Introduction to Sveltos Architecture

Sveltos is a set of Kubernetes controllers that all run in a single management cluster. They deploy and manage add-ons across a fleet of managed clusters. This page describes what each component does, which ones can be removed (no mandatory ones), and how the two deployment modes (agent, agentless) differ in the permissions they require on managed clusters.

Entry Point

Sveltos has no separate API server. The Kubernetes API of the management cluster is the only entry point. All Sveltos resources like ClusterProfile, Classifier, EventTrigger, SveltosCluster, and the rest are Kubernetes custom resources. Users interact with them using kubectl, Helm, or any GitOps controller pointed at the management cluster. Standard Kubernetes RBAC controls who can read and write Sveltos resources.

Cluster Discovery and Registration

Sveltos supports several ways to bring a cluster under management: providing a kubeconfig Secret, using cloud workload identity (AWS IRSA, GKE Workload Identity), pull mode for clusters not reachable from the management cluster, and automatic discovery of Cluster API Cluster objects. See Register a Cluster for details on each approach.

Profiles target clusters by label selectors. A ClusterProfile does not name specific clusters; it declares which labels a cluster must carry. When a cluster is registered and its labels match an existing profile, Sveltos begins managing it immediately with no further configuration.

Core Reconciliation Loop

The central reconciliation loop is what drives all add-on deployments.

flowchart TD
    U([User / GitOps]) -- "creates/updates" --> CP[ClusterProfile or Profile]
    CP -- "label selector match" --> AC[addon-controller]
    AC -- "creates one per matching cluster" --> CS[ClusterSummary]
    CS -- "deploys features in order" --> FH["Feature handlers\n(Helm, raw YAML, Kustomize, …)"]
    FH -- "push mode" --> MC[Managed Cluster]
    FH -- "pull mode: writes ConfigurationGroup" --> AG[sveltos-applier in managed cluster]
    AG -- "applies to" --> MC
    MC -- "drift detected" --> DD[drift-detection-manager]
    DD -- "signals" --> CS

Step by step:

1. A user (or a GitOps controller) creates or updates a ClusterProfile in the management cluster.
2. The addon-controller finds all clusters whose labels match the clusterSelector and creates or updates one ClusterSummary per matching cluster.
3. The ClusterSummary reconciler deploys each declared feature, including Helm charts, raw YAML, and Kustomize packages, in the order defined by the profile. A failure on one feature stops further features for that cluster until the next reconciliation cycle.
4. The deployed resource list is recorded in a ClusterConfiguration, which serves as the source of truth for what Sveltos owns on each cluster.
5. When syncMode is ContinuousWithDriftDetection, the drift-detection-manager watches every resource Sveltos deployed. If anything is changed externally, it signals the ClusterSummary reconciler to reapply the desired state.

The addon-controller continuously monitors the system using efficient event-driven watchers, minimizing CPU overhead by only acting when state changes occur.

Management Cluster Components

Core Controllers

These controllers are always deployed and cannot be disabled.

Optional Components

These components can be disabled when not needed.

Installation Jobs

Two Jobs run at install and upgrade time. They are not long-running controllers.

Agents

Two agents handle work that requires direct access to the managed cluster's API server: evaluating classification rules, detecting events, checking health, and detecting configuration drift. Where these agents run is the key difference between the two deployment modes.

Deployment Modes

Sveltos ships in two modes that differ only in where the agents run.

Mode 1: Local Agent Mode (Manifest)

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

The agents run inside each managed cluster. The Classifier-manager deploys the sveltos-agent as a Deployment in the projectsveltos namespace on every managed cluster. The Addon-controller deploys the drift-detection-manager to managed clusters that have at least one profile using ContinuousWithDriftDetection.

Management cluster                     Managed cluster
─────────────────────────────────      ─────────────────────────────────────────
addon-controller                       projectsveltos namespace:
classifier-manager  ──deploys──►         sveltos-agent (Deployment)
event-manager                            drift-detection-manager (if needed)
healthcheck-manager                      Sveltos CRDs
sveltoscluster-manager                   ClassifierReports, EventReports, …
access-manager

RBAC is created in each managed cluster by Sveltos:

• Namespace: projectsveltos
• ServiceAccount: sveltos-agent-manager in the projectsveltos namespace
• ClusterRole sveltos-agent-manager-role:
  • get, list, watch on *.* is needed to evaluate Classifier, EventSource, and HealthCheck rules against arbitrary resource types
  • create, delete, get, list, patch, update, watch on ClassifierReport, EventReport, HealthCheckReport, ReloaderReport
  • get, list, patch, update, watch on Classifier, EventSource, HealthCheck, Reloader
  • create, patch, update on Events
• ClusterRoleBinding: Binds the ClusterRole to the ServiceAccount
• When syncMode: ContinuousWithDriftDetection: A separate drift-detection-manager Deployment, ServiceAccount, and ClusterRole are also created (read access on tracked resources, write on ResourceSummary)

The management cluster needs a kubeconfig for each managed cluster (stored as a Secret, referenced by SveltosCluster) so the controllers can connect outbound to deploy agents, collect reports, and push add-ons.

Mode 2: Centralized Agent Mode (Manifest)

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

The agents run in the management cluster, one Deployment per managed cluster. Sveltos leaves no footprint on managed clusters.

Management cluster
──────────────────────────────────────────────────────────────────────────
addon-controller
classifier-manager
event-manager
healthcheck-manager
sveltoscluster-manager
access-manager

Per-managed-cluster Deployments (**running in the management cluster**):
  sveltos-agent-<cluster>            ──► connects to managed cluster API
  drift-detection-manager-<cluster>  ──► connects to managed cluster API (if needed)

RBAC in managed clusters: None. Sveltos creates no ServiceAccount, ClusterRole, or Deployment in managed clusters. The only requirement is that the kubeconfig for each managed cluster — stored as a Secret in the management cluster and referenced by SveltosCluster — grants the permissions Sveltos needs.

The kubeconfig must allow:

• get, list, watch on *.* for the sveltos-agent to evaluate classification, event, and health-check rules
• Read access on resources being drift-detected for drift-detection-manager
• Sufficient permissions for addon-controller to deploy (create, update, delete) the add-ons defined in profiles

Scoping deployment permissions

The deployment permissions are not fixed. They are exactly the permissions needed to create, update, and delete whatever a ClusterProfile declares. There is no need to grant cluster-admin. Follow a least-privilege approach.

For example, a ClusterProfile that installs the podinfo Helm chart into the podinfo namespace looks like the following YAML output.

apiVersion: config.projectsveltos.io/v1beta1
kind: ClusterProfile
metadata:
  name: podinfo
spec:
  clusterSelector:
    matchLabels:
      env: fv
  helmCharts:
  - repositoryURL:    https://stefanprodan.github.io/podinfo
    repositoryName:   podinfo
    chartName:        podinfo/podinfo
    chartVersion:     6.14.0
    releaseName:      podinfo-latest
    releaseNamespace: podinfo
    helmChartAction:  Install
    options:
      installOptions:
        createNamespace: false

It requires only the following RBAC on the managed cluster to perform the deployment.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: sa-deployer
  namespace: podinfo
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: sa-deployer-role
  namespace: podinfo
rules:
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["autoscaling"]
  resources: ["horizontalpodautoscalers"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["services"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["networking.k8s.io"]
  resources: ["ingresses"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["secrets"]   # Helm stores release state in Secrets
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["pods"]      # Helm test pods
  verbs: ["get", "list", "watch", "create", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: sa-deployer-binding
  namespace: podinfo
subjects:
- kind: ServiceAccount
  name: sa-deployer
  namespace: podinfo
roleRef:
  kind: Role
  name: sa-deployer-role
  apiGroup: rbac.authorization.k8s.io

The kubeconfig stored in the management cluster is generated for the sa-deployer ServiceAccount. Sveltos uses it to connect to the managed cluster with exactly those permissions. Nothing more.

Mode Comparison

Next Steps

Continue with the CRDs sections.