// Benutzung · Steuerung
Managing a Kubernetes cluster
Add a Kubernetes cluster as a resource and Fleeger enumerates the whole thing — nodes, namespaces, workloads, services, ingresses, storage, jobs, and cert-manager objects (certificates, orders, issuers) — with live status, and lets you run a handful of control actions from the UI.
Onboarding a cluster
- On a location → Resources → New resource, kind k8s_cluster.
- Paste the cluster's kubeconfig as the credential (or pick an existing
k8scredential). The address is taken from the kubeconfig'sserver:line. - Save. On its next cycle the agent lists the cluster and the objects appear under Kubernetes on the Resources tab.
The kubeconfig's user needs cluster-wide read for discovery; the control actions below additionally need write on the relevant objects.
The kubeconfig must carry its credentials inline: a token,
username/password, or client-certificate-data and client-key-data, with
the CA as certificate-authority-data. Fleeger refuses, with a 400 when you
save it, a kubeconfig that would make the agent run a command or read one of
its own files: a user with exec (as aws eks, gke-gcloud-auth-plugin and
kubelogin kubeconfigs have) or auth-provider, or a path in tokenFile,
client-certificate, client-key or certificate-authority. The agent runs
with its own NATS identity and ServiceAccount, and for the bundled core agent
inside the hub, so anyone who may store a credential could otherwise run code
there. For a cloud cluster, create a ServiceAccount with the read
ClusterRole and use a token for it (kubectl create token, or a long-lived
kubernetes.io/service-account-token Secret). A kubeconfig stored before this
check is refused by the agent instead: the cluster's resource shows a collect
error starting kubeconfig refused: that names the user or cluster and the
field, and is not collected (nor its control actions run) until its credential
is replaced.
A kubeconfig that sets proxy-url is refused too, when it is stored and by
the agent, without repeating the URL: the agent has no proxy support,
and its Kubernetes client ignores HTTPS_PROXY/https_proxy in its
environment, in-cluster too. One exception: kube reads that variable while it
loads a stored kubeconfig, before the agent can drop it, so a value that is
not a valid URL fails every stored kubeconfig with failed to parse proxy url; unset or fix it. A kubeconfig whose users[].user or
clusters[].cluster is not a mapping is refused as well, and so is one that
is not valid YAML; the message then quotes no line of it.
At a location the bundled core agent collects (local_collector), the
kubeconfig's server may not be one of the hub's own services: by name, by an
address the name resolves to, loopback, link-local, or (when the hub runs on
Kubernetes) the hub cluster's own API at kubernetes.default.svc or its
service address. Such a cluster is not collected, and shows a collect
error starting refused: that names the field; its control actions are
refused the same way, before anything is sent. The agent then connects to the
address it checked, so a DNS answer that changes in between cannot redirect
it. See
It never probes the hub itself.
A remote spoke judges nothing: its location's own network is what it reaches.
In-cluster
A k8s_cluster registered without a credential is collected in-cluster:
the agent reads the cluster it runs in with its own ServiceAccount, and the
shipped ClusterRoles grant it the read surface. For a remote spoke that is the
spoke's own cluster, and any user who may create resources at its location
may register it. At a local_collector location it is the hub's own
cluster, read by the core agent, so there only a user holding
location.edit on all locations may register one, or make one by changing a
credential-less resource's kind, detaching a cluster's kubeconfig, or rolling
back to a checkpoint that has one; anyone else gets a 403 and attaches
a kubeconfig instead. Clusters an administrator registered stay editable by
location users. The core agent collects in-cluster only a registration with no
credential: one whose credential has no kubeconfig is not collected, with a
collect error starting refused:, where a remote spoke still reads it as
in-cluster.
Node and object names are unique only within a cluster, so the agent keys each
discovered object on its cluster as well: the UID of the cluster's
kube-system namespace, which it takes from the namespace list it makes every
cycle (and, only when that list fails, from a get of kube-system; the
shipped ClusterRoles grant both). Two clusters in one location that both have a
node n1 or a namespace default therefore show one resource each, and the
same cluster registered twice still shares its objects: each is one resource,
also while two inventory-svc processes handle its two registrations' reports
at once. If the agent cannot
read kube-system's UID, it still reports metrics but no objects, and the
cluster's resource shows the collect error cannot tell which cluster it is;
its objects are no longer refreshed (and are removed if discovery retention is
enabled).
Upgrading from rc.2 or earlier with one cluster registered twice in a location: the first upgraded collection can create new resources for the registration that reports first, and the old ones, with their checks and alerts, are left behind (and are removed if discovery retention is enabled). Remove the duplicate registration before upgrading, or re-attach the checks and alerts to the new resources afterwards.
Metric series, alerts and pod logs are keyed on their cluster through the
cluster label, so two clusters' same-named node, workload or pod keep
their series apart; see the rc.3 upgrade notes.
What you see
Objects are grouped by kind, each with a status badge:
- Workloads (Deployments/StatefulSets/DaemonSets) —
ready/degraded/scaled-zero, withready/desiredreplica counts. - Certificates (cert-manager) —
valid/expiring(within 14 days) /expired/notready, the DNS names, the issuer, and when it expires. - Namespaces, Services (type + ports), Ingresses (hosts + TLS), PVCs (phase + capacity), Jobs/CronJobs, HPAs, and the cert-manager Orders / CertificateRequests / Issuers.
- Pods are shown live (from metrics), grouped by namespace — not stored as inventory rows (a busy cluster churns thousands).
Clusters without cert-manager simply show no certificate sections — the agent skips CRDs that aren't installed.
Control actions
Buttons appear on the controllable kinds:
| Kind | Actions |
|---|---|
| Deployment / StatefulSet | Scale (set replicas), Restart (rollout) |
| DaemonSet | Restart |
| Node | Cordon / Uncordon |
| Pod | Delete (force a reschedule) |
| Certificate | Reissue (triggers cert-manager renewal) |
Restart bumps the pod-template restartedAt annotation (same as
kubectl rollout restart). Reissue sets the Issuing condition on the
Certificate (same as cmctl renew) — cert-manager then requests a fresh cert.
Actions are disabled while the location's agent is unreachable.
Each action goes to the cluster its object belongs to, using that cluster's
kubeconfig: a workload, node or certificate's own cluster registration, and for
a pod, the registration whose discovered objects carry the pod's cluster
label (k8s-cluster:<uid>, or registration:<inventory id> directly). With
two clusters in one location, deleting cluster B's default/nginx deletes B's
pod, and the confirmation names the cluster. An action whose cluster cannot be
told is not sent, and the page says why: the cluster's registration was
deleted (reload the page); no discovered object carries the pod's
k8s-cluster: label yet (the first cycles after an upgrade, or discovery
failing), even with a single cluster; the pod has no cluster label (an agent
older than rc.3) and the location has more than one k8s cluster; or the
location's resources changed between the confirmation and the send.
With the same cluster registered twice (or a registration edited away from a cluster another one now reaches), an action uses the kubeconfig and RBAC of one registration:
- a workload, node or certificate's action goes through the registration that last reported that object (its parent);
- a pod's action goes through the registration that reported the pod's cluster
most recently: of the objects carrying the pod's
k8s-cluster:label, the one discovered last names it (on a tie, the smallest registration id). An object a registration no longer reports keeps its old parent, but it stops being refreshed, so it does not outrank the current one.
The action also names the cluster it is meant for (k8s-cluster:<uid>, in the
command's cluster param, recorded in the audit log). Before changing
anything, the agent reads kube-system through the registration's kubeconfig
and refuses the action if that is a different cluster, or if it cannot read it
(the kubeconfig needs get on the kube-system namespace, which the shipped
ClusterRoles grant). That catches a registration edited to reach another
cluster and stale objects still filed under an old registration. Pods labeled
registration:<id> and objects without a scope (an agent older than rc.3) are
sent without it and act on whatever the kubeconfig reaches. An agent older than
rc.3 ignores the param, so this check needs the upgraded agent.
Verifying
The result lands in the Agents tab → Control path audit log, and the object's status refreshes on the next agent cycle (nudged automatically after the action).