Skip to main content

Variables and secrets

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

A service receives its settings through environment variables: a value written in the manifest, or a key of a Secret for anything confidential. Secrets are never in the manifest; you create them separately and the App references them by name.

Prerequisites​

Steps​

1. Declare the variables​

api.yml
apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: api
spec:
  imagePullSecrets: [gitlab-registry]            # to pull the private image
  services:
    api:
      image: registry.gitlab.com/acme/api:1.2.0
      ports: ["8080"]
      env:
        LOG_LEVEL: info                          # string
        WORKERS: 4                               # number → "4"
        DEBUG: false                             # boolean → "false"
        DB_PASSWORD: { secret: db, key: password }   # password key of the Secret db
      envFrom: [api-env]                         # all keys of the Secret api-env

Command-line equivalent, for an App with one service:

sng app create api --image registry.gitlab.com/acme/api:1.2.0 --port 8080 \
  --env LOG_LEVEL=info --env WORKERS=4 --env DEBUG=false \
  --env-secret DB_PASSWORD=db:password --env-from api-env \
  --image-pull-secret gitlab-registry

2. Create the referenced Secrets​

Create gitlab-registry (docker-registry type), db (with a password key) and api-env on your tenant: Injection into an App. The order does not matter, the App waits.

3. Apply and check the state​

sng apply api.yml
sng app describe api

As long as a Secret is missing, the state says so:

App      : api
Statut   : en cours
Message  : api : Secrets absents (…) : api-env
SERVICE  KIND        IMAGE                                PHASE        URL  DETAIL
api      deployment  registry.gitlab.com/acme/api:1.2.0   Progressing  -    SecretNotFound Secrets absents (…) : api-env

As soon as the Secret exists, the service starts with no further action, within a few minutes.

Verification​

sng app describe api displays Statut : prête. sng app logs api shows the application started with its settings.

Modify a variable afterwards​

sng app patch api --env LOG_LEVEL=debug            # adds or replaces
sng app patch api --env-secret SMTP_PASSWORD=smtp:password
sng app patch api --unset-env DEBUG                # removes

Each patch updates the manifest and triggers a rolling update of the service. For an App with several services, add --service <name>.

The forms of env​

FormExampleWhat the container receives
stringLOG_LEVEL: infoLOG_LEVEL=info
numberWORKERS: 4WORKERS=4
booleanDEBUG: falseDEBUG=false
referenceDB_PASSWORD: { secret: db, key: password }the value of the password key of the Secret db, read when the container starts
null or emptyHOME_DIR:rejected: write HOME_DIR: ""

Rules: 100 variables at most per service; name of the form ^[A-Za-z_][A-Za-z0-9_.-]*$; secret and key are both required in a reference. No interpolation: ${VAR} is passed as is.

envFrom: an entire Secret​

envFrom: [api-env] turns each key of the listed Secrets (10 at most) into a variable. It is the natural translation of a compose env_file. In case of a duplicate between env and envFrom, the value from env wins (standard container behavior).

imagePullSecrets: private images​

  • spec.imagePullSecrets applies to all services.
  • services.<name>.imagePullSecrets replaces this list for one service; [] means "none" (useful for a public image next to private images).
  • A missing registry Secret blocks the service (Waiting, ImagePullSecretNotFound): nothing is started as long as it is missing, and the platform rechecks every 30 seconds. Create it: the service starts within the following half-minute.

Going further​

  • The platform only checks the existence of the referenced Secrets; it never reads their content.
  • A secret referenced by env or envFrom that does not exist yet is created for you, pending, without a value: it appears in sng secret list. Set its value with sng secret set and the service starts (Inject a secret into an App).
  • A compose secret mounted as a file (secrets:) has no equivalent: use a {secret, key} variable.
  • Secret names are DNS subdomains (lowercase, digits, -, .).

See also​