Registration
Sveltos Cluster Registration
Sveltos supports automatic discovery of ClusterAPI powered clusters. If Sveltos is deployed in a management cluster with ClusterAPI (CAPI), no further action is required for add-ons management. It will watch for clusters.cluster.x-k8s.io instances and program those accordingly.
Sveltos can manage Kubernetes add-ons to any cluster seamlessly (on-prem, Cloud).
Register Cluster
sveltosctl Registration
To register Kubernetes clusters with Sveltos, it is recommended, but not required, to use the sveltosctl. Alternatively, to programmatically register clusters, consult the section.
If the kubeconfig
has multiple contexes, and the default context points to the management cluster, use the --fleet-cluster-context option. This option sets the name of the context that points to the cluster to be registered. The below example will generate a kubeconfig file and register the cluster with Sveltos.
$ sveltosctl register cluster \
--namespace=<namespace> \
--cluster=<cluster name> \
--fleet-cluster-context=<context name> \
--labels=key1=value1,key2=value2
Alternative Sveltos Cluster Registration
If a different kubeconfig
is needed, users can utilise the sveltosctl generate kubeconfig
command. It allows Sveltos to create the required ServiceAccount
alongside the kubeconfig
. To proceed with the registration process, follow the steps listed below.
- Generate the kubeconfig: Use the
sveltosctl generate kubeconfig
command while pointing it to the cluster you want Sveltos to manage. The command will create a ServiceAccount withcluster-admin
permissions and generate the kubeconfig based on it. 1 - Register the Cluster: Use the
sveltosctl register cluster
pointing it to the Sveltos management cluster. Provide the following options:--namespace=<namespace>
: Namespace in the management cluster where Sveltos will store information about the registered cluster.--cluster=<cluster name>
: A chosen name to identify the registered cluster within Sveltos.--kubeconfig=<path to file with Kubeconfig>
: Path to the kubeconfig file generated in step 1.--labels=<key1=value1,key2=value2>
(Optional): Comma-separated key-value pairs to define labels for the registered cluster (e.g., --labels=environment=production,tier=backend).
Registration Example
Pointing to the managed cluster (Generate kubeconfig with ServiceAccount creation):
$ sveltosctl generate kubeconfig --create > ~/.kube/prod-cluster.config
Pointing to the management cluster (Register the cluster):
$ sveltosctl register cluster \
--namespace=monitoring \
--cluster=prod-cluster \
--kubeconfig=~/.kube/prod-cluster.config \
--labels=environment=production,tier=backend
The example will register a cluster (i.e, creates a SveltosCluster instance) named prod-cluster in the monitoring namespace with the labels set to "environment=production" and "tier=backend".
If later on you want to change the labels assigned to the cluster, use the kubectl command below.
$ kubectl edit sveltoscluster prod-cluster -n monitoring
Registration Examples
EKS
Once an EKS cluster is created, perform the below steps.
-
Retrieve the
kubeconfig
file with the AWS CLI. -
Generate Sveltos Relevant Kubeconfig
-
Register EKS with Sveltos
Tip
For Step #2, Sveltos will have cluster-admin privileges to the cluster.
GKE
- Pointing to GKE cluster, run sveltosctl generate kubeconfig --create --expirationSeconds=86400
- Run sveltosctl register cluster command pointing it to the kubeconfig file generated by the step above.
Tip
Step #1 gives Sveltos cluster-admin privileges (that is done because we do not know in advance which add-ons we want Sveltos to deploy). We might choose to give Sveltos fewer privileges. Just keep in mind it needs enough privileges to deploy the add-ons you request to deploy.
Rancher RKE2
If you use Rancher's next-generation Kubernetes distribution RKE2, you will only need to download the kubeconfig either from the Rancher UI under the Cluster Management section or via SSH into the RKE2 Cluster and under the /etc/rancher/rke2/rke2.yaml directory. Run the below command.
Civo
If you use Civo Cloud, simply download the cluster Kubeconfig and perform the below.
Kamaji
If you use the Hosted Control Plane solution Kamaji, follow steps below below to perform a tenant cluster registration with Sveltos.
- Point the kubeconfig to the Kamaji Management Cluster
- Check the secrets in the namespace the tenant cluster was created
- Look for the secret with the following name format
<tenant_name>-admin-kubeconfig
- Get and decode the secret to a file of your preference
- Perform a Sveltos registration Example
vCluster
If you use vCluster with Helm for multi-tenancy, follow the steps below to perform a cluster registration with Sveltos.
- Point the kubeconfig to the parent Kubernetes cluster
- Check the secrets in the namespace the virtual cluster was created
- Look for the secret with the following name format
vc-<vcluster name>
- Get and decode the secret to a file of your preference
- Perform a Sveltos registration Example
Programmatic Registration
To programmatically register clusters with Sveltos, create the below resources in the management cluster.
- Secret: Store the kubeconfig of the managed cluster in the data section under the key
kubeconfig
. - SveltosCluster: Represent your cluster as an
SveltosCluster
instance.
By default, Sveltos searches for a Secret
named <cluster-name>-sveltos-kubeconfig
in the same namespace as the SveltosCluster. To use a different Secret name, set the SveltosCluster.Spec.KubeconfigName field to the desired name.
Kubernetes Resources Example
Secret Resource
SveltosCluster ResourceTip
To get an idea on how an already registered cluster looks like, check out the Sveltos mgmt
cluster using the command kubectl get sveltoscluster mgmt -n mgmt -o yaml
.
-
As an alternative to generate kubeconfig have a look at the script: get-kubeconfig.sh. Read the script comments to get more clarity on the use and expected outcomes. This script was developed by Gravitational Teleport. We simply slightly modified to fit Sveltos use case. ↩
-
To manage add-ons and deployments on the management cluster, by default, Sveltos automatically registers the cluster as
mgmt
in themgmt
namespace. Follow the standard Sveltos label concept to mark it for deployments. ↩