Skip to content

Register Cluster

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 Sveltos to manage add-ons. It will watch for instances and program those accordingly.

Other clusters (on-prem, Cloud) can be registered with Sveltos easily. Sveltos can manage Kubernetes add-ons on all the clusters seamlessly.

Register Cluster

The instructions below will walk readers through registering an existing Kubernetes cluster with Sveltos for management. It is recommended, but not required, to use the sveltosctl to register a cluster.

If the kubeconfig in place has multiple contexts, 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 you want to register.

$ sveltosctl register cluster --namespace=<namespace> --cluster=<cluster name> --fleet-cluster-context=<context name> --labels=key1=value1,key2=value2

The above command will generate a kubeconfig file and register the cluster with Sveltos.

Alternatively, if a different kubeconfig is needed for the managed cluster registration, 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.

  1. 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 with cluster-admin permissions and generate the kubeconfig based on it. 1
  2. 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 \

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

Note: The command assumes you have kubectl configured to access the Sveltos management cluster.

Register Civo Cluster

If you use Civo Cloud, simply download the cluster Kubeconfig and perform the below.

$ sveltosctl register cluster --namespace=<namespace> --cluster=<cluster name> \
    --kubeconfig=<path to file with Kubeconfig>

Register GKE Cluster

  1. Pointing to GKE cluster, run sveltosctl generate kubeconfig --create --expirationSeconds=86400
  2. Run sveltosctl register cluster command pointing it to the kubeconfig file generated by the step above.

Note: 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.

Note: To register an EKS cluster, we will have to generate a new kubeconfig like in step #1. Once this is done, the kubeconfig can be used to perform the Sveltos registration.

Register RKE2 Cluster

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.

$ sveltosctl register cluster --namespace=<namespace> --cluster=<cluster name> \
    --kubeconfig=<path to file with Kubeconfig>

Register vCluster

If you use vCluster with Helm for multitenancy, follow the steps below to perform a cluster registration with Sveltos.

  1. Point the kubeconfig to the parent Kubernetes cluster
    $ export KUBECONFIG=~/demo/vcluster/multi-tenant/kubeconfig/demo01.yaml
  2. Check the secrets in the namespace the virtual cluster was created
    $ kubectl get secrets -n {your namespace}
  3. Look for the secret with the following name format vc-<vcluster name>
  4. Get and decode the secret to a file of your preference
    $ kubectl get secret vc-vcluster-dev -n dev --template={{.data.config}} | base64 -d > ~/demo/vcluster/multi-tenant/kubeconfig/vcluster-dev.yaml
  5. Perform a Sveltos registration
    $ sveltosctl register cluster --namespace=<namespace> --cluster=<cluster name> \
        --kubeconfig=<path to file with Kubeconfig> --labels=key1=value1,key2=value2
    $ sveltosctl register cluster --namespace=projectsveltos --cluster=vcluster-dev --kubeconfig=~/demo/vcluster/multi-tenant/kubeconfig/vcluster-dev.yaml --labels=env=dev

  1. Note: As an alternative to generate kubeconfig have a look at the script: 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.