Docs

Clusters

What this screen is for

The Clusters tab is the registry of every Kubernetes cluster Fenwave can deploy to, inspect, or install addons on.

This registry is the source of truth

Fenwave reads clusters from here. Static configuration files are consulted only when this registry is empty. A cluster that seems to be missing is nearly always unregistered rather than misconfigured — and adding it to a config file will not help while this registry has any entry at all.

Before you start

To do this You need
See the tab platform-settings.cluster.read
Register a cluster platform-settings.cluster.create
Edit one platform-settings.cluster.update
Unregister one platform-settings.cluster.delete
Validate one platform-settings.cluster.validate

Register the cloud account first if the cluster will authenticate through it.

Opening it

  1. Settings › Infrastructure
  2. Select the Clusters tab.

The interface

📸 Screenshot Placeholder: The Clusters tab with two clusters. Mark: (1) Add button, (2) the status badge showing Valid, (3) the Last Validated column, (4) the validate action, (5) the unregister action.

# Control What it does When you’d use it
1 Add Opens the cluster dialog Registering a cluster
2 Status badge Valid, Invalid, or Pending The first thing to read
3 Last Validated When validation last succeeded Spotting stale registrations
4 Validate Tests the connection now After any credential or network change
5 Unregister Removes it from Fenwave Decommissioning

Unregistering asks for confirmation. It removes Fenwave’s record — it does not touch the cluster itself.

Authentication methods

Method For Notes
Service Account Token Any cluster Simplest. A long-lived secret you must rotate yourself
AWS EKS, using a registered AWS credential Depends on that credential staying valid
AWS EKS with IRSA EKS, classic OIDC No long-lived secret
EKS Pod Identity EKS No long-lived secret
In-Cluster The cluster Fenwave itself runs on Uses the pod’s own identity
Google GKE GKE, using a registered GCP credential Depends on that credential
Workload Identity GKE No long-lived secret

Prefer the methods with no long-lived secret — IRSA, Pod Identity, Workload Identity, In-Cluster. A service account token works immediately and then becomes something you have to remember to rotate.

Walkthroughs

Register an EKS cluster with IRSA

Requires platform-settings.cluster.create and .validate.

  1. Settings › Infrastructure › Clusters, click Add.
  2. Name the cluster as your teams refer to it — this name appears in policy scope selectors and deployment targets.
  3. Choose AWS EKS with IRSA as the authentication method.
  4. Fill in the remaining fields.
  5. Save, then validate.
  6. Confirm the status badge reads Valid. Pending means it has not been proven; treat it as not done.

Register the cluster Fenwave runs on

Choose In-Cluster. It uses the platform pod’s own identity, so there is no credential to supply or rotate.

Validate after a change

Requires platform-settings.cluster.validate.

Validate whenever the underlying cloud credential rotates, the cluster endpoint moves, or network policy changes. Last Validated tells you how much you can trust the current status.

Scenario

“Our cluster isn’t in the dropdown.”

A team reports their cluster is missing when they try to scope a policy or pick a deployment target.

  1. Settings › Infrastructure › Clusters — is it listed at all?
    • Not listed → it was never registered. Register it. Adding it to a configuration file will not work: this registry takes precedence whenever it is non-empty.
    • Listed → continue.
  2. Read the status badge.
    • Pending → registered but never validated. Click validate.
    • Invalid → validate to get the current error.
  3. If validation fails, check the cloud credential it authenticates through. A cluster cannot be valid while its credential is not.
  4. Once the badge reads Valid, re-check the policy scope selector — the cluster should now appear.
  5. If the user still cannot see it, the problem is their permissions rather than the registration. Check Access Explorer.

Step 5 matters: “missing from the dropdown” has two completely different causes — not registered, or not permitted — and they are indistinguishable to the person reporting it.

When it doesn’t work

Symptom Cause How to check Fix
Cluster absent everywhere in Fenwave Not registered here This tab Register it; config files are ignored while this registry is non-empty
Status stuck at Pending Never validated The status badge Click validate
Status Invalid after a cloud change The underlying credential rotated Cloud Fix the credential, then revalidate the cluster
Registered and valid, but a user cannot select it Their permissions, not the cluster Access Explorer Grant a policy scoped to that cluster
Cannot validate although you can edit Validation is its own permission Access Explorer Ask for platform-settings.cluster.validate
Unregistered by mistake The record is removed; the cluster is untouched — Register it again

Next