> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.34.0/getting-started/deployment/helm-chart.md). # Helm Chart The [Terrakube Helm chart](https://github.com/terrakube-io/terrakube-helm-chart) deploys the API, executor, registry and UI, plus Dex for sign-in, onto any Kubernetes cluster (1.19+) with Helm 3. ```bash helm repo add terrakube-repo https://charts.terrakube.io helm repo update helm search repo terrakube-repo/terrakube --versions | head kubectl create namespace terrakube helm install terrakube terrakube-repo/terrakube -n terrakube ``` That command installs a **sandbox**: sample data, a demo OpenLDAP directory, and bundled PostgreSQL, MinIO and Valkey. To try it on a laptop follow [Minikube](/2.34.0/getting-started/deployment/minikube.md) or [Minikube + HTTPS](/2.34.0/getting-started/deployment/minikube-+-https.md). {% hint style="danger" %} The bundled OpenLDAP, PostgreSQL and MinIO use Bitnami images and well-known default passwords and secrets. They are for evaluation only. Use the production checklist below before exposing Terrakube to users. {% endhint %} ### Choose the Terrakube version The chart's default image tag is its `appVersion` (chart 4.7.12 ships Terrakube 2.33.1), which can lag the latest release. Pin the versions you want in your values file; they are independent per component and should match: ```yaml api: version: "2.33.3" executor: version: "2.33.3" registry: version: "2.33.3" ui: version: "2.33.3" ``` Images are published to Docker Hub as `azbuilder/api-server`, `azbuilder/executor`, `azbuilder/open-registry` and `azbuilder/terrakube-ui` (see [Docker Images](/2.34.0/getting-started/docker-images.md)). Pin the chart version too, with `helm install ... --version `, so upgrades are deliberate. ### Production checklist Create a `terrakube.yaml` and install with `helm install --values terrakube.yaml terrakube terrakube-repo/terrakube -n terrakube`. | Area | What to set | Guide | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sign-in | A real Dex connector and `security.useOpenLDAP: false`. Set `security.adminGroup` to the group whose members administer Terrakube. | [User Authentication (Dex)](/2.34.0/getting-started/deployment/user-authentication-dex.md), [User Management](/2.34.0/getting-started/user-management.md) | | Secrets | New 32-character `security.patSecret` and `security.internalSecret`. The values in the chart are public. | [Token Security](/2.34.0/getting-started/deployment/token-security.md) | | Database | `api.defaultDatabase: false` and your own PostgreSQL, MySQL or SQL Server. Set `api.loadSampleData: false`. | [Database backend](/2.34.0/getting-started/deployment/database-backend.md) | | Redis | `api.defaultRedis: false` and an external Redis or Valkey. Required when you run more than one API or executor replica. | [External Redis](/2.34.0/getting-started/deployment/external-redis.md) | | Storage | `storage.defaultStorage: false` and S3, Azure Blob, Google Cloud Storage or your own MinIO. | [Storage backend](/2.34.0/getting-started/deployment/storage-backend.md) | | Ingress and TLS | Your controller, domains and certificates. | [Ingress Configuration](/2.34.0/getting-started/deployment/ingress-configuration.md) | | Executors | Replica count sized to peak concurrent runs (each pod runs one job at a time), or ephemeral Kubernetes jobs. | [Self-Hosted Agents](/2.34.0/getting-started/deployment/self-hosted-agents.md), [Ephemeral Agents](/2.34.0/getting-started/deployment/ephemeral-agents.md) | | Observability | OpenTelemetry metrics and traces. | [Open Telemetry](/2.34.0/getting-started/deployment/open-telemetry.md) | | Private CAs and proxies | Custom certificates, or a corporate proxy. | [Custom CA Certs](/2.34.0/getting-started/deployment/custom-ca-certs.md), [Proxy Configuration](/2.34.0/getting-started/deployment/proxy-configuration.md) | Any component accepts extra environment variables under `env`, which is how most Terrakube settings in this documentation are applied. Every variable and its default is listed in the [Configuration Reference](/2.34.0/reference/configuration.md): ```yaml api: env: - name: ModuleRefreshInterval value: "60" ``` ### Upgrading ```bash helm repo update helm upgrade terrakube terrakube-repo/terrakube -n terrakube --values terrakube.yaml --version ``` Database migrations run automatically when the API starts. Read [Upgrading](/2.34.0/getting-started/upgrading.md) before you upgrade: it has the chart and version compatibility table and the breaking changes for each release. {% hint style="warning" %} **Upgrading to Terrakube 2.34.0** * **Executor pool:** set `executor.emptyDirSecret: true` (chart 4.7.12 or later). From 2.34.0 the executor reads its internal secret from a file and removes it after loading, so the file must be in a writable volume. The chart copies the secret into an `emptyDir` with an init container (`executor.initSecretImage`, default `busybox`). * **Ephemeral executors:** the API now mounts the executor secret into each ephemeral job as files instead of environment variables (`ExecutorEphemeralEmptyDirSecret`, default `true`). The executor image used for ephemeral jobs must therefore be 2.34.0 or later. If you pin an older ephemeral executor image, set `ExecutorEphemeralEmptyDirSecret=false` on the API. Upgrade the API, executor, registry and UI together. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.terrakube.io/2.34.0/getting-started/deployment/helm-chart.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.