# Kubernetes Setup for Releases

Prepare Helm installations, identity, connectivity, and operators for self-hosted promotion

Prepare separate development and production SteelEngine installations before testing promotion. Add staging when your release policy requires independent validation.

The Helm configuration below enables promotion, including the supported organization Git workflow path. Organization repository configuration, target workspace mapping and public trust still need setup. It does not configure blue/green traffic or trigger coordination. Complete the ordinary [Kubernetes installation](/self-hosting/kubernetes) and [Temporal setup](/self-hosting/temporal) first.

## Environment Inventory

Record these values in the customer handoff. Store secret references rather than secret values.

| Item                            | Development                           | Production                              |
| ------------------------------- | ------------------------------------- | --------------------------------------- |
| Public origin                   | `https://dev.steelengine.example.com` | `https://steelengine.example.com`       |
| Kubernetes namespace            | `steelengine-dev`                     | `steelengine-prod`                      |
| Persistent deployment identity  | A unique UUID generated once          | A different UUID generated once         |
| Promotion environment key       | `dev`                                 | `prod`                                  |
| Temporal namespace              | Dedicated development namespace       | Dedicated production namespace          |
| Database and object storage     | Development resources                 | Independent production resources        |
| Organization Git branch mapping | `dev`                                 | `prod`                                  |
| Provider accounts               | Test/sandbox accounts                 | Explicitly approved production accounts |

Separate namespaces alone do not isolate data or credentials. Verify database endpoints, storage prefixes/buckets, secret access, Temporal authorization, and network policy. Development must not receive production credentials through shared defaults.

## Prepare the Cluster

1. Pin the chart revision and compatible web, worker, realtime, and migration image versions. The reviewed chart uses image repository/tag settings; record the resolved image digests and avoid mutable `latest` tags for a pilot.
2. Provision persistent PostgreSQL, object storage, Temporal, TLS, registry access, and secret management using the base installation guide. Plan capacity for retained releases and rollback material.
3. Configure the stable public application and authentication origins. Keep the production origin stable across future blue/green slots.
4. Provision the main worker and document worker broker secrets with the scopes described in the Kubernetes guide. Do not reuse the general internal API secret as a broker secret.
5. Confirm health, migrations, worker polling, clock synchronization, backup restoration, and ordinary workflow execution before enabling promotion.

The current document worker uses a native sidecar and requires Kubernetes 1.29 or later. Validate the client cluster against the delivered chart and supported version policy, including its admission and network policies.

## Promotion Values Overlay

This is a partial overlay for an already configured installation. Replace the example UUID once and retain it across pod restarts and Helm upgrades. Use a different identity for each independent installation. Do not derive it from a pod, Helm revision, or blue/green color.

```yaml
app:
  env:
    PROMOTION_ENABLED: "true"
    PROMOTION_DEPLOYMENT_ID: "9c6cf304-8bcb-4ed1-9e07-5c7a7bd7e206"
    PROMOTION_ENVIRONMENT_KEY: "dev"

worker:
  env:
    PROMOTION_ENABLED: "true"
    PROMOTION_DEPLOYMENT_ID: "9c6cf304-8bcb-4ed1-9e07-5c7a7bd7e206"
    PROMOTION_ENVIRONMENT_KEY: "dev"

documentWorker:
  enabled: true

cronjobs:
  enabled: true
  jobs:
    promotionNotifications:
      enabled: true
```

Set promotion variables explicitly on both `app.env` and `worker.env`; do not assume arbitrary application variables are forwarded. The document worker inherits the worker environment. Confirm the rendered configuration gives web and both worker roles the same deployment UUID and Temporal namespace. Inspect variable names and non-secret identity values without dumping Secret contents.

Provision `CRON_SECRET` through the app Secret. In the reviewed chart, the CronJob reads the literal `CRON_SECRET` key when `app.env.CRON_SECRET` is unset. A differently named Secret key needs matching chart support; do not assume a custom key mapping reaches the CronJob. The job calls `/api/cron/promotion-notifications` every minute to recover notification delivery.

Keep secrets out of checked-in values and terminal history. Use the chart's existing-Secret integration and your approved secret manager. Helm rendering can include secret material; handle rendered output as confidential. See [Helm upgrade documentation](https://helm.sh/docs/helm/helm_upgrade/).

## Validate Before Installing the Overlay

Use the complete, non-secret values file for that environment and the partial overlay. These commands render locally and do not install a release:

```bash
helm lint ./helm/steelengine \
  --values customer-values.yaml \
  --values promotion-values.yaml

helm template steelengine ./helm/steelengine \
  --namespace steelengine-dev \
  --values customer-values.yaml \
  --values promotion-values.yaml > rendered-private.yaml
```

Verify Secret references, origins, namespace, worker identities, migration behavior, and CronJob authentication. Apply through the customer's normal reviewed Helm pipeline. The feature flag is disabled by default, is rejected on hosted SteelEngine, and does not grant users or API keys additional permissions.

## Establish Trust and Access

1. Identify the source and target organization IDs and every workspace. Record who may configure trust, bind resources, approve releases, and activate production.
2. Configure each installation's organization environment policy with the existing CLI/API.
3. Create an installation signing key and independently provision the trust authority. Distribute signed trust snapshots to recipients through the approved channel.
4. Configure target integration accounts and resource assignments. Development's credentials must not become production's default.
5. Rehearse the supported workflow file path before expanding scope. Current enrollment is permanent through the API and target enrollment requires a workspace without workflows or workflow folders, including archived entries.

The GitHub App proves repository access. The promotion signer and trust authority prove release provenance. They are separate identities and neither substitutes for the other.

## Readiness Evidence

Retain the chart commit, resolved image digests, migration result, installation identities, worker readiness, a successful notification sweep, and a tested backup/restore record. Add the source/target workspace mapping and integration inventory. Redact tokens, private keys, raw Secret manifests, and connection strings from the client acceptance packet.

Do not install a second complete Helm release against production merely to name it green. The chart can start migrations, CronJobs, workers, and schedules; isolated traffic routing alone does not prevent duplicate side effects. Review [Blue/Green Operation](/self-hosting/releases/blue-green) before designing that topology.