Skip to content

Commit b081b34

Browse files
phillipleblanclukekim
phillipleblanc
and
lukekim
authored
Update Helm deployment documentation (#1002)
* Update Helm docs to explain more concepts * Tweaks --------- Co-authored-by: Luke Kim <80174+lukekim@users.noreply.github.com>
1 parent 6254d37 commit b081b34

1 file changed

Lines changed: 150 additions & 38 deletions

File tree

  • website/docs/deployment/kubernetes

‎website/docs/deployment/kubernetes/index.md‎

Lines changed: 150 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,137 @@ tags:
1111
- spiceai
1212
---
1313

14-
## TL;DR
14+
## Quickstart
1515

1616
```bash
1717
helm repo add spiceai https://helm.spiceai.org
1818
helm repo update
1919
helm upgrade --install spiceai spiceai/spiceai
2020
```
2121

22-
Deploy Spice using Helm in Kubernetes.
23-
24-
For a quick start with Helm, refer to the [Helm Quickstart Guide](https://helm.sh/docs/intro/quickstart/#initialize-a-helm-chart-repository).
25-
2622
:::info Deployment Architecture
27-
The Spice.ai Helm chart deploys the application as a stateless Kubernetes Deployment by default. This configuration does not persist data between pod restarts. For workloads requiring data persistence, such as file-based acceleration, the chart supports deploying Spice.ai as a StatefulSet with persistent volume claims by enabling and configuring the `stateful` section in the values file.
23+
By default, the Spice.ai Helm chart deploys the application as a stateless Kubernetes Deployment. To persist data between restarts (e.g., for file-based acceleration), enable and configure the `stateful` section in the values file. Refer to the [Stateful Configuration](#stateful-configuration) section for details.
2824
:::
2925

30-
## Values
26+
## What are Kubernetes and Helm?
27+
28+
**Kubernetes** is an open-source platform for automating deployment, scaling, and management of containerized applications.
29+
**Helm** is a package manager for Kubernetes that simplifies the installation and configuration of applications using reusable templates called charts.
30+
31+
Spice publishes a Helm chart that simplifies the deployment of Spice.ai OSS on Kubernetes.
32+
33+
## Deploy Spice using Helm in Kubernetes
3134

32-
The following table lists the configurable parameters of the Spice.ai chart and their [default values](https://github.com/spiceai/spiceai/blob/trunk/deploy/chart/values.yaml). Override the default values by creating a `values.yaml` file ([example](#example-valuesyaml)).
35+
### Prerequisites
36+
37+
- Access to a Kubernetes cluster.
38+
- For local testing, try running a local Kubernetes cluster using [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/).
39+
- `kubectl` CLI installed and configured to interact with the target Kubernetes cluster. Visit the [Kubernetes docs](https://kubernetes.io/docs/tasks/tools/#kubectl) for installation instructions.
40+
- Helm CLI installed. Visit the [Helm docs](https://helm.sh/docs/intro/install/) for installation instructions.
41+
42+
### Add the Spice Helm repository
43+
44+
A Helm repository (Helm repo) is a storage location where Helm charts are hosted and can be accessed for deployment in Kubernetes clusters. Add the Spice Helm repository to your local Helm client and update the index to get the latest charts:
3345

3446
```bash
35-
helm upgrade --install spiceai spiceai/spiceai -f values.yaml
47+
helm repo add {repository-name} https://helm.spiceai.org
48+
helm repo update
49+
```
50+
51+
The repository name is customizable and can be set to any preferred value. For example:
52+
53+
```bash
54+
helm repo add spiceai https://helm.spiceai.org
55+
# or
56+
helm repo add my-spiceai-repo https://helm.spiceai.org
57+
```
58+
59+
### Install the Spice Helm chart as a new release
60+
61+
Once the repository with the chart is added, install the chart into the Kubernetes cluster with the following command:
62+
63+
```bash
64+
helm install {release-name} {repository-name}/spiceai --namespace {namespace}
65+
```
66+
67+
For example:
68+
69+
```bash
70+
helm install spiceai spiceai/spiceai --namespace default
3671
```
3772

38-
## Spicepod
73+
Spice can be installed multiple times in the same cluster by specifying a different release name for each installation.
3974

40-
Define a [Spicepod](https://spiceai.org/docs/getting-started/spicepods) to be loaded by the Spice.ai runtime by overriding the `spicepod` value in the `values.yaml` file.
75+
#### Command Breakdown
76+
77+
- `helm install`: Installs a new Helm chart. To upgrade an existing release, use `helm upgrade`. Combine both upgrade and install by specifying `helm upgrade --install`.
78+
- `spiceai`: The name of the release. This name is customizable and can be set to any preferred value, e.g., `spiceai-my-app-v1` and `spiceai-my-app-v2` are valid release names. Each Helm release is a distinct installation of the same chart.
79+
- `spiceai/spiceai`: The chart to install. The first `spiceai` is the repository name added earlier, and the second `spiceai` is the name of the chart to install. While the repository name is customizable, the chart name is not.
80+
- `--namespace default`: The Kubernetes namespace to install the chart into. This is optional and defaults to `default`.
81+
82+
Another valid command to install the chart is (assuming the repository name is `my-spiceai-repo`):
83+
84+
```bash
85+
helm upgrade --install spiceai-my-app-1 my-spiceai-repo/spiceai
86+
```
87+
88+
### Upgrade the Spice Helm chart
89+
90+
To upgrade an existing release, use the `helm upgrade` command:
91+
92+
```bash
93+
helm upgrade {release-name} {repository-name}/{chart-name}
94+
```
95+
96+
For example:
97+
98+
```bash
99+
helm upgrade spiceai-my-app-1 my-spiceai-repo/spiceai
100+
```
101+
102+
### Rollback a Helm release
103+
104+
On occasion, you may need to roll back a Spice Helm release to a previous version. To do so, use the `helm rollback` command. This will notify Kubernetes to redeploy Spice back to a previous version of the Helm release:
105+
106+
```bash
107+
helm rollback {release-name} --namespace {namespace}
108+
```
109+
110+
For example:
111+
112+
```bash
113+
helm rollback spiceai-my-app-1 --namespace default
114+
```
115+
116+
### Uninstall a Helm release
117+
118+
To uninstall a Helm release, use the `helm uninstall` command. This will cause Kubernetes to remove the Spice deployment entirely. Note that any data stored in volumes created by configuring the `stateful` parameter will be preserved and must be manually deleted if desired:
119+
120+
```bash
121+
helm uninstall {release-name} --namespace {namespace}
122+
```
123+
124+
For example:
125+
126+
```bash
127+
helm uninstall spiceai-my-app-1 --namespace default
128+
```
129+
130+
## Customize the Helm release
131+
132+
By default, the Helm release installs a minimal Spice.ai setup with an empty Spicepod. To add a Spicepod and adjust other settings, customize the release as needed by creating a `values.yaml` file or by using the `--set` flag.
133+
134+
:::note
135+
`values.yaml` is the configuration file used in Helm to define the user-configurable parameters of a Helm chart. The `--set` flag is used to specify individual values on the command line. Visit the [Helm docs](https://helm.sh/docs/chart_template_guide/values_files/#helm) for more information.
136+
:::
137+
138+
Create a `values.yaml` file and override the default values as needed.
139+
The full list of configurable parameters and their defaults are specified in the [values.yaml file](https://github.com/spiceai/spiceai/blob/trunk/deploy/chart/values.yaml) in the `spiceai/spiceai` repository.
140+
The [Common Parameters](#common-parameters) section below lists the most commonly used configurable parameters and their descriptions.
141+
142+
### Spicepod
143+
144+
To customize the Spicepod that the Spice.ai runtime will load, define a [Spicepod](https://spiceai.org/docs/getting-started/spicepods) in a new `values.yaml` file.
41145

42146
```yaml
43147
spicepod:
@@ -48,32 +152,40 @@ spicepod:
48152
datasets:
49153
- from: s3://spiceai-demo-datasets/taxi_trips/2024/
50154
name: taxi_trips
51-
description: Demo taxi trips in s3
52155
params:
53156
file_format: parquet
54-
acceleration:
55-
enabled: true
56157
```
57158
159+
Upgrade or install a new release with the custom Spicepod:
160+
161+
```bash
162+
helm upgrade --install spiceai spiceai/spiceai -f values.yaml
163+
```
164+
165+
:::note
166+
The Helm convention is to use a file called `values.yaml`, but any file name can be used and passed to the `-f` flag.
167+
:::
168+
58169
## Common Parameters
59170

60-
| **Name** | **Description** | **Value** |
61-
|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
62-
| `additionalLabels` | Additional labels to add to all resources. | `{}` |
63-
| `image.repository` | The repository of the Docker image. | `spiceai` |
64-
| `image.tag` | Replace with a specific version of Spice.ai to run. | `1.0.5` |
65-
| `replicaCount` | Number of Spice.ai replicas to run. | `1` |
66-
| `service.type` | Kubernetes service type. Can be null, ClusterIP, NodePort, or LoadBalancer. | `null` |
67-
| `monitoring.podMonitor.enabled` | Enable Prometheus metrics collection for the Spice pods. Requires the [Prometheus Operator](https://prometheus-operator.dev/docs/operator/api/#monitoring.coreos.com/v1.PodMonitor) CRDs. | `false` |
68-
| `image.pullSecrets` | Specify Docker registry secret names as an array. | `[]` |
69-
| `tolerations` | List of node taints to tolerate. | `[]` |
70-
| `resources` | Resource requests and limits for the Spice.ai container. See [Container resource examples](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#example-1). | `{}` |
71-
| `additionalEnv` | Additional environment variables to set in the Spice.ai container. | `[]` |
72-
| `stateful.enabled` | Use a StatefulSet with a PVC for the data volume. | `false` |
73-
| `stateful.storageClass` | Storage class for the volume claim template in the StatefulSet. | `standard` |
74-
| `stateful.size` | Size of each PV in the StatefulSet. | `1Gi` |
75-
| `stateful.mountPath` | Mount path in container for the persistent volume. | `/data` |
76-
| `serviceAccount.create` | Specifies whether a ServiceAccount should be created. | `false` |
171+
| **Name** | **Description** | **Value** |
172+
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
173+
| `additionalEnv` | Additional environment variables to set in the Spice.ai container. | `[]` |
174+
| `additionalLabels` | Additional labels to add to all resources. | `{}` |
175+
| `image.pullSecrets` | Specify Docker registry secret names as an array. | `[]` |
176+
| `image.repository` | The repository of the Docker image. | `spiceai` |
177+
| `image.tag` | Replace with a specific version of Spice.ai to run. | `1.3.0` |
178+
| `monitoring.podMonitor.enabled` | Enable Prometheus metrics collection for the Spice pods. Requires the [Prometheus Operator](https://prometheus-operator.dev/docs/operator/api/#monitoring.coreos.com/v1.PodMonitor) CRDs. | `false` |
179+
| `replicaCount` | Number of Spice.ai replicas to run. | `1` |
180+
| `resources` | Resource requests and limits for the Spice.ai container. See [Container resource examples](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#example-1). | `{}` |
181+
| `service.type` | Kubernetes service type. Can be null, ClusterIP, NodePort, or LoadBalancer. | `null` |
182+
| `serviceAccount.create` | Specifies whether a ServiceAccount should be created. | `false` |
183+
| `spicepod` | Define the [Spicepod](https://spiceai.org/docs/getting-started/spicepods) to be loaded by the Spice.ai runtime. | `{}` |
184+
| `stateful.enabled` | Use a StatefulSet with a PVC (Persistent Volume Claim) for the data volume. | `false` |
185+
| `stateful.mountPath` | Mount path in container for the persistent volume. | `/data` |
186+
| `stateful.size` | Size of each PV in the StatefulSet. | `1Gi` |
187+
| `stateful.storageClass` | Storage class for the volume claim template in the StatefulSet. | `standard` |
188+
| `tolerations` | List of node taints to tolerate. | `[]` |
77189

78190
## Environment Variables and Secrets
79191

@@ -82,7 +194,7 @@ Add extra environment variables using the `additionalEnv` property. This can be
82194
```yaml
83195
additionalEnv:
84196
- name: SPICED_LOG
85-
value: "DEBUG"
197+
value: 'DEBUG'
86198
- name: SPICE_SECRET_SPICEAI_KEY
87199
valueFrom:
88200
secretKeyRef:
@@ -131,7 +243,7 @@ Once the monitoring is enabled, import the [Spice Grafana dashboard](../../clien
131243

132244
### Health and Readiness
133245

134-
Spice provides two HTTP endpoints for monitoring the runtime state: `/health` and `/v1/ready`. These endpoints are used for Kubernetes health and readiness probes in the Spice deployment.
246+
Spice provides two HTTP endpoints for monitoring the runtime state: `/health` and `/v1/ready`. These endpoints are used for Kubernetes health and readiness probes in the Spice deployment. The Spice Helm chart automatically configures these probes.
135247

136248
#### Health Probe
137249

@@ -227,7 +339,7 @@ Enabling the StatefulSet architecture requires configuration of the `stateful` s
227339
stateful:
228340
enabled: true
229341
# Storage class for the volume claim template
230-
storageClass: "standard"
342+
storageClass: 'standard'
231343
# Size of each PV in the StatefulSet
232344
size: 1Gi
233345
# Mount path in container
@@ -245,13 +357,13 @@ additionalLabels:
245357
246358
image:
247359
repository: spiceai/spiceai
248-
tag: 1.0.5
360+
tag: 1.3.0
249361
replicaCount: 1
250362
251363
service:
252364
type: ClusterIP
253365
additionalAnnotations:
254-
service.beta.kubernetes.io/aws-load-balancer-internal: "true"
366+
service.beta.kubernetes.io/aws-load-balancer-internal: 'true'
255367
256368
resources:
257369
limits:
@@ -263,7 +375,7 @@ resources:
263375
264376
additionalEnv:
265377
- name: SPICED_LOG
266-
value: "INFO"
378+
value: 'INFO'
267379
- name: SPICE_SECRET_SPICEAI_KEY
268380
valueFrom:
269381
secretKeyRef:
@@ -272,7 +384,7 @@ additionalEnv:
272384
273385
stateful:
274386
enabled: true
275-
storageClass: "standard"
387+
storageClass: 'standard'
276388
size: 5Gi
277389
mountPath: /data
278390

0 commit comments

Comments
 (0)