Zum Inhalt springen
Produkte

// 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

  1. On a location → Resources → New resource, kind k8s_cluster.
  2. Paste the cluster's kubeconfig as the credential (or pick an existing k8s credential). The address is taken from the kubeconfig's server: line.
  3. 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, with ready/desired replica 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).

// Zusammenarbeit

Bereit, Ihre digitale Infrastruktur zu bauen?

Ob individuelle Automatisierung für Ihr Unternehmen oder ein durchgeplantes Netzwerk für Ihr Zuhause — lassen Sie uns über das Projekt sprechen.