Cookbook: Add a New Environment

Audience: Operator who needs to add a staging, dev, or DR environment alongside an existing production deployment.

When to use this

You already have a working deployment (e.g., deploy-prd.yaml pointing to env-prd.yaml). You want to create a second environment — same infrastructure blueprint, different settings.

Step-by-step

1. Copy the existing environment file

cp envs/env-prd.yaml envs/env-stg.yaml

2. Edit the new environment

Change the name, description, and any environment-specific values:

apiVersion: strata.huybrechts.xyz/v1
kind: environment
meta:
  name: haven_env_stg                          # ← unique name
  annotations:
    description: Staging environment for Haven
  labels:
    version: "1.0.0"
  tags: [haven, staging]
spec:
  variables:
    - key: WORKSPACE
      store: constant
      value: haven
    - key: DATACENTER
      store: constant
      value: kamatera-eu-fr
  secrets:
    # Use DIFFERENT secret references for staging
    - key: TERRAFORM_API_TOKEN
      store: bitwarden
      value: <your-staging-bitwarden-id>
    - key: KAMATERA_API_KEY
      store: bitwarden
      value: <your-staging-bitwarden-id>
    # ... (all secrets for this environment)

Key rules:

meta.name must be unique across all environments.
Secret IDs should point to staging-specific credentials — never share production secrets.
Variables that differ per environment (e.g., DATACENTER) get new values; shared ones stay the same.

3. Create a deployment file for the new environment

cp deploy/deploy-prd.yaml deploy/deploy-stg.yaml

Edit it to reference the new environment:

apiVersion: strata.huybrechts.xyz/v1
kind: deployment
meta:
  name: haven_deploy_stg                       # ← unique name
  annotations:
    description: Staging deployment for Haven
  labels:
    version: "1.0.0"
  tags: [haven, staging, deployment]
spec:
  layers:
    environment: stg

  properties:
    environment: stg

  workspace:
    name: haven_platform
    description: Haven Platform Workspace
    file: "@haven/stack/ws-platform.yaml"      # same workspace blueprint

  environments:
    - "@haven/envs/env-stg.yaml"               # ← points to staging env

  stages:
    - name: infrastructure
      type: infrastructure
      scope: all
      depends_on: null
      on_failure: stop

The workspace stays the same — that’s the point. The workspace defines WHAT to build; the environment defines HOW to customize it.

4. Validate

strata validate --file deploy/deploy-stg.yaml

Fix any errors (usually: missing secret references, name collisions, or typos in @repo/path).

5. Build and review

strata build plan --file deploy/deploy-stg.yaml

This shows what Terraform artifacts would be generated without writing anything. Review the output to confirm your staging environment looks correct.

6. Build for real

strata build run --file deploy/deploy-stg.yaml

7. Deploy (when ready)

strata deploy run --file deploy/deploy-stg.yaml

Checklist

[ ] New environment file with unique meta.name
[ ] Staging-specific secrets (never reuse production credentials)
[ ] New deployment file referencing the new environment
[ ] strata validate passes
[ ] strata build plan output reviewed
[ ] Committed to version control before deploying

Common mistakes

Mistake	Symptom	Fix
Same `meta.name` as production	Validation error: duplicate name	Use a unique name like `haven_env_stg`
Forgot to update secret references	Build fails: cannot resolve secret	Create staging secrets in your vault, update IDs
Wrong `@repo/path` in deployment	File not found error	Check repository alias in your solution config
Deployed before validating	Terraform errors with incomplete config	Always run `strata validate` first