Cluster Registration Tokens¶
Not needed for Manager initiated registration
For manager initiated registrations the token is managed by the Fleet manager and does not need to be manually created and obtained.
For an agent initiated registration the downstream cluster must have a cluster registration token.
Cluster registration tokens are used to establish a new identity for a cluster. Internally
cluster registration tokens are managed by creating Kubernetes service accounts that have the
permissions to create ClusterRegistrationRequests
within a specific namespace. Once the
cluster is registered a new ServiceAccount
is created for that cluster that is used as
the unique identity of the cluster. The agent is designed to forget the cluster registration
token after registration. While the agent will not maintain a reference to the cluster registration
token after a successful registration please note that usually other system bootstrap scripts do.
Since the cluster registration token is forgotten, if you need to re-register a cluster you must give the cluster a new registration token.
Token TTL¶
Cluster registration tokens can be reused by any cluster in a namespace. The tokens can be given a TTL such that it will expire after a specific time.
Create a new Token¶
The ClusterRegistationToken
is a namespaced type and should be created in the same namespace
in which you will create GitRepo
and ClusterGroup
resources. For in depth details on how namespaces
are used in Fleet refer to the documentation on namespaces. Create a new
token with the below YAML.
kind: ClusterRegistrationToken
apiVersion: "fleet.cattle.io/v1alpha1"
metadata:
name: new-token
namespace: clusters
spec:
# A duration string for how long this token is valid for. A value <= 0 or null means infinite time.
ttl: 240h
Obtaining Token Value (Agent values.yaml)¶
The token value is the contents of a values.yaml
file that is expected to be passed to helm install
to install the Fleet agent on a downstream cluster. The token is stored in a Kubernetes secret referenced
by the status.secretName
field on the newly created ClusterRegistrationToken
. In practice the secret
name is always the same as the ClusterRegistrationToken
name. The contents will be in
the secret's data key values
. To obtain the values.yaml
content for the above example YAML one can
run the following one-liner.
kubectl -n clusters get secret new-token -o 'jsonpath={.data.values}' | base64 --decode > values.yaml
This values.yaml
file can now be used repeatedly by clusters to register until the TTL expires.