Configure environment variables and secrets#

This guide shows you how to set environment variables on Plone backend and frontend pods and how to source sensitive values from Kubernetes Secrets and ConfigMaps. Use it to inject a RelStorage DSN, an admin password, or any runtime configuration without baking values into the image.

Prerequisites#

A working Plone deployment using cdk8s-plone.
Familiarity with the cdk8s-plus Env API and the EnvValue helpers it provides.
kubectl access to the target namespace for creating Secrets and ConfigMaps.

Set a plain environment variable on the backend#

Pass an environment object to backend. Build each value with Env.value for a literal string.

import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
import { Env } from 'cdk8s-plus-30';

new Plone(chart, 'plone', {
  variant: PloneVariant.VOLTO,
  backend: {
    image: 'plone/plone-backend:6.1.3',
    environment: {
      variables: {
        PLONE_TIMEZONE: Env.value('Europe/Vienna'),
        ZSERVER_THREADS: Env.value('4'),
      },
    },
  },
});

The environment option is typed as the cdk8s-plus Env construct. Its variables map takes an EnvValue for every entry, so always wrap raw strings in Env.value.

Reference a value from a Secret#

Store sensitive values such as a RelStorage DSN or an admin password in a Kubernetes Secret, then reference them with Env.fromSecret.

First create the Secret in the cluster.

kubectl create secret generic plone-backend-secrets \
  --namespace <namespace> \
  --from-literal=relstorage-dsn='dbname=plone host=db user=plone password=s3cret' \
  --from-literal=admin-password='change-me'

Reference the existing Secret by name, then read individual keys from it.

import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
import { Env, Secret } from 'cdk8s-plus-30';

const backendSecret = Secret.fromSecretName(
  chart,
  'backend-secret',
  'plone-backend-secrets',
);

new Plone(chart, 'plone', {
  variant: PloneVariant.VOLTO,
  backend: {
    image: 'plone/plone-backend:6.1.3',
    environment: {
      variables: {
        RELSTORAGE_DSN: Env.fromSecret(backendSecret, 'relstorage-dsn'),
        ADMIN_PASSWORD: Env.fromSecret(backendSecret, 'admin-password'),
      },
    },
  },
});

Env.fromSecret renders a secretKeyRef in the pod template, so the value never appears in plain text in the synthesized manifest.

Reference a value from a ConfigMap#

For non-sensitive configuration that you manage separately from the chart, read keys from a ConfigMap with Env.fromConfigMap.

import { Env, ConfigMap } from 'cdk8s-plus-30';

const settings = ConfigMap.fromConfigMapName(
  chart,
  'settings',
  'plone-settings',
);

// inside backend.environment.variables:
//   LOG_LEVEL: Env.fromConfigMap(settings, 'log-level'),

Set variables on the frontend#

The frontend accepts the same environment option as the backend.

import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
import { Env } from 'cdk8s-plus-30';

new Plone(chart, 'plone', {
  variant: PloneVariant.VOLTO,
  frontend: {
    image: 'plone/plone-frontend:16.0.0',
    environment: {
      variables: {
        RAZZLE_API_PATH: Env.value('https://plone.example.com/++api++'),
      },
    },
  },
});

The Volto frontend automatically injects RAZZLE_INTERNAL_API_PATH when you do not set it. Override it through environment only when your service topology requires a non-default internal address.

frontend: {
  image: 'plone/plone-frontend:16.0.0',
  environment: {
    variables: {
      RAZZLE_INTERNAL_API_PATH: Env.value('http://plone-backend:8080/Plone'),
    },
  },
}

Pull from a private registry#

Image registry credentials are not environment variables. List the names of existing pull secrets in the top-level imagePullSecrets option.

new Plone(chart, 'plone', {
  variant: PloneVariant.VOLTO,
  imagePullSecrets: ['my-registry-credentials'],
  backend: {
    image: 'registry.example.com/plone-backend:6.1.3',
  },
  frontend: {
    image: 'registry.example.com/plone-frontend:16.0.0',
  },
});

Create the pull secret beforehand with kubectl create secret docker-registry <name>.

Verify#

Synthesize the manifests and inspect the rendered Deployment for the expected entries.

cdk8s synth

# Confirm literal values and secret references appear on the backend container
grep -A 3 'RELSTORAGE_DSN' dist/*.yaml
grep -B 1 -A 4 'secretKeyRef' dist/*.yaml

A secretKeyRef block in the output confirms the value resolves at runtime from the Secret rather than being stored in the manifest. After applying, check that the variables reach the container.

kubectl apply -f dist/
kubectl exec -n <namespace> deployment/<plone-backend-deployment> -- env | grep RELSTORAGE_DSN