Skip to content

Vault

The Vault is the cluster-wide, centralized storage for secrets and sensitive configuration data inside ASAB Maestro. It is exposed by ASAB Remote Control through a simple REST API. The Vault gives you a single place to store API tokens, passwords, and TLS certificates that services in the cluster can then consume safely.

Vault API

The Vault is exposed by the ASAB Remote Control service with default web port 8891 (see Network ports).

Method Path Description
GET /vault List all Vault parameter names.
PUT /vault/{parameter} Save or update a secret. The request body is the raw secret value.
DELETE /vault/{parameter} Delete a secret.

Notes on the API:

  • Parameter names are case insensitive and are always normalized to lowercase. LDAP_USER_PASSWORD and ldap_user_password refer to the same Vault entry.
  • DELETE of a non-existent parameter returns 404.

Using the Vault from the command line

You can manage the Vault with /opt/site/gov.sh curl from any node that runs ASAB Remote Control (port 8891 on localhost). These calls are internally authorized.

Run the commands directly on the node:

# List all Vault parameters
/opt/site/gov.sh curl localhost:8891/vault

# Save a plain-text secret
/opt/site/gov.sh curl -X PUT localhost:8891/vault/MY_API_TOKEN --data 'supersecret'

# Save a secret from a file (for example a certificate or key)
/opt/site/gov.sh curl -X PUT localhost:8891/vault/ldap_tls_cafile --data-binary '@/absolute/path/to/cafile.crt'

# Delete a secret
/opt/site/gov.sh curl -X DELETE localhost:8891/vault/MY_API_TOKEN

Use --data-binary '@file' when the value contains newlines, such as PEM certificates or private keys. Use --data 'value' for a single-line string.

Using the Vault in the model

Declaring secrets

A secret is declared in the secrets section of the model or of a descriptor. The declaration only states the name and, optionally, the type and length; the value is not written in the model.

/Site/model.yaml
secrets:
  API_TOKEN:
    type: token
    length: 32
  SHARED_SECRET: {}

If the secret does not exist in the Vault when the model is applied, ASAB Maestro generates a random token of the requested length and stores it in the Vault.

Consuming a secret

Once declared, the secret is available as a Jinja2 template parameter under its name. Use it anywhere the model or a descriptor supports templating, for example in a service configuration:

/Site/model.yaml
services:
  seacat-auth:
    ...
    asab:
      config:
        "seacatauth:credentials:ldap:external":
          ...
          password: "{{API_TOKEN}}"

Secrets declared in the model are available cluster-wide. Secrets declared in a descriptor are scoped to that service (see Descriptors).

Storing files from the Vault

To expose a Vault secret as a file inside a container, map the secret into a files entry.

The following example exposes the three LDAPS files from the Vault to the seacat-auth service:

/Site/model.yaml
services:
  seacat-auth:
    ...
    files:
      - "/conf/tls_cafile.crt": "{{LDAP_TLS_CAFILE}}"
      - "/conf/tls_certfile.crt": "{{LDAP_TLS_CERTFILE}}"
      - "/conf/tls_keyfile.pem": "{{LDAP_TLS_KEYFILE}}"

secrets:
  LDAP_TLS_CAFILE: {}
  LDAP_TLS_CERTFILE: {}
  LDAP_TLS_KEYFILE: {}

Before applying the model, upload the actual file contents to the Vault (see Using the Vault from the command line).

See also the full walk-through in Integrate an LDAP server.