|
| 1 | +--- |
| 2 | +title: 'CI/CD Deployment' |
| 3 | +sidebar_label: 'CI/CD' |
| 4 | +sidebar_position: 7 |
| 5 | +description: 'Deploy Spice.ai applications using continuous integration and delivery pipelines, including Helm, Kubernetes GitOps with Argo CD or Flux, GitHub Actions, and the Spice Cloud deploy action.' |
| 6 | +keywords: |
| 7 | + [ |
| 8 | + spice.ai, |
| 9 | + deployment, |
| 10 | + ci/cd, |
| 11 | + cicd, |
| 12 | + helm, |
| 13 | + kubernetes, |
| 14 | + github actions, |
| 15 | + gitops, |
| 16 | + argo cd, |
| 17 | + flux, |
| 18 | + spicepod, |
| 19 | + spice cloud, |
| 20 | + ] |
| 21 | +tags: |
| 22 | + - deployment |
| 23 | + - helm |
| 24 | + - kubernetes |
| 25 | + - github |
| 26 | + - gitops |
| 27 | +--- |
| 28 | + |
| 29 | +Spice deployments can be automated through continuous integration and delivery (CI/CD) pipelines. The recommended approach for self-hosted, open-source deployments is the [Spice Helm chart](https://github.com/spiceai/helm-charts), driven either directly from a pipeline runner or declaratively through a GitOps controller. Container and cloud-VM workflows are also supported, as is a managed deploy action for the Spice Cloud Platform. |
| 30 | + |
| 31 | +The sections below cover, in order: |
| 32 | + |
| 33 | +- [Helm in CI pipelines](#helm-in-ci-pipelines) — push-based deployment from GitHub Actions, GitLab CI, or any runner. |
| 34 | +- [Kubernetes GitOps](#kubernetes-gitops) — pull-based reconciliation with Argo CD or Flux. |
| 35 | +- [Containers and cloud VMs](#containers-and-cloud-vms) — Docker, AWS, and Azure pipelines. |
| 36 | +- [Spice Cloud Platform](#spice-cloud-platform) — Connect Repository from the portal, or the `spicehq/spice-cloud-deploy-action` GitHub Action. |
| 37 | + |
| 38 | +:::tip Self-hosted enterprise deployments |
| 39 | +For production self-hosted deployments, the [Spice.ai Enterprise Kubernetes Operator](https://docs.spice.ai/docs/enterprise/kubernetes-operator/kubernetes) is the recommended approach. The operator provides per-replica StatefulSets, automatic PVC resizing, configurable update strategies, crashloop protection, and distributed query execution through `SpicepodSet` and `SpicepodCluster` custom resources, all reconcilable from Git through the same GitOps tooling described below. |
| 40 | +::: |
| 41 | + |
| 42 | +## Helm in CI pipelines |
| 43 | + |
| 44 | +The [Spice Helm chart](https://github.com/spiceai/helm-charts) is the primary deployment artifact for self-hosted clusters. Any CI runner with `kubectl` and `helm` installed can roll out a release by checking out the repository, authenticating to the target cluster, and running `helm upgrade --install`. |
| 45 | + |
| 46 | +The chart loads the Spicepod from a `spicepod` key in the values file. A typical layout keeps a single `values.yaml` that contains both chart configuration and the Spicepod definition: |
| 47 | + |
| 48 | +```yaml |
| 49 | +# values.yaml |
| 50 | +image: |
| 51 | + repository: spiceai/spiceai |
| 52 | + tag: '1.10.0' |
| 53 | + |
| 54 | +spicepod: |
| 55 | + name: cayenne |
| 56 | + version: v1 |
| 57 | + kind: Spicepod |
| 58 | + datasets: |
| 59 | + - from: s3://spiceai-demo-datasets/taxi_trips/2024/ |
| 60 | + name: taxi_trips |
| 61 | + params: |
| 62 | + file_format: parquet |
| 63 | + acceleration: |
| 64 | + enabled: true |
| 65 | + engine: duckdb |
| 66 | +``` |
| 67 | +
|
| 68 | +For details on chart values, see the [Helm deployment guide](https://spiceai.org/docs/deployment/kubernetes/helm). |
| 69 | +
|
| 70 | +### GitHub Actions example |
| 71 | +
|
| 72 | +The workflow below deploys the chart to a Kubernetes cluster on every push to `main`. Cluster credentials are provided through a base64-encoded kubeconfig stored in the `KUBE_CONFIG` repository secret. |
| 73 | + |
| 74 | +```yaml |
| 75 | +name: Deploy Spice |
| 76 | +on: |
| 77 | + push: |
| 78 | + branches: [main] |
| 79 | +
|
| 80 | +jobs: |
| 81 | + deploy: |
| 82 | + runs-on: ubuntu-latest |
| 83 | + steps: |
| 84 | + - uses: actions/checkout@v4 |
| 85 | +
|
| 86 | + - uses: azure/setup-helm@v4 |
| 87 | + with: |
| 88 | + version: v3.14.0 |
| 89 | +
|
| 90 | + - name: Configure kubectl |
| 91 | + run: | |
| 92 | + mkdir -p "$HOME/.kube" |
| 93 | + echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > "$HOME/.kube/config" |
| 94 | +
|
| 95 | + - name: Deploy Spice |
| 96 | + run: | |
| 97 | + helm repo add spiceai https://helm.spiceai.org |
| 98 | + helm repo update |
| 99 | + helm upgrade --install spiceai spiceai/spiceai \ |
| 100 | + --namespace spiceai \ |
| 101 | + --create-namespace \ |
| 102 | + --values values.yaml \ |
| 103 | + --atomic \ |
| 104 | + --wait \ |
| 105 | + --timeout 5m |
| 106 | +``` |
| 107 | + |
| 108 | +`--atomic` rolls back on failure, and `--wait` blocks until the release is healthy, so a failed deploy fails the pipeline. |
| 109 | + |
| 110 | +### GitLab CI example |
| 111 | + |
| 112 | +The same pattern works in GitLab CI. The job uses the official `alpine/helm` image and reads cluster credentials from a CI/CD variable. |
| 113 | + |
| 114 | +```yaml |
| 115 | +deploy: |
| 116 | + image: alpine/helm:3.14.0 |
| 117 | + stage: deploy |
| 118 | + before_script: |
| 119 | + - apk add --no-cache curl |
| 120 | + - curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" |
| 121 | + - install -m 0755 kubectl /usr/local/bin/kubectl |
| 122 | + - mkdir -p ~/.kube && echo "$KUBE_CONFIG" | base64 -d > ~/.kube/config |
| 123 | + script: |
| 124 | + - helm repo add spiceai https://helm.spiceai.org |
| 125 | + - helm repo update |
| 126 | + - helm upgrade --install spiceai spiceai/spiceai |
| 127 | + --namespace spiceai --create-namespace |
| 128 | + --values values.yaml |
| 129 | + --atomic --wait --timeout 5m |
| 130 | + only: |
| 131 | + - main |
| 132 | +``` |
| 133 | + |
| 134 | +### Pinning the chart and runtime versions |
| 135 | + |
| 136 | +Production pipelines should pin both the chart and the Spice runtime image to specific versions. Pass `--version` to `helm upgrade` to pin the chart, and set `image.tag` in `values.yaml` to pin the runtime image: |
| 137 | + |
| 138 | +```bash |
| 139 | +helm upgrade --install spiceai spiceai/spiceai \ |
| 140 | + --version 1.10.0 \ |
| 141 | + --values values.yaml |
| 142 | +``` |
| 143 | + |
| 144 | +Available chart versions are listed in the [helm-charts repository](https://github.com/spiceai/helm-charts/releases). Runtime image tags are published on [GitHub Container Registry](https://github.com/spiceai/spiceai/pkgs/container/spiceai). |
| 145 | + |
| 146 | +### Promoting across environments |
| 147 | + |
| 148 | +To promote the same artifact across environments, keep a base `values.yaml` and add per-environment overlays such as `values.staging.yaml` and `values.prod.yaml`. Helm merges multiple `-f` flags in order: |
| 149 | + |
| 150 | +```bash |
| 151 | +helm upgrade --install spiceai spiceai/spiceai \ |
| 152 | + --values values.yaml \ |
| 153 | + --values values.prod.yaml |
| 154 | +``` |
| 155 | + |
| 156 | +Each environment can target a different cluster, namespace, or image tag while sharing the same Spicepod definition. |
| 157 | + |
| 158 | +## Kubernetes GitOps |
| 159 | + |
| 160 | +GitOps controllers reconcile cluster state from a Git repository, removing the need for the pipeline to hold cluster credentials. The controller runs inside the cluster and pulls changes as they are committed. |
| 161 | + |
| 162 | +- [Argo CD](https://spiceai.org/docs/deployment/kubernetes/argocd) — `Application` manifests reconciled by the Argo CD controller. |
| 163 | +- [Flux](https://spiceai.org/docs/deployment/kubernetes/flux) — `HelmRelease` resources reconciled by the Flux toolkit. |
| 164 | + |
| 165 | +Both guides include end-to-end manifests targeting the official chart, including upgrade and rollback patterns. GitOps is the recommended approach for multi-cluster or multi-environment deployments. |
| 166 | + |
| 167 | +## Containers and cloud VMs |
| 168 | + |
| 169 | +For deployments that target a container runtime or a cloud VM rather than Kubernetes, invoke the standard provider tooling from any pipeline runner: |
| 170 | + |
| 171 | +- [Docker](https://spiceai.org/docs/deployment/docker) — build, push, and run the `spiceai/spiceai` image. Pipelines typically run `docker build` and `docker push` against a registry, then `docker compose up -d` or `docker run` on the target host. |
| 172 | +- [AWS](https://spiceai.org/docs/deployment/aws) — deploy the published CloudFormation template through the AWS CLI or any CloudFormation-aware action. |
| 173 | +- [Azure](https://spiceai.org/docs/deployment/azure) — deploy through ARM/Bicep templates or the Azure CLI. |
| 174 | + |
| 175 | +Each provider guide includes the deployment artifact (image, template, or script) that the pipeline invokes. |
| 176 | + |
| 177 | +## Spice Cloud Platform |
| 178 | + |
| 179 | +Deployments targeting the [Spice Cloud Platform](https://spiceai.org/docs/deployment/cloud) can be automated two ways: |
| 180 | + |
| 181 | +- **Connect Repository** — link a GitHub repository to a Spice Cloud app from the portal. The app redeploys automatically on each push to the connected branch, with no pipeline configuration required. See [Connect GitHub](https://docs.spice.ai/docs/portal/apps/connect-github). |
| 182 | +- **GitHub Actions** — use the [`spicehq/spice-cloud-deploy-action`](https://github.com/spicehq/spice-cloud-deploy-action) to deploy from a custom workflow. Use this when the pipeline needs to run tests, build artifacts, or set secrets and tags before deploying. |
| 183 | + |
| 184 | +### GitHub Actions |
| 185 | + |
| 186 | +The `spicehq/spice-cloud-deploy-action` deploys a Spicepod manifest to a Spice Cloud app on each pipeline run. |
| 187 | + |
| 188 | +#### Prerequisites |
| 189 | + |
| 190 | +- A [Spice Cloud account](https://spice.ai/login). |
| 191 | +- An OAuth client created from the Spice Cloud Portal. Two repository secrets — `SPICE_CLIENT_ID` and `SPICE_CLIENT_SECRET` — store its credentials. |
| 192 | +- A `spicepod.yaml` checked into the repository. |
| 193 | + |
| 194 | +#### Minimal workflow |
| 195 | + |
| 196 | +```yaml |
| 197 | +name: Deploy Spicepod |
| 198 | +on: |
| 199 | + push: |
| 200 | + branches: [main] |
| 201 | +
|
| 202 | +jobs: |
| 203 | + deploy: |
| 204 | + runs-on: ubuntu-latest |
| 205 | + steps: |
| 206 | + - uses: actions/checkout@v4 |
| 207 | + - uses: spicehq/spice-cloud-deploy-action@v1 |
| 208 | + with: |
| 209 | + client-id: ${{ secrets.SPICE_CLIENT_ID }} |
| 210 | + client-secret: ${{ secrets.SPICE_CLIENT_SECRET }} |
| 211 | + app-name: my-app |
| 212 | + spicepod: spicepod.yaml |
| 213 | +``` |
| 214 | + |
| 215 | +#### Common options |
| 216 | + |
| 217 | +| Input | Purpose | |
| 218 | +| -------------------------------------- | -------------------------------------------------------------------------------------- | |
| 219 | +| `app-name` or `app-id` | Target Spice Cloud app. One is required. | |
| 220 | +| `spicepod` | Path to the Spicepod manifest. Defaults to `spicepod.yaml`. | |
| 221 | +| `region` | Required when `create-app-if-missing` provisions a new app (for example, `us-east-1`). | |
| 222 | +| `create-app-if-missing` | Boolean. Creates the app on first deploy. | |
| 223 | +| `secrets` | YAML or JSON map of app-level secrets to set on the deployment. | |
| 224 | +| `tags` | YAML or JSON map of metadata labels. | |
| 225 | +| `test-sql`, `test-chat`, `test-search` | Post-deploy smoke checks against the deployed app. | |
| 226 | +| `wait-for-completion` | Poll until the deployment finishes. Defaults to `true`. | |
| 227 | +| `timeout-seconds` | Maximum time to wait when polling. Defaults to `600`. | |
| 228 | + |
| 229 | +The action emits `app-id`, `app-url`, `deployment-id`, `deployment-status`, and `test-results` outputs that downstream steps can consume. For the full input and output reference, see the [action's README](https://github.com/spicehq/spice-cloud-deploy-action). |
| 230 | + |
| 231 | +## Related |
| 232 | + |
| 233 | +- [Helm Deployment Guide](https://spiceai.org/docs/deployment/kubernetes/helm) |
| 234 | +- [Kubernetes Deployment Guide](https://spiceai.org/docs/deployment/kubernetes) |
| 235 | +- [Argo CD Guide](https://spiceai.org/docs/deployment/kubernetes/argocd) |
| 236 | +- [Flux Guide](https://spiceai.org/docs/deployment/kubernetes/flux) |
| 237 | +- [Spice Cloud Platform Deployment](https://spiceai.org/docs/deployment/cloud) |
| 238 | +- [Spice Helm Chart](https://github.com/spiceai/helm-charts) |
| 239 | +- [Spice Cloud Deploy Action](https://github.com/spicehq/spice-cloud-deploy-action) |
0 commit comments