Vault Reference#

Configuration details for Vault integrations with Kubernetes and GitLab.

Kubernetes integration#

VaultStaticSecret resource#

The VaultStaticSecret resource syncs a Vault secret into a Kubernetes Secret.

VaultStaticSecret with all common fields#
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: secret
spec:
  type: <engine type: kv-v1 or kv-v2, use kv-v2>
  mount: <kv engine name>
  path: <path to secret in Vault>
  version: <version of secret, omit for latest>
  refreshAfter: <sync frequency, e.g. 60s>
  rolloutRestartTargets: <list of workloads to restart on change>
  syncConfig:
    instantUpdates: <enable event-driven instant updates>
  destination:
    name: <Kubernetes secret name>
    create: <true to create new secret>
    overwrite: <true to overwrite existing secret>
    labels: <labels for created secret>
    annotations: <annotations for created secret>
    type: <K8s secret type: Opaque, dockercfg, tls, etc.>
    transformation:
      excludeRaw: <exclude _raw field containing all data>
      excludes: <list of fields to exclude>
      includes: <list of fields to include>
      templates:
        <key name>:
          text: <Go template expression>

Key fields:

Field

Description

mount

KV engine name (e.g., dev, shared)

path

Path within the engine (e.g., my-team/my-app)

refreshAfter

How often to check for updates (e.g., 60s, 5m)

rolloutRestartTargets

Workloads to restart when secret changes

destination.name

Name of the Kubernetes Secret to create

transformation.includes

Whitelist of keys to sync (omit for all)

DeviceServer resource#

For TANGO device servers using ska-tango-util, inject Vault secrets directly:

instances: <instances to deploy>
entrypoints: <TANGO class entrypoints>
server:
  instances:
    - name: "<instance name>"
      classes:
        - name: "SomeClass"
          devices:
            - name: "test/someclass/1"
              properties:
                - name: "deviceProperty"
                  values:
                    - "test"
secrets:
  - secretPath: <path to secret>
    secretMount: <kv engine>
    env:
      - secretKey: <key in Vault secret>
        envName: <environment variable name>
        default: <fallback value if secrets disabled>
        transform: <Go template expression>

Note

DeviceServer secrets do not support file mounting or version specification.

Debugging Kubernetes integration#

Inspect VaultStaticSecret status:

kubectl describe vaultstaticsecret/test-secret

Example error output:

Events:
Type     Reason            Age   From               Message
----     ------            ----  ----               -------
Warning  VaultClientError  3s    VaultStaticSecret  Failed to read Vault secret: Error making API request.

URL: GET <vault secret url>
Code: 403. Errors:

* 1 error occurred:
   * permission denied

Common HTTP status codes:

Code

Meaning

400

Invalid request — missing or invalid data

403

Forbidden — incorrect authentication or no access to secret

404

Invalid path — path doesn’t exist or no permission to view

View status in Headlamp by navigating to the VaultStaticSecret page for the CI/CD cluster.

Headlamp VaultStaticSecret page

GitLab integration#

Integrate GitLab CI/CD pipelines with Vault to retrieve secrets or configuration files.

Job configuration#

<job>:
  stage: <stage>
  variables:
    VAULT_SERVER_URL: <vault url, defaults to https://vault.skao.int>
    VAULT_AUTH_PATH: <login method, defaults to jwt>
    VAULT_AUTH_ROLE: <vault role, defaults to developer>
    SOME_VAR: something
  id_tokens:
    VAULT_ID_TOKEN:
      aud: <audience, use https://gitlab.com>
  secrets:
    <ENV_VAR_NAME>:
      vault: <path/to/secret>/${SOME_VAR}@<kv engine>
      file: <true for file, false for env var>

When file: true, the environment variable contains the path to the secret file. When file: false, it contains the value.

Debugging GitLab integration#

Configuration errors cause the job to fail before starting. Common errors:

Authentication error:

Resolving secret "CONTEXT_VALUES"...
Using "vault" secret resolver...
ERROR: Job failed (system failure): resolving secrets: initializing Vault service:
preparing authenticated client: authenticating Vault client: writing to Vault:
api error: status code 400: error validating token: invalid audience (aud) claim

Permission denied:

Resolving secret "CONTEXT_VALUES"...
Using "vault" secret resolver...
ERROR: Job failed (system failure): resolving secrets: reading secret:
reading from Vault: api error: status code 403: 1 error occurred:
  * permission denied

Secret not found:

Resolving secret "CONTEXT_VALUES"...
Using "vault" secret resolver...
ERROR: Job failed (system failure): resolving secrets: secret not found: CONTEXT_VALUES

If the job starts, GitLab successfully retrieved all secrets.

External documentation#

Vault#

GitLab#

Kubernetes#