DirectorySecurity AdvisoriesPricing
Sign in
Directory
temporal-worker-controller logo

temporal-worker-controller

packaged by Chainguard

Last changed
Request a free trial

Contact our team to test out this image for free. Please also indicate any other images you would like to evaluate.

Tags
Overview
Comparison
Provenance
Specifications
SBOM
Vulnerabilities
Advisories

Chainguard Container for temporal-worker-controller

Temporal Worker Controller is a Kubernetes controller that safely rolls out versioned Temporal workers using Temporal Worker Deployment versioning.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/temporal-worker-controller:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

Chainguard's temporal-worker-controller image is comparable to the upstream temporalio/temporal-worker-controller image and works with the upstream Helm charts. Like upstream, it runs as the nonroot user 65532, uses /app as its working directory, sets SSL_CERT_FILE to the system CA bundle, and starts the controller through the temporal-worker-controller entrypoint. The binary is installed at /usr/bin/temporal-worker-controller instead of /usr/local/bin/temporal-worker-controller. The upstream chart passes only arguments to the container, so this makes no difference when deploying with it.

A FIPS-enabled variant is available as temporal-worker-controller-fips.

Prerequisites

  • A Temporal server running version 1.29.1 or later, or a Temporal Cloud namespace. The controller manages worker versions through Temporal's Worker Deployment versioning APIs.
  • cert-manager in the cluster. By default the controller chart issues the serving certificate for the controller's admission webhook through cert-manager. The upstream project describes other ways to provide the webhook certificate.

Getting Started

The controller is deployed with the upstream Helm charts, which are published as OCI artifacts on Docker Hub. The temporal-worker-controller-crds chart installs the custom resource definitions and must be installed first:

helm install temporal-worker-controller-crds \
  oci://docker.io/temporalio/temporal-worker-controller-crds \
  --namespace temporal-system --create-namespace

The controller chart protects the controller's metrics endpoint with a kube-rbac-proxy sidecar. Create a values.yaml that points the chart at this image, and at Chainguard's kube-rbac-proxy image for that sidecar:

cat > values.yaml <<EOF
image:
  repository: cgr.dev/ORGANIZATION/temporal-worker-controller
  tag: latest
kubeRBACProxy:
  image:
    registry: cgr.dev
    repository: ORGANIZATION/kube-rbac-proxy
    tag: latest
EOF

Then install the controller chart:

helm install temporal-worker-controller \
  oci://docker.io/temporalio/temporal-worker-controller \
  --namespace temporal-system \
  --values values.yaml --wait

The two charts are released together, so install them at the same version. Confirm the controller is running:

kubectl rollout status deployment/temporal-worker-controller-manager -n temporal-system

Roll out a worker

A Connection tells the controller how to reach Temporal, and a WorkerDeployment describes the worker the controller manages. The following example connects to a self-hosted Temporal frontend and rolls out each new worker version progressively: it routes 10% and then 50% of new workflows to the new version, pausing for 5 and then 10 minutes, before making it the current version. Replace TEMPORAL_FRONTEND with the address of your Temporal frontend and WORKER_IMAGE with your worker image:

kubectl apply -f - <<EOF
apiVersion: temporal.io/v1alpha1
kind: Connection
metadata:
  name: temporal
  namespace: default
spec:
  hostPort: TEMPORAL_FRONTEND:7233
---
apiVersion: temporal.io/v1alpha1
kind: WorkerDeployment
metadata:
  name: my-worker
  namespace: default
spec:
  replicas: 3
  rollout:
    strategy: Progressive
    steps:
      - rampPercentage: 10
        pauseDuration: 5m
      - rampPercentage: 50
        pauseDuration: 10m
  sunset:
    scaledownDelay: 1h
    deleteDelay: 24h
  workerOptions:
    connectionRef:
      name: temporal
    temporalNamespace: default
  template:
    spec:
      containers:
        - name: worker
          image: WORKER_IMAGE
EOF

The controller creates a Deployment for each worker version and sets TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE, TEMPORAL_DEPLOYMENT_NAME, and TEMPORAL_WORKER_BUILD_ID in the worker containers. The worker must use these values to enable Worker Versioning when it connects to Temporal, so that each version registers once its pods start polling. Check the rollout state with:

kubectl get workerdeployment my-worker -n default

Changing the worker's image, or any other part of the pod template, creates a new version. The controller ramps it up according to the rollout steps, then drains and scales down the previous version.

Configuration

To connect to Temporal Cloud with an API key, store the key in a Secret in the same namespace as the WorkerDeployment and reference it from the Connection. Replace API_KEY with your key and TEMPORAL_CLOUD_ENDPOINT with the gRPC endpoint of your Temporal Cloud namespace, as the Temporal Cloud UI shows it with its :7233 port:

kubectl create secret generic temporal-cloud-api-key \
  --namespace default --from-literal=api-key=API_KEY

kubectl apply -f - <<EOF
apiVersion: temporal.io/v1alpha1
kind: Connection
metadata:
  name: temporal-cloud
  namespace: default
spec:
  hostPort: TEMPORAL_CLOUD_ENDPOINT
  apiKeySecretRef:
    name: temporal-cloud-api-key
    key: api-key
EOF

To use mutual TLS instead, reference a Secret that holds tls.crt and tls.key with mutualTLSSecretRef. When the Temporal frontend uses a private certificate authority, put its certificate in the same Secret under ca.crt. Set tls.serverName only when the frontend's certificate does not name the hostPort host. A Secret that cert-manager issues from a CA Issuer already carries all three keys. The Connection rejects tls.caCertSecretRef alongside mutualTLSSecretRef, since that field is only for API key and credential-free connections.

By default the controller watches every namespace. To limit it to specific namespaces, list them in the chart's rbac.restrictWatchNamespaces value. To see every value the chart accepts:

helm show values oci://docker.io/temporalio/temporal-worker-controller

Documentation and Resources

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.

Licenses

Chainguard's container images contain software packages that are direct or transitive dependencies. The following licenses were found in the "latest" tag of this image:

    For a complete list of licenses, please refer to this Image's SBOM.

    Software license agreement

    Compliance

    Chainguard Containers are SLSA Level 3 compliant with detailed metadata and documentation about how it was built. We generate build provenance and a Software Bill of Materials (SBOM) for each release, with complete visibility into the software supply chain.

    SLSA compliance at Chainguard

    This image helps reduce time and effort in establishing PCI DSS 4.0 compliance with low-to-no CVEs.

    PCI DSS at Chainguard

    Category
    Application

    The trusted source for open source

    Talk to an expert
    PrivacyTerms

    Product

    Chainguard ContainersChainguard LibrariesChainguard VMsChainguard OS PackagesChainguard ActionsChainguard Agent SkillsIntegrationsPricing
    © 2026 Chainguard, Inc. All Rights Reserved.
    Chainguard® and the Chainguard logo are registered trademarks of Chainguard, Inc. in the United States and/or other countries.
    The other respective trademarks mentioned on this page are owned by the respective companies and use of them does not imply any affiliation or endorsement.