ESS (External Secret Syncer)

Overview

The External Secret Syncer (ESS) keeps Control Plane secrets in step with an external secret store. It polls each configured provider on an interval and creates or updates the matching Control Plane secret, so your workloads consume ordinary Control Plane secrets while the source of truth stays in HashiCorp Vault, AWS Secrets Manager, AWS Parameter Store, GCP Secret Manager, 1Password, 1Password Connect, Doppler or Infisical. Your provider connections and the list of secrets to sync live in a sync.yaml file that you store as an opaque secret before installing. It carries provider credentials, so it is never a Helm value. Every secret ESS writes is tagged syncer.cpln.io/source with the ESS workload, and ESS refuses to overwrite a secret tagged by a different ESS instance.

This template does not create a GVC. It deploys into an existing GVC that you already have.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-ess`	The syncer (standard, 1 to 3 replicas on CPU), admin API on port `3004`, health check `GET /about`	—
Identity	`RELEASE_NAME-ess-identity`	Workload identity ESS calls the Control Plane API as	—
Policy	`RELEASE_NAME-ess-policy`	Grants the identity `manage` on every secret in the org (`targetKind: secret`, `target: all`)	—

The policy is org-wide, regardless of which secrets you sync. It grants manage on every secret in the org, not just the targets named in sync.yaml. Anything that can run as RELEASE_NAME-ess-identity can read, change and delete every secret in the org. Treat the ESS workload as security-sensitive, keep allowedIp narrow, and restrict who can edit the release, its sync.yaml secret and the workload.

The template creates no secret of its own: it mounts the secret named by configSecretName at /usr/src/app/sync.yaml. The identity carries no cloud-provider binding, so every provider authenticates with the credentials you put in sync.yaml.

Prerequisites

One opaque secret holding your entire sync.yaml must exist before you install. Secrets are org-level, so no GVC flag is involved.

Gather read-only provider credentials

ESS only reads from your providers. Create a credential scoped to the secrets you want synced:

Provider	Credential in `sync.yaml`	Access ESS needs
HashiCorp Vault	`vault.token`	Read on the paths you sync
AWS Parameter Store	`accessKeyId` and `secretAccessKey`	`ssm:GetParameter` on the parameters you sync
AWS Secrets Manager	`accessKeyId` and `secretAccessKey`	`secretsmanager:GetSecretValue` on the secrets you sync
GCP Secret Manager	`credentials.clientEmail` and `credentials.privateKey` of a service account	Secret Accessor on the secrets you sync, plus permission to list secrets for `dictionaryFromProject` and `discoverAllSecrets`
1Password	`serviceAccountToken`	A service account with read access to the vaults you sync
1Password Connect	`serverURL` and `token`	A Connect token for your Connect server
Doppler	`accessToken`	A Doppler service token (`dp.st.…`)
Infisical	`clientId`, `clientSecret` and `projectId`	An Infisical machine identity with read access to the project

Write your sync.yaml

A minimal file that syncs one Vault value into an opaque Control Plane secret. The full schema is under Configuration.

# sync.yaml
providers:
  - name: my-vault
    vault:
      address: https://my-vault.com:8200
      token: YOUR-VAULT-TOKEN
    syncInterval: 1m
secrets:
  - name: my-app-secret
    provider: my-vault
    opaque:
      path: /v1/secret/data/my-app
      parse: data.password

Store it as an opaque secret

cat sync.yaml | cpln secret create-opaque --name SECRET_NAME --encoding plain -f -

Set configSecretName to this name. Secret names are org-wide, so give each release its own. Read it back any time with:

cpln secret reveal SECRET_NAME -o yaml

If the secret does not exist at install time, the deployment wedges silently. cpln logs returns zero lines, because the container never starts. The missing secret is named only in status.versions[].message:

cpln workload get-deployments RELEASE_NAME-ess --gvc GVC_NAME -o yaml

Use get-deployments; plain cpln workload get has no versions key. The deployment recovers on its own once the secret exists, or force a redeployment to skip the wait.

Installation

Once the secret exists, install from the marketplace registry with its name:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/ess \
  --version 2.1.1 --gvc GVC_NAME \
  --set configSecretName=SECRET_NAME

Or follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image and Resources

image: ghcr.io/controlplane-com/cpln-build/external-secret-syncer:v2.0.2

resources:
  cpu: 200m
  memory: 256Mi

resources sets the container limits. Change image only when moving to a newer ESS release.

Admin API Access

port: 3004

allowedIp:
  - 1.2.3.4 # Replace with your IP

port is the ESS admin API, used by the /about health check. allowedIp lists the CIDRs that may reach the admin API on its public endpoint; the shipped 1.2.3.4 is a placeholder that admits nobody. Other workloads in the GVC cannot reach the admin API.

Sync Configuration Secret

configSecretName: my-ess-config

configSecretName names the opaque secret holding your sync.yaml (see Prerequisites). The rest of this section is the schema of that file: a providers list and a secrets list.

Providers

Each provider has a unique name and exactly one provider block. An optional syncInterval sets the default interval for every secret that uses it.

providers:
  # HashiCorp Vault
  - name: my-vault
    vault:
      address: https://my-vault.com:8200   # required
      token: YOUR-VAULT-TOKEN              # required
    syncInterval: 1m                       # optional

  # AWS Parameter Store
  - name: my-aws-ssm
    awsParameterStore:
      region: us-east-1
      accessKeyId: YOUR-ACCESS-KEY
      secretAccessKey: YOUR-SECRET-KEY

  # AWS Secrets Manager
  - name: my-aws-secrets-manager
    awsSecretsManager:
      region: us-east-1
      accessKeyId: YOUR-ACCESS-KEY
      secretAccessKey: YOUR-SECRET-KEY

  # GCP Secret Manager
  - name: my-gcp
    gcpSecretManager:
      projectId: 123456789876
      credentials:
        clientEmail: YOUR-SERVICE-ACCOUNT-EMAIL
        privateKey: YOUR-PRIVATE-KEY

  # 1Password
  - name: my-1password
    onePassword:
      serviceAccountToken: YOUR-TOKEN
      integrationName: my-ess              # optional
      integrationVersion: 1.0.0            # optional

  # 1Password Connect
  - name: my-1password-connect
    onePasswordConnect:
      serverURL: https://my-connect-server.example.com   # required
      token: YOUR-TOKEN                                  # required

  # Doppler
  - name: my-doppler
    doppler:
      accessToken: YOUR-TOKEN              # a Doppler service token (dp.st....)

  # Infisical
  - name: my-infisical
    infisical:
      clientId: YOUR-CLIENT-ID             # required, from an Infisical machine identity
      clientSecret: YOUR-CLIENT-SECRET     # required
      projectId: YOUR-PROJECT-ID           # required

The template’s identity has no AWS or GCP binding, so supply the access keys or service-account credentials shown above for the AWS and GCP providers.

Secrets

Each entry in secrets writes one Control Plane secret. It needs a name (the Control Plane secret to create or update), a provider that matches a provider name, an optional syncInterval, and exactly one of the sync types below. opaque stores one value as an opaque secret. Use the shorthand when you need only a path:

secrets:
  - name: my-secret
    provider: my-vault
    opaque: /v1/secret/data/myapp

Or the long form for options:

secrets:
  - name: my-secret
    provider: my-vault
    opaque:
      path: /v1/secret/data/myapp    # path to fetch
      parse: data.password           # optional, extracts a key from a JSON or YAML response
      default: fallback-value        # optional, used if the fetch fails
      encoding: base64               # optional, base64-decodes the fetched value

Vault KV secrets are nested under a data key, so parse paths for Vault start with data.. With the shorthand and no default, a failed fetch fails the sync with no fallback. dictionary stores several values as a dictionary secret. Each key is fetched independently, supports the same path, parse, default and encoding options, and a failure on one key does not block the others:

secrets:
  - name: my-secret
    provider: my-vault
    dictionary:
      PORT:
        path: /v1/secret/data/app
        parse: data.port
        default: 5432
      PASSWORD:
        path: /v1/secret/data/app
        parse: data.password
      USERNAME:
        path: /v1/secret/data/app
        parse: data.username
        default: "no username"

dictionaryFromProject syncs a whole provider project into one dictionary secret. Doppler takes a project/config path; GCP Secret Manager takes true and pulls every accessible secret from the provider’s project, one key per secret:

secrets:
  - name: my-doppler-config
    provider: my-doppler
    dictionaryFromProject:
      path: my-project/dev    # "project/config"
  - name: my-gcp-config
    provider: my-gcp
    dictionaryFromProject: true

GCP secrets with no accessible latest version (no versions, disabled or destroyed) are skipped. A form that does not match its provider stops ESS at startup. dictionaryFromJson fetches one value holding a JSON object and flattens it into a dictionary secret. It works with any provider:

secrets:
  - name: json-config
    provider: my-aws-secrets-manager
    dictionaryFromJson: /example/app/config

Nested objects become dot-notation keys (db.host), arrays are stored as their JSON string, and null, numbers and booleans are stored as strings. A value that is not a JSON object is stored under a single __raw key, and ESS logs a warning. discoverAllSecrets (GCP Secret Manager only, must be true) creates a separate Control Plane secret for every accessible secret in the provider’s project:

secrets:
  - name: gcp-discover        # identifier only, created secrets are named after the GCP secrets
    provider: my-gcp
    discoverAllSecrets: true

A cpln-type: dictionary label on the GCP secret flattens its JSON value into a dictionary secret (same rules as dictionaryFromJson); cpln-type: opaque or no label stores an opaque secret.
Opaque values that are canonical base64 are marked encoding: base64, so workloads receive the decoded value. Label the GCP secret cpln-encoding: disable to store a value verbatim, for example an API key that happens to look like base64.
Names are normalized to valid Control Plane names (lowercased, unsupported characters such as _ replaced by -, so MY_API_KEY becomes my-api-key). If two names collide, the last one wins and ESS logs a warning.
Each created secret carries a syncer.cpln.io/discoveredBy tag set to the entry’s name.

Path Formats

Provider	Sync type	Path format	Example
Doppler	`opaque` or `dictionary` key	`project/config/SECRET`	`my-app/production/DATABASE_URL`
Doppler	`dictionaryFromProject`	`project/config`	`my-app/production`
Infisical	`opaque` or `dictionary` key	`environment/SECRET` in the provider’s project	`dev/DATABASE_URL`

Sync Interval

Intervals use <hours>h<minutes>m<seconds>s; every part is optional but at least one is required (10s, 5m, 1h30m). The most specific setting wins: the secret’s syncInterval, then the provider’s, then the default of 300s.

Connecting

ESS has no client endpoint of its own. Workloads consume the secrets it writes by name, exactly like any other Control Plane secret, with no dependency on ESS being reachable.

What	Address	Notes
Synced secrets	`cpln secret reveal SYNCED_SECRET_NAME -o yaml`	The `syncer.cpln.io/lastError` tag is empty after a successful sync and holds the error message after a failed one
Admin API (public)	`status.canonicalEndpoint` from `cpln workload get RELEASE_NAME-ess --gvc GVC_NAME -o yaml`	Reachable only from the CIDRs in `allowedIp`
Admin API (private)	`cpln port-forward RELEASE_NAME-ess 3004:3004 --gvc GVC_NAME`	Health check `GET /about`
Provider credentials	`cpln secret reveal SECRET_NAME -o yaml`	Your `sync.yaml`

To confirm a sync happened, read the secret back and check its tags and data:

cpln secret reveal SYNCED_SECRET_NAME -o yaml

A synced secret looks like this:

kind: secret
name: my-app-secret
tags:
  syncer.cpln.io/lastError: ''      # holds the error message if the last sync failed
  syncer.cpln.io/source: ...        # the ESS workload that manages this secret
type: dictionary
data:
  PORT: '1234'
  PASSWORD: 'no pass'               # a default used when the key was not found

The syncer logs each secret it schedules and any error it hits, by secret name:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-ess"} |= "SYNCED_SECRET_NAME"' --limit 50 --since 10m

Operations

Updating the Sync Configuration

To add a provider, add a secret or replace a credential, export the secret, edit sync.yaml in its payload, and apply it:

cpln secret reveal SECRET_NAME -o yaml > secret.yaml
# edit only the payload in secret.yaml
cpln apply -f secret.yaml
cpln secret reveal SECRET_NAME -o yaml

Then force a redeployment so the running syncer mounts the new file:

cpln workload force-redeployment RELEASE_NAME-ess --gvc GVC_NAME

Removing an entry from sync.yaml stops syncing it but leaves the Control Plane secret it created in place.

Upgrading From 2.0.x

Version 2.1.0 removes the essConfig values block. The schema is unchanged: migrating is a verbatim lift of that block into sync.yaml, minus the top-level essConfig: wrapper. Version 2.0.x does not create a GVC, so this is an ordinary in-place upgrade of the same release.

Carrying essConfig forward stops the upgrade. It is rejected at render, so cpln helm upgrade fails and your existing syncer keeps running untouched:

Error: execution error at (ess/templates/identity.yaml:1:4): ess: essConfig was REMOVED — it holds
provider credentials (Vault token, AWS keys, 1Password token), so it is now an `opaque` secret you
create, named by configSecretName, whose entire value is your sync.yaml. Delete essConfig from your
values. See Prerequisites in the README.

Move your essConfig block into sync.yaml

Copy it verbatim and drop the essConfig: wrapper, so providers: and secrets: become top-level keys.

Create the secret under a new name

cat sync.yaml | cpln secret create-opaque --name SECRET_NAME --encoding plain -f -

Do not reuse RELEASE_NAME-ess-config: that is the secret 2.0.x created, and the upgrade removes it.

Upgrade with essConfig removed

Delete essConfig from your values file, then upgrade:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/ess \
  --version 2.1.1 --gvc GVC_NAME \
  --set configSecretName=SECRET_NAME

Rotate every credential that was in your values file

They were stored in the Helm release, so treat them as exposed. Reissue the Vault token, AWS keys or 1Password service-account token, then update sync.yaml as described in Updating the Sync Configuration.

Troubleshooting

The deployment never becomes ready and cpln logs is empty

Cause: the secret named by configSecretName does not exist, so the container never starts.Fix: read status.versions[].message with cpln workload get-deployments RELEASE_NAME-ess --gvc GVC_NAME -o yaml, create the secret it names (see Prerequisites), and wait for the deployment to recover or force a redeployment.

The syncer restarts with Error parsing sync config

Cause: sync.yaml does not match the schema. Common messages are Secrets must only reference one secret type, Provider must have exactly one provider, Secrets must have a valid provider and Provider names must be unique.Fix: correct the file against Sync Configuration Secret, re-apply the secret and force a redeployment.

A synced secret shows an error in syncer.cpln.io/lastError

Cause: ESS could not fetch the value from the provider, for example a wrong path, an expired token or missing read access. On Doppler, parse on a value that is not JSON or YAML also fails.Fix: read the message from the tag with cpln secret reveal SYNCED_SECRET_NAME -o yaml, fix the path or credential in sync.yaml, and apply it. The tag clears on the next successful sync.

Sync fails with Secret is managed by another ESS

Cause: the target secret’s syncer.cpln.io/source tag names a different ESS workload, for example a release installed earlier under another name.Fix: sync into a different secret name, or delete the existing secret so this ESS can create it.

The admin API endpoint refuses connections

Cause: allowedIp still holds the 1.2.3.4 placeholder, or your address is not in it.Fix: set allowedIp to your CIDR and upgrade, or reach the API privately with cpln port-forward RELEASE_NAME-ess 3004:3004 --gvc GVC_NAME.

Important Notes

Create the sync.yaml secret before installing, and force a redeployment after every change to it.
Two ESS instances cannot manage the same secret; give each release its own target secret names.
ESS never deletes a secret when its entry or upstream source is removed. Removing an entry from sync.yaml, or deleting the source upstream, leaves the Control Plane secret in place; delete it yourself.
Changing a secret between opaque and dictionary makes ESS delete and recreate it, so it briefly does not exist.
Version 2.1.0 removed essConfig; follow Upgrading From 2.0.x before upgrading an older release.

Template Catalog

Templates

ESS (External Secret Syncer)

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image and Resources

Admin API Access

Sync Configuration Secret

Providers

Secrets

Path Formats

Sync Interval

Connecting

Operations

Updating the Sync Configuration

Upgrading From 2.0.x

Troubleshooting

Important Notes

External References

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Resources

​Admin API Access

​Sync Configuration Secret

​Providers

​Secrets

​Path Formats

​Sync Interval

​Connecting

​Operations

​Updating the Sync Configuration

​Upgrading From 2.0.x

​Troubleshooting

​Important Notes

​External References

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image and Resources

Admin API Access

Sync Configuration Secret

Providers

Secrets

Path Formats

Sync Interval

Connecting

Operations

Updating the Sync Configuration

Upgrading From 2.0.x

Troubleshooting

Important Notes

External References