title: 'Kubernetes - Argo CD' sidebar_label: 'Argo CD' sidebar_position: 2 description: 'Deploy Spice.ai on self-hosted Kubernetes using Argo CD and the Spice Helm chart.' tags:
This guide describes how to deploy Spice.ai on a self-hosted Kubernetes cluster using Argo CD and the official Spice Helm chart. Argo CD continuously reconciles the cluster state with manifests stored in Git, providing a GitOps workflow for managing Spice.ai deployments.
:::info Deployment Architecture
By default, the Spice.ai Helm chart deploys Spice as a stateless Kubernetes Deployment. To persist data between restarts (for example, to use file-based acceleration), enable the stateful section in the Helm values. See the Stateful Configuration section in the Helm guide for details.
:::
:::tip[Spice.ai Enterprise]
For production stateful or distributed deployments managed via Argo CD, the Spice.ai Enterprise Operator's SpicepodSet (per-replica StatefulSets, automatic PVC resizing, advanced update strategies) and SpicepodCluster (scheduler/executor topology with mTLS) resources can be reconciled by Argo CD just like any other CRD-backed manifest.
:::
Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. It watches Git repositories or Helm registries for changes and automatically applies them to the cluster, keeping the live state in sync with the desired state defined in Git.
This guide uses the Spice Helm chart as the source. For a direct Helm-based deployment without Argo CD, see Kubernetes - Helm.
kubectl CLI installed and configured for the target cluster. See the Kubernetes documentation.argocd CLI for command-line management. See Install the Argo CD CLI.Argo CD reconciles a Kubernetes resource of kind Application, which describes the source (Helm chart, kustomization, or plain manifests), the destination cluster and namespace, and the sync policy.
Define an Application that references the Spice Helm chart directly. Inline overrides are provided through helm.valuesObject.
Save the following as spiceai-application.yaml:
Apply the manifest:
Argo CD detects the new Application, fetches the chart, renders the templates, and applies the resulting resources to the destination namespace.
For larger or more sensitive configurations, store the Helm values in a Git repository and reference them with Argo CD multiple sources. This keeps configuration version-controlled and reviewable through pull requests.
The first source supplies the chart, and the second source (ref: values) provides the values file referenced by $values. Update the Spice configuration by committing changes to clusters/production/spiceai/values.yaml; Argo CD reconciles the change automatically.
A values.yaml example is available in Example values.yaml.
The syncPolicy.automated block enables continuous reconciliation:
prune: true removes resources from the cluster when they are removed from Git.selfHeal: true reverts manual changes made directly to the cluster, restoring the state defined in Git.syncOptions: [CreateNamespace=true] instructs Argo CD to create the destination namespace if it does not exist.syncOptions: [ServerSideApply=true] is recommended for charts that produce large CRDs or resources that exceed the client-side apply annotation size limit.To trigger a manual sync from the CLI:
Upgrade the running Spice.ai deployment by changing spec.source.targetRevision (or spec.sources[].targetRevision) to a newer chart version, then committing the change to Git or reapplying the Application manifest. Argo CD reconciles the new revision and performs a rolling upgrade.
To pin to the latest chart version automatically, set targetRevision: '*'. Pinning to a specific version is recommended for production environments to ensure reproducible deployments.
The list of published chart versions is available at helm.spiceai.org.
Roll back to a previous revision using the Argo CD CLI or UI:
When the Application is managed by Git, prefer reverting the commit that introduced the change so the desired state in Git matches the live state. With selfHeal: true enabled, Argo CD will otherwise re-apply the Git state.
Delete the Application to remove the Spice.ai deployment. With prune: true, all resources created by the chart are removed:
PersistentVolumeClaims created by a StatefulSet are retained by default and must be deleted manually if no longer needed:
Do not commit plain-text secrets to Git. Reference Kubernetes Secret resources from additionalEnv and manage the secrets themselves with one of:
Example referencing a pre-existing Secret named spice-secrets:
See Environment Variables and Secrets in the Helm guide for additional configuration patterns.
The Spice Helm chart integrates with the Prometheus Operator through a PodMonitor resource. Enable it with:
Once metrics are collected, import the Spice Grafana dashboard for visualization.
To deploy multiple Spice.ai instances (for example, one per environment or tenant), create one Application per release with distinct names, namespaces, and values. The App of Apps pattern or ApplicationSets can manage these declaratively at scale.
Example ApplicationSet that deploys Spice.ai to multiple namespaces: