Sveltos — Quick‑Start & Reference Guide

1 What is Sveltos?

Sveltos is a set of Kubernetes controllers that run in a management cluster. From that central control‑plane it installs, updates, and deletes Kubernetes add‑ons and applications across any number of managed clusters. The project extends Cluster API and supports declarative, multi‑tenant, and GitOps workflows at scale.

Key capabilities

• Deploy Helm charts, raw YAML/JSON, Kustomize, Carvel ytt, and Jsonnet packages
• Two installation modes (with or without lightweight agents inside managed clusters)
• Dry‑run simulations and drift detection
• Configuration snapshots with diff/rollback
• Optional web dashboard and Grafana monitoring

2 Prerequisites

Install the following locally before running the quick‑start demo:

• Docker https://docs.docker.com/engine/install/
• Go (required to build helper scripts) https://go.dev/doc/install
• kubectl https://kubernetes.io/docs/tasks/tools/#kubectl

3 Hands‑On Quick‑Start (Kind)

Clone the add‑on controller repository and launch the scripted environment:

$ git clone https://github.com/projectsveltos/addon-controller && cd addon-controller/
$ make quickstart

The script creates:

1. A Kind‑based management cluster (sveltos-management)
2. Cluster API components inside that cluster
3. Sveltos controllers inside that cluster
4. A workload cluster (clusterapi-workload) provisioned by Cluster API (Docker provider)

Wait a few minutes for all pods to reach Running.

Verify the topology

$ kind get clusters
clusterapi-workload
sveltos-management

$ kubectl config set-context kind-sveltos-management
$ kind export kubeconfig --name sveltos-management
$ kubectl get clusters --show-labels
NAME                  PHASE         VERSION   LABELS
clusterapi-workload   Provisioned   v1.32.0   env=fv,sveltos-agent=present

4 Installing Sveltos in Production

Sveltos supports two deployment modes and both Helm and Kustomize installers.

4.1 Modes

Manifest examples

Mode 1:

$ kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/v0.57.2/manifest/manifest.yaml
$ kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/v0.57.2/manifest/default-instances.yaml

Mode 2:

$ kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/v0.57.2/manifest/agents_in_mgmt_cluster_manifest.yaml
$ kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/v0.57.2/manifest/default-instances.yaml

Note Both manifests install Sveltos in the projectsveltos namespace.

4.2 Helm installation

Add the chart repository and refresh indices:

$ helm repo add projectsveltos https://projectsveltos.github.io/helm-charts
$ helm repo update

Install Mode 1:

$ helm install projectsveltos projectsveltos/projectsveltos \
    -n projectsveltos --create-namespace

Install Mode 2:

$ helm install projectsveltos projectsveltos/projectsveltos \
    -n projectsveltos --create-namespace \
    --set agent.managementCluster=true

CRD upgrades Helm will not auto‑upgrade CRDs. Update them manually:

$ kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/v0.57.2/manifest/crds/sveltos_crds.yaml

4.3 Kustomize installation

Mode 1:

$ kustomize build \
    https://github.com/projectsveltos/sveltos.git//kustomize/base?ref=v0.57.2 | kubectl apply -f -
$ kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/v0.57.2/manifest/default-instances.yaml

Mode 2:

$ kustomize build \
    https://github.com/projectsveltos/sveltos.git//kustomize/overlays/agentless-mode?ref=v0.57.2 | kubectl apply -f -
$ kubectl apply -f https://raw.githubusercontent.com/projectsveltos/sveltos/v0.57.2/manifest/default-instances.yaml

5 Deploying Workloads with Sveltos

5.1 Helm charts (ClusterProfile)

The following ClusterProfile installs Kyverno in every cluster labeled env=fv.

apiVersion: config.projectsveltos.io/v1beta1
kind: ClusterProfile
metadata:
  name: deploy-kyverno
spec:
  clusterSelector:
    matchLabels:
      env: fv
  syncMode: Continuous
  helmCharts:
  - repositoryURL:    https://kyverno.github.io/kyverno/
    repositoryName:   kyverno
    chartName:        kyverno/kyverno
    chartVersion:     v3.3.7
    releaseName:      kyverno-latest
    releaseNamespace: kyverno
    helmChartAction:  Install

Apply:

$ kubectl apply -f clusterprofile_kyverno.yaml

Switch to the workload context and confirm pods are running:

$ kubectl config set-context kind-clusterapi-workload
$ kind export kubeconfig --name clusterapi-workload
$ kubectl get pods -n kyverno

5.2 Raw YAML / JSON via ConfigMap

1. Create the resource definitions (here: an nginx Deployment and Service):

   # nginx_deploy.yaml
   apiVersion: v1
   kind: Namespace
   metadata:
     name: dev
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nginx
     namespace: dev
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: nginx
     template:
       metadata:
         labels:
           app: nginx
       spec:
         containers:
         - name: nginx
           image: nginx:latest
           ports:
           - containerPort: 80
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: nginx-service
     namespace: dev
   spec:
     selector:
       app: nginx
     ports:
     - protocol: TCP
       port: 80
       targetPort: 80
     type: ClusterIP
   

2. Store the file in a ConfigMap:

   $ kubectl create configmap nginx --from-file=nginx_deploy.yaml
   

3. Reference that ConfigMap from a ClusterProfile:

   apiVersion: config.projectsveltos.io/v1beta1
   kind: ClusterProfile
   metadata:
     name: nginx-deploy
   spec:
     clusterSelector:
       matchLabels:
         env: fv
     syncMode: Continuous
     policyRefs:
     - name: nginx
       namespace: default
       kind: ConfigMap
   

4. Apply it:

   $ kubectl apply -f clusterprofile_nginx.yaml
   

5.3 GitOps with FluxCD (Kustomize)

Sveltos can point at Flux‑managed GitRepository, OCIRepository, or Bucket objects and apply individual paths. Example:

apiVersion: config.projectsveltos.io/v1beta1
kind: ClusterProfile
metadata:
  name: flux-system
spec:
  clusterSelector:
    matchLabels:
      env: fv
  syncMode: Continuous
  kustomizationRefs:
  - namespace: flux-system
    name: flux-system
    kind: GitRepository
    path: ./helloWorld/
    targetNamespace: eng

For additional template mechanisms see the Carvel ytt and Jsonnet extensions (links preserved in original docs).

6 Air‑Gapped & Private Registry Support

When clusters cannot reach public registries you can patch the agent and drift‑detection manager deployments via Helm values.

Example: patch drift‑detection‑manager image

addonController:
  driftDetectionManagerPatchConfigMap:
    data:
      patch: |-
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: drift-detection-manager
        spec:
          template:
            spec:
              imagePullSecrets:
              - name: my-registry-secret
              containers:
              - name: manager
                image: registry.company.io/projectsveltos/drift-detection-manager:dev

Example: patch sveltos‑agent image (JSON Patch)

classifierManager:
  agentPatchConfigMap:
    data:
      image-patch: |-
        - op: replace
          path: /spec/template/spec/containers/0/image
          value: registry.company.io/projectsveltos/sveltos-agent:dev
        - op: add
          path: /spec/template/spec/imagePullSecrets
          value:
            - name: my-registry-secret

Provide the patched values file when installing the chart:

$ helm install projectsveltos projectsveltos/projectsveltos \
    -n projectsveltos --create-namespace -f custom_values.yaml

7 sveltosctl — Command‑Line Interface

7.1 Installation options

• Pre‑built binaries: GitHub Releases page
• As a Pod: manifest/sveltosctl_manifest.yaml (requires a PersistentVolume)

7.2 Common queries

# List add‑ons per cluster
$ sveltosctl show addons

# Filter by selector
$ sveltosctl show addons --namespace default --clusterprofile deploy-kyverno

# List arbitrary resources in managed clusters
$ sveltosctl show resources --kind=Pod --namespace=nginx

# Show which clusters match a ClusterProfile and where ConfigMaps are applied
$ sveltosctl show usage

# Display RBAC rights granted to tenant admins
$ sveltosctl show admin-rbac

8 Advanced Workflow Features

8.1 Dry‑Run Sync Mode

Set spec.syncMode: DryRun in a ClusterProfile to simulate all operations. After reconciliation, inspect results:

$ sveltosctl show dryrun --raw-diff

Dry‑run reports include object‑level actions (Install/Upgrade/Delete) and Helm value diffs.

8.2 Configuration Snapshots & Rollback

• Define a Snapshot CRD with a cron‑style schedule and storage path.
• Use sveltosctl snapshot diff to compare two timestamps.
• Roll back full or partial configuration states:

$ sveltosctl snapshot rollback --snapshot=hourly --sample=2023-08-26:05:00:00

8.3 Drift Detection (ContinuousWithDriftDetection)

Enable in a ClusterProfile to surface divergences between desired and live state. Detected drifts are exposed via Prometheus metrics and sveltosctl show dryrun.

9 Observability & UI Add‑Ons

9.1 Sveltos Dashboard (optional)

Install via manifest or Helm chart, then expose the dashboard Service. Authenticate with a Kubernetes service‑account token. See install commands in section How to install Sveltos dashboard of the original docs.

9.2 Grafana Dashboard

With Prometheus and Grafana installed on the management cluster, import the JSON dashboard at: https://raw.githubusercontent.com/projectsveltos/sveltos/main/docs/assets/sveltosgrafanadashboard.json

Key metrics include cluster connectivity, reconcile counts, drift totals, and histogram buckets for deployment durations.

Telemetry Opt‑Out

Sveltos collects minimal anonymised data (versions, counts of managed objects). Disable with:

# Helm
helm install projectsveltos projectsveltos/projectsveltos \
  -n projectsveltos --create-namespace \
  --set telemetry.disabled=true

# Manifest deployments
--disable-telemetry=true  # flag on addon‑controller