Skip to main content
A fleet’s Lumovi reaches each cluster with credentials that may only impersonate: it acts as whoever signed in, and the cluster applies their RBAC. The Helm chart makes them in the cluster you add, and prints the kubeconfig entry to give Lumovi. This is for clusters whose API server Lumovi can reach. For a cluster in a network it can’t reach, run an agent there instead.

With the Helm chart

1

Install the chart as a member

With your kubeconfig pointing at the cluster to add:
mode: member makes no Lumovi in this cluster, only what the fleet’s Lumovi needs here, named after the release:
  • a service account, lumovi,
  • a ClusterRole and a ClusterRoleBinding, lumovi-impersonate, that let it impersonate users and groups, and nothing else,
  • a Secret, lumovi-token, in which Kubernetes keeps a token for the service account that doesn’t expire.
clusterName is what the fleet calls the cluster. With rbac.create: false, the chart makes no ClusterRole or binding, and you give the service account the same permission yourself. Creating them needs an account that may impersonate users and groups itself, or has the escalate and bind verbs on cluster roles: a cluster administrator has these.
2

Get its kubeconfig entry

The chart’s notes, printed after helm install, start with prod-eu can join a fleet now, and have two commands. They print a kubeconfig with the cluster’s address (as your kubeconfig has it), its certificate authority, and the token. Here, they write it to prod-eu.yaml:
helm get notes lumovi --namespace lumovi prints them again later. If Lumovi reaches the cluster at another address than yours, change server. The API server’s certificate must be valid for that address, or set tls-server-name to a name it’s valid for.
3

Add it to the fleet's kubeconfig

Copy its cluster, user and context into the fleet’s kubeconfig, and give the context Lumovi’s settings for it, if you want any:
fleet.yaml
See Settings for each cluster.
4

Give Lumovi the new kubeconfig

In a Secret (fleet.kubeconfigSecret), replace it, with your kubeconfig pointing at the fleet’s cluster:
Lumovi reads it again by itself, and the log says Fleet: prod-eu added. In LUMOVI_FLEET_KUBECONFIG, change the setting, and restart Lumovi.Or, when Lumovi reads Secrets, give the cluster a Secret of its own instead, with prod-eu.yaml as it is, and its settings as annotations: see Clusters from Secrets.
Whoever has the token can act as anyone in the cluster. Keep the fleet’s kubeconfig only where its administrators can read it. Deleting the lumovi-token Secret revokes the token, and so does uninstalling the release.

From the Fleet page

Where the server allows it (the chart’s fleet.addFromPage, off unless you set it), Lumovi’s admins add a cluster on the Fleet page, with the credentials the chart made, or any that may impersonate: Add cluster, then Paste a kubeconfig… or Use a token… (a server’s address, a token and its CA). It needs Lumovi to have admins, and to keep its state across restarts. Check it checks, in order:
  • It reads: a kubeconfig of one context, with its cluster and user.
  • What it signs in with is in it: no credential plugin (an exec user, or an auth provider), since Lumovi’s server runs no programs, and no files on someone’s computer. Use the -data fields, or a token.
  • Its server is https, checked against its certificate authority: never insecure-skip-tls-verify.
  • The server answers, and the credentials work, and they may impersonate users and groups, so Lumovi acts as whoever signs in, as with the chart’s.
A check that fails says what’s wrong, with what to do: a client certificate or key that isn’t one; a server certificate for another name (with the names it gives, to connect to one of them or set tls-server-name), not signed by the certificate authority given (or, with none given, by one Lumovi’s server trusts), expired, or not valid yet (check the server’s clock). “The server doesn’t answer” means only that it couldn’t be reached in time. Two things are pointed out, but not refused: a cluster reached through a proxy (its proxy-url, shown by its host), and credentials that may do anything there, not only act as each person. A service account that may only impersonate, as the chart makes, is safer. The check reaches the address it’s given over https, from inside the network Lumovi runs in, and shows what the server answers: only admins can ask it to. Then give it a Name, Labels and Groups, who sees it besides admins. Lumovi keeps it as a Secret of its own, lumovi-cluster-<name>, labelled lumovi.dev/cluster, in a namespace kept for them, fleet.addNamespace: <release namespace>-clusters unless set, like lumovi-clusters. The chart makes it (unless fleet.createAddNamespace is false), and keeps it when the release is uninstalled, with the clusters in it: delete it to let them go. To install Lumovi again under another release name, and keep them, see fleet.createAddNamespace in Helm values. Lumovi reads there only the Secrets it made, by their UID, as it reads any such Secret: someone else’s there isn’t a cluster, unless fleet.secrets and fleet.secretNamespaces name that namespace. It never replaces a Secret it didn’t make, and if it can’t record one it just made, it deletes it again. Each one added is in the audit log, as cluster.added. A cluster added this way has Remove from the fleet… in its settings. Lumovi deletes the Secret it made, that one only: if it was made again since, by someone else, it’s left as it is.
With fleet.addFromPage on, Lumovi may list, create and delete Secrets in that namespace, and nowhere else: never in its own. The clusters’ credentials it keeps there are as strong as what they may do in each cluster: see A fleet. Whoever controls Lumovi, or may read that namespace’s Secrets, controls them too. Give each cluster credentials that may only impersonate, as the chart’s do, and keep that namespace, like Lumovi’s own, to the administrators of every one of its clusters.

Without the chart

The same objects, for kubectl apply:
member.yaml
The first is the user’s token, and the second, as it is, the cluster’s certificate-authority-data. Applying them needs the same permissions as installing the chart: an account that may impersonate users and groups itself, or has the escalate and bind verbs on cluster roles.

A fleet of clusters

The kubeconfig, its settings, and the fleet page.

Private clusters

When Lumovi can’t reach the cluster’s API server.