> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret Env Var Syncer

## Overview

The Secret Env Var Syncer (SEVS) runs as a cron workload that syncs keys from Control Plane dictionary secrets into environment variables on GVCs or individual workload containers. It runs on a configurable schedule, applies the changes, then exits.

### How It Works

SEVS runs as a cron workload on Control Plane. Your sync configuration is stored in a Control Plane secret and mounted into the workload as `config.yaml`. On each execution, SEVS reads the list of entries, fetches the specified dictionary secrets, and applies their keys as environment variables to the target GVCs or workload containers. The job then exits until the next scheduled run.

Env var values are written as `cpln://secret/SECRET_NAME.KEY_NAME` references — not raw values. This means the target resource resolves the secret reference at runtime rather than storing the value inline.

SEVS skips the `PUT` request when the target already matches the desired env vars, making each run idempotent.

### What Gets Created

* **Cron SEVS Workload** — A cron workload that reads the mounted config, syncs dictionary secret keys as environment variable references to each configured target, then exits.
* **Identity** — An identity bound to the workload, used to authenticate against the Control Plane API.
* **Policies** — Three policies granting the identity `reveal` on all secrets, `edit` on all GVCs, and `edit` on all workloads.
* **Secret** — An opaque secret containing the sync configuration (`config.yaml`), mounted into the workload at `/app/config.yaml`.

<Note>
  This template does not create a GVC. You must deploy it into an existing GVC.
</Note>

## Prerequisites

* One or more Control Plane [dictionary secrets](/reference/secret) containing the key-value pairs you want to sync as environment variables.

### Installation

To install, follow the instructions for your preferred method:

<CardGroup cols={2}>
  <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
    Browse, install, and manage templates visually
  </Card>

  <Card title="CLI" href="/template-catalog/install-manage/cli" icon="terminal">
    Manage templates from your terminal
  </Card>

  <Card title="Terraform" href="/template-catalog/install-manage/terraform" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><g fill-rule="evenodd"><path d="M77.941 44.5v36.836L46.324 62.918V26.082zm0 0" fill="#5c4ee5"/><path d="M81.41 81.336l31.633-18.418V26.082L81.41 44.5zm0 0" fill="#4040b2"/><path d="M11.242 42.36L42.86 60.776V23.941L11.242 5.523zm0 0M77.941 85.375L46.324 66.957v36.82l31.617 18.418zm0 0" fill="#5c4ee5"/></g></svg>}>
    Declare templates in your Terraform configurations
  </Card>

  <Card
    title="Pulumi"
    href="/template-catalog/install-manage/pulumi"
    icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" id="Pulumi-Icon--Streamline-Svg-Logos" height="24" width="24">
    <desc>
        Pulumi Icon Streamline Icon: https://streamlinehq.com
    </desc>
    <path fill="#f26e7e" d="M4.683025 13.3318c0.869125 -0.5018 0.870575 -2.1264 0.003225 -3.62865s-2.27504 -2.313275 -3.1441725 -1.811475C0.672945 8.3935 0.6715 10.0181 1.53885 11.52035c0.86735 1.502275 2.27505 2.313275 3.144175 1.81145Zm0.0052 3.2167c0.86735 1.502275 0.865925 3.126875 -0.003225 3.628675 -0.86915 0.5018 -2.2768275 -0.309225 -3.144175 -1.81145 -0.8673525 -1.50225 -0.8659075 -3.126875 0.003225 -3.628675 0.8691325 -0.5018 2.276825 0.309225 3.144175 1.81145Zm5.922875 3.4243c0.86735 1.50225 0.8659 3.126775 -0.003225 3.62875 -0.869125 0.501775 -2.27685 -0.309325 -3.1442 -1.81155 -0.867325 -1.50225 -0.865875 -3.12685 0.00325 -3.628675 0.869125 -0.5018 2.276825 0.309225 3.144175 1.811475Zm-0.001925 -6.845275c0.86735 1.50225 0.8659 3.12685 -0.003225 3.628675 -0.869125 0.5018 -2.276825 -0.309225 -3.144175 -1.811475 -0.86735 -1.50225 -0.8659 -3.12685 0.003225 -3.62865 0.869125 -0.501825 2.276825 0.3092 3.144175 1.81145Z" stroke-width="0.25"></path>
    <path fill="#8a3391" d="M22.45775 11.524125c0.86725 -1.502225 0.865925 -3.12685 -0.003225 -3.62865 -0.869125 -0.501825 -2.276825 0.3092 -3.144175 1.811475 -0.86735 1.50225 -0.8659 3.126825 0.003225 3.62865 0.869125 0.501825 2.276825 -0.3092 3.144175 -1.811475Zm0.000175 3.2151c0.869075 0.5018 0.870625 2.1264 0.003225 3.62865 -0.86735 1.50225 -2.27505 2.313275 -3.144175 1.81145 -0.869125 -0.5018 -0.870575 -2.126425 -0.003225 -3.62865 0.86735 -1.50225 2.27505 -2.313275 3.144175 -1.81145ZM16.536225 18.157875c0.86915 0.501825 0.8706 2.126425 0.00325 3.628675 -0.86735 1.502125 -2.275075 2.313225 -3.1442 1.81145 -0.869125 -0.50175 -0.870575 -2.126425 -0.003225 -3.62865 0.867375 -1.502275 2.27505 -2.3133 3.144175 -1.811475Zm-0.003325 -6.843775c0.869125 0.5018 0.870575 2.126425 0.003225 3.628675s-2.27505 2.313275 -3.1442 1.811475c-0.869125 -0.501825 -0.870575 -2.126425 -0.003225 -3.628675 0.86735 -1.502275 2.27505 -2.313275 3.1442 -1.811475Z" stroke-width="0.25"></path>
    <path fill="#f7bf2a" d="M15.138225 2.06721c0 1.003615 -1.40625 1.817215 -3.14095 1.817215 -1.7347 0 -3.14095 -0.8136 -3.14095 -1.817215C8.856325 1.06359 10.262575 0.25 11.997275 0.25c1.7347 0 3.14095 0.81359 3.14095 1.81721ZM9.2166 5.482375c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172s1.40625 -1.817225 3.14095 -1.817225c1.7347 0 3.14095 0.8136 3.14095 1.817225Zm8.71005 1.8172c1.7347 0 3.14095 -0.813575 3.14095 -1.8172s-1.40625 -1.817225 -3.14095 -1.817225c-1.7347 0 -3.14095 0.8136 -3.14095 1.817225s1.40625 1.8172 3.14095 1.8172Zm-2.788425 1.605625c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172 0 -1.0036 1.40625 -1.8172 3.14095 -1.8172 1.7347 0 3.14095 0.8136 3.14095 1.8172Z" stroke-width="0.25"></path>
    </svg>}
  >
    Declare templates in your Pulumi programs
  </Card>
</CardGroup>

## Configuration

The default `values.yaml` for this template:

```yaml theme={null}
image: ghcr.io/controlplane-com/cpln-build/secret-env-var-syncer:v1.3.1

resources:
  cpu: 100m
  memory: 256Mi

schedule: "*/5 * * * *" # Default: every 5 minutes. Uses standard cron syntax (minute hour day month weekday).

timeoutSeconds: 300 # Maximum time allowed for a single sync run. Increase if you have a large number of entries.

sevsConfig:
  entries:
    - target:
        type: gvc
        name: my-gvc
      secret: my-dictionary-secret
    # - target:
    #     type: workload
    #     name: my-workload
    #     gvc: my-gvc
    #     container: app
    #   secret: my-dictionary-secret
```

### Top-Level Fields

* `image` — The SEVS container image. Do not change unless upgrading.
* `resources.cpu` / `resources.memory` — Resource limits for the workload container.
* `schedule` — Cron expression controlling how often the sync runs (default: `*/5 * * * *`).
* `timeoutSeconds` — Maximum time allowed for a single sync run (default: `300`). Increase if you have a large number of entries.
* `sevsConfig` — The full sync configuration — a list of entries (see below).

### Entries

Each entry in `sevsConfig.entries` syncs the keys of one Control Plane dictionary secret into the environment variables of one target.

| Field    | Description                                                  |
| -------- | ------------------------------------------------------------ |
| `target` | The resource to apply env vars to (see target types below)   |
| `secret` | The name of the Control Plane dictionary secret to read from |

#### Target: GVC

Applies all keys from the dictionary secret as environment variables on the entire GVC:

```yaml theme={null}
- target:
    type: gvc
    name: my-gvc
  secret: my-dictionary-secret
```

#### Target: Workload

Applies all keys from the dictionary secret as environment variables on a specific container within a workload:

```yaml theme={null}
- target:
    type: workload
    name: my-workload
    gvc: my-gvc
    container: app
  secret: my-dictionary-secret
```

<Note>
  The `container` field is required for workload targets. The `gvc` field is required when the workload is in a different GVC than the one SEVS is deployed in.
</Note>

### Synced Env Var Format

Each dictionary key becomes an environment variable name on the target. The value is written as a Control Plane secret reference — not the raw secret value:

```
cpln://secret/SECRET_NAME.KEY_NAME
```

The target GVC or workload resolves this reference at runtime.

## Permissions

SEVS requires the following permissions on its identity, all of which are created automatically by the template:

| Resource Kind | Permission | Reason                                                                          |
| ------------- | ---------- | ------------------------------------------------------------------------------- |
| `secret`      | `reveal`   | Read the dictionary secrets listed in each entry, and the mounted `config.yaml` |
| `gvc`         | `edit`     | Write environment variables to GVC targets                                      |
| `workload`    | `edit`     | Write environment variables to workload container targets                       |

## Important Notes

* **Dictionary secrets only** — Source secrets must be of type `dictionary`. Opaque secrets are not supported as sync sources.
* **One-shot execution** — SEVS runs once per schedule tick and exits. It is not a long-running daemon.
* **Concurrency** — The job uses `concurrencyPolicy: Forbid`. If a previous run is still active when the next schedule fires, the new run is skipped.
* **Idempotent** — SEVS skips the update when the target already matches the desired env vars.
* **Env var overwrite** — Existing environment variables on the target with the same key will be overwritten on each run.

## External References

<CardGroup cols={2}>
  <Card title="SEVS Image Source" icon="github" href="https://github.com/controlplane-com/secret-env-var-syncer">
    Source code for the Secret Env Var Syncer image
  </Card>

  <Card title="SEVS Template" icon="github" href="https://github.com/controlplane-com/templates/tree/main/secret-env-var-syncer">
    View the source files, default values, and chart definition
  </Card>
</CardGroup>