DOCSEARCHbyAlgolia
Submit Docs

Temporal Helm Charts

repository·main·Indexed 20 days ago

https://github.com/temporalio/helm-charts

Helm charts for deploying the Temporal orchestration engine and Temporal Proxy to Kubernetes clusters. The charts focus on server components and require users to provide their own database persistence (MySQL, PostgreSQL, Cassandra, or Elasticsearch). Includes configurations for secret-aware credentials, TLS for gateways and upstreams, and support for sidecar containers.

Tokens
8.7K
Snippets
28
Records
36
Agent score
69%

What's inside temporalio-helm-charts

  1. Manage Schema Setup and Deployment Ordering

    main

    By default, the Temporal Helm chart uses Helm hooks (pre-install, pre-upgrade) to ensure that database and Elasticsearch schemas are initialized before the server pods start.

    ArgoCD Users: ArgoCD maps Helm hooks to its own sync waves. If you are using ArgoCD-native hooks, Helm hooks will be ignored.

    Flux, Rancher, or Terraform Users: If you require explicit control over deployment ordering and do not want to use Helm hooks, set useHelmHooks: false in your configuration.

  2. Configure Admin tools and Namespace creation frontend

    main

    By default, the admin-tools Deployment and the namespace-setup Job connect to the internal-frontend. The internal-frontend allows these tools to perform administrative operations without going through an external Authorizer/ClaimMapper.

    If you want to route these tools through the external frontend (making them subject to your Authorizer), set the following:

    • For admin tools: admintools.useExternalFrontend: true
    • For namespace-setup Job: server.config.namespaces.useExternalFrontend: true

    Note: If you route them through the external frontend and have an Authorizer enabled, you must provide admin credentials (e.g., via admintools.additionalEnv or admintools.additionalEnvSecretName).

  3. Understand Temporal Helm Chart scope and persistence

    main

    The Temporal Helm Chart is designed to deploy only the Temporal server components. It does not include sub-charts for databases.

    To make Temporal functional, you must configure persistence for one of the following supported databases:

    • MySQL
    • PostgreSQL
    • Cassandra
    • Elasticsearch

    The persistence configuration in the Helm chart follows the standard raw Temporal server configuration format.

  4. Use secret-aware credentials for upstreams and auth

    main

    To avoid storing sensitive credentials in plaintext within the ConfigMap, two specific fields support a secretKeyRef object instead of a plain string:

    1. upstreams[].credentials.static.apiKey
    2. auth.staticToken.token

    When using secretKeyRef, the chart automatically:

    1. Adds an environment variable to the proxy container sourced from the specified Secret.
    2. Rewrites the configuration value to use the ${VAR} syntax so the proxy substitutes it at startup.

    Generated Environment Variable Names:

    • For upstreams[].credentials.static.apiKey: TP_UPSTREAM_<NAME>_API_KEY, where <NAME> is the upstream's name converted to uppercase and non-alphanumeric characters are replaced with _.
    • For auth.staticToken.token: TP_AUTH_STATIC_TOKEN.

    Example: Using an upstream named cloud with a secret named temporal-cloud and key api-key will result in the environment variable TP_UPSTREAM_CLOUD_API_KEY being injected.

    config:
  upstreams:
    - name: cloud
      hostPort: localhost:7233
      credentials:
        static:
          apiKey:
            secretKeyRef:
              name: temporal-cloud
              key: api-key

  5. Install Temporal with Cassandra

    main

    To use a Cassandra cluster for the default store, use the values/values.cassandra.yaml template.

    Important: Cassandra cannot be used for the visibility store. You must configure a separate SQL or Elasticsearch datastore for visibility.

    helm install --repo https://go.temporal.io/helm-charts -f cassandra.values.yaml temporal temporal --timeout 900s

  6. Install Temporal with PostgreSQL

    main

    To install Temporal using a PostgreSQL database, use the provided values/values.postgresql.yaml template. Edit the file with your connection details and run the Helm install command.

    helm install --repo https://go.temporal.io/helm-charts -f postgresql.values.yaml temporal temporal --timeout 900s

  7. Run the Temporal CLI from the admin-tools container

    main

    The Helm chart includes an admin-tools container that provides access to the temporal CLI. You can shell into this container using kubectl exec to perform administrative tasks like managing namespaces.

    To access the CLI, execute a bash shell in the temporal-admintools service.

    $ kubectl exec -it services/temporal-admintools /bin/bash
bash-5.0#

# Example: List namespaces
bash-5.0# temporal operator namespace list

# Example: Create a namespace
bash-5.0# temporal operator namespace create -n nonesuch

  8. Install Temporal with Elasticsearch for visibility

    main

    To use Elasticsearch for the visibility store, configure the visibility datastore with the elasticsearch: key in your values file. You must still provide a separate datastore (SQL or Cassandra) for the default store.

    helm install --repo https://go.temporal.io/helm-charts -f elasticsearch.values.yaml temporal temporal --timeout 900s

  9. Install Temporal with MySQL

    main

    To install Temporal using a MySQL database, use the provided values/values.mysql.yaml template. Edit the file with your connection details and run the Helm install command.

    helm install --repo https://go.temporal.io/helm-charts -f mysql.values.yaml temporal temporal --timeout 900s

  10. Install Temporal with sidecar containers (e.g., Cloud SQL Proxy)

    main

    If your database requires a proxy (such as Google Cloud SQL Proxy), you can provide sidecar containers via the Helm values file.

    Example installation using a specific values file for a Cloud SQL proxy:

    helm install --repo https://go.temporal.io/helm-charts -f values/values.cloudsqlproxy.yaml temporal temporal --timeout 900s

  11. Upgrade the Temporal cluster

    main

    Upgrading requires a two-step process:

    1. Upgrade your database schema (if the new release includes schema changes).
    2. Perform a rolling upgrade of the installation using helm upgrade.

    Compatibility Notes:

    • Not Supported: Running newer binaries with an older schema.
    • Supported: Running older binaries with a newer schema (downgrading binaries).

  12. Install the Temporal Helm Chart

    main

    The Temporal Helm Chart (V3) deploys the Temporal server components to a Kubernetes cluster. Note that this chart does not install databases; you must provide your own persistence (MySQL, PostgreSQL, Cassandra, or Elasticsearch) following the raw Temporal server configuration format.

    Prerequisites

    • A configured Kubernetes cluster (e.g., AWS EKS, kind, or minikube).
    • kubectl installed and configured to access your cluster.
    • Helm v3 installed.

    Installation Methods

    Method 1: Using the Helm Repository (Recommended)

    This is the preferred method as it uses tested releases and avoids cloning the repository.

    1. Add the Temporal Helm repo:
      helm repo add temporal https://go.temporal.io/helm-charts/
helm repo update
    2. Install the chart using helm install with the --repo flag pointing to https://go.temporal.io/helm-charts/.

    Method 2: Local Git Clone (For Testing Changes)

    Use this method only if you are testing modifications to the chart itself.

    1. Clone the repository.
    2. Navigate to the chart directory:
      cd charts/temporal
    3. Install from the local directory:
      helm install <release-name> .

    Note: If you use the Helm repository method, any values.yaml files used in examples must be downloaded manually from GitHub, as they are not included in the Helm repo.

    helm repo add temporal https://go.temporal.io/helm-charts/
helm repo update