Skip to main content

Secrets Management

Add secrets to a vault​

This section describes how you can create, update and delete vaults and vault secrets.

A vault can contain multiple secret collections. Each secret collection contains multiple key/value maps.

The vault controls to which sites its constituent secret collections are distributed to.

Create a new vault​

Create a vault named operations and distribute the vault to all sites the tenant has access to.

supctl create strongbox vaults <<EOF
name: operations
distribute:
  to: all
EOF

Please see here for more distribution options.

Create a key value map in a vault​

Store username and password in a key/value map named credentials in the operations vault and give access to any image.

supctl create strongbox vaults operations secrets<<EOF
name: credentials
allow-image-access:
  - "*"
data:
  username: the-user
  password: the-password
EOF

Data that contains newlines or non-string characters, i.e. binary data can instead be stored as base64 encoded data in the base64-data parameter.

supctl create strongbox vaults operations secrets<<EOF
name: credentials-b64
allow-image-access:
  - "*"
base64-data:
  username: dGhlLXVzZXItMg==
  password: dGhlIHBhc3N3b3Jk
EOF

And there may even be a mix of plain-text and base64 data.

supctl create strongbox vaults operations secrets<<EOF
name: credentials-mixed
allow-image-access:
  - "*"
data:
  username: the-user
  password: the-password
base64-data:
  username: dGhlLXVzZXItMg==
  password: dGhlIHBhc3N3b3Jk
EOF

If a base64 encoded value is mounted as a file from an app then the decoded value will appear as content in the file. If the same key appears in both data and base64-data then the base64-data will prevail, in the case above the base64 version of username and password will be used.

Update secrets in a vault​

Update the password in the credentials key/value map.

supctl merge strongbox vaults operations secrets credentials<<EOF
data:
  password: the-new-password
EOF

Delete a secret from a vault​

supctl delete strongbox vaults operations secrets credentials

This will delete the entire secret. It is also possible to delete a specific secret version using a query parameter, ie

supctl -q version=2 delete strongbox vaults operations secrets credentials

This will delete version 2 of the secret. This operation can be undone suing the undelete action.

Undelete a secret version from a vault​

supctl do strongbox vaults operations secrets credentials undelete

This will restore the latest version of the secret to the vault. A specific version can be un-deleted using a version argument, ie

supctl -q version=2 do strongbox vaults operations secrets credentials undelete

Remove a secret from a vault​

supctl do strongbox vaults operations secrets credentials destroy

A secret can be completely removed using the destroy action. If all versions of a secret has been destroyed then the entire secret is removed.

Delete a vault​

supctl delete strongbox vaults operations

Control distribution of secrets​

Distribute a vault to all sites​

To distribute a vault to to all sites a tenant has access to

supctl create strongbox vaults <<EOF
name: global-vault
distribute:
  to: all
EOF

Distribute a vault to select sites​

supctl create strongbox vaults <<EOF
name: credentials-stockholm-sergel
distribute:
  sites:
    - stockholm-sergel
    - helsingborg-bergakungen
EOF

Distribute a vault to the same sites as an application is deployed​

supctl create config strongbox vault <<EOF
name: popcorn-credentials
distribute:
  deployments:
    - popcorn-deployment
EOF

popcorn-deployemnt is the name of the application deployment (not the name of the application).

Application configuration​

tip

Use the ${SYS_SITE} variable, this variable will expand to the site name when deployed.

name: site-secrets
services:
  - name: site-service
    containers:
      - name: alpine
        image: docker/alpine
        cmd: ["sleep", "infinity"]
        mounts:
          - volume-name: credentials
            mount-path: /credentials
    volumes:
      - name: credentials
        vault-secret-ref:
          vault: credentials-${SYS_SITE}
          secret: credentials

    mode: replicated
    replicas: 1

This will expand credentials-${SYS_SITE} to e.g. credentials-stockholm-sergel in the Stockholm site.

Don't distribute secrets​

Some secrets does not need to be distributed to any sites, e.g. registry credentials, to store secrets in the Control Tower only

supctl create strongbox vaults <<EOF
name: my-vault
distribute:
  to: none
EOF

Control which image can access a key/value map​

To allow an image to auto-mount a vault secret as a virtual file, or as en environment variable, it must be listed in the allow-image-access parameter. It is possible to use * to allow all images to mount the secret, but this is strongly discouraged for production use. Each image id should instead be explicitly listed.

The image-id can be determined using, for example, docker

docker images alpine:latest --no-trunc -q
sha256:021b3423115ff662225e83d7e2606475217de7b55fde83ce3447a54019a77aa2

and supctl

supctl show registry repositories alpine digests
- digest: sha256:be9bdc0ef8e96dbc428dc189b31e2e3b05523d96d12ed627c37aa2936653258c
  tags:
    - latest
  type: image-manifest
  platform: linux/amd64
  image-id: sha256:021b3423115ff662225e83d7e2606475217de7b55fde83ce3447a54019a77aa2
  compressed-size: 2.68 MB

or

supctl show registry repositories avassa-public/movie-theaters-demo/curtain-controller digests
- digest: sha256:cd9f8edadf866a2013a28f26e88899a12563c2ebe6942dc3464a0a2f41294b78
  tags:
    - v1.0
  type: image-manifest
  platform: linux/amd64
  image-id: sha256:32d739ebbe6afd82fc1d578cbc8f4900ac97fc2c3624d47d59594a67e5e72202
  compressed-size: 10.46 MB

Allow auto-mounting of secret from alpine image.

name: credentials
allow-image-access:
  - sha256:021b3423115ff662225e83d7e2606475217de7b55fde83ce3447a54019a77aa2
data:
  username: the-user
  password: the-password

Allow another tenant access​

It is also possible to share a secret with another tenant. This is useful when, for example, auto generating mTLS certifictates for a share MQTT service. An image started by another tenant may access a secret, provided that the allow-image-access setting allows it and allow-tenant-access is configured to permit the tenant to access the secret. See [Tenant Secret Sharing]https://docs.avassa.io/how-to/tenant-secret-sharing

Add secrets to a versioned vault​

By default only a single version of a secret is stored in a vault. This can be changed by setting the max-versions parameter when creating a vault, or changed for an existing vault using the merge (PATCH) operation.

Allowing multiple version makes it possible to rollback a change for example, using the delete operation.

Create a new versioned vault​

Create a versioned vault named popcorn-systems and distribute the vault to all sites the tenant has access to. The vault will hold at most 10 old version of each map it stores. Check-and-set (CAS) is configured to allow cooperative locking, ie, to prevent unintentional overwrite.

supctl create strongbox vaults <<EOF
name: popcorn-systems
max-versions: 10
cas-required: true
distribute:
  to: all
EOF

Create a key value map in a versioned vault​

Store username and password in a key/value map named db-user in the popcorn-systems versioned vault. Since CAS is required version is set to 0 to indicate that the value should be created.

supctl -q version=0 create strongbox vaults popcorn-systems secrets<<EOF
name: db-user
data:
  username: the-db-user
  password: the-db-password
EOF

Add a new version of the key value map​

To update an existing value the current version must be supplied since the cas-required options was set for the vault.

supctl -q version=1 merge strongbox vaults popcorn-systems secrets db-user<<EOF
data:
  password: the-new-db-password
EOF

Access the current version​

Read the current version

supctl show strongbox vaults popcorn-systems secrets db-user
name: db-user
data:
  password: the-new-db-password
  username: the-db-user
dict:
  password: the-new-db-password
  username: the-db-user
creation-time: 2021-08-23T12:35:05.429330Z
version: 2
metadata:
  current-version: 2
  modified-time: 2021-08-23T12:35:05.429331Z
  creation-time: 2021-08-23T12:33:26.480139Z
  oldest-version: 1

Access an old version​

Show the first version of the db-user map.

supctl -q version=1 show strongbox vaults popcorn-systems secrets db-user
name: db-user
data:
  password: the-db-password
  username: the-db-user
dict:
  password: the-db-password
  username: the-db-user
creation-time: 2021-08-23T12:33:26.480139Z
version: 1
metadata:
  current-version: 2
  modified-time: 2021-08-23T12:35:05.429331Z
  creation-time: 2021-08-23T12:33:26.480139Z
  oldest-version: 1

Delete an old version​

It is possible to delete certain versions of a key value map, as well as the entire map. Deleting a version makes it temporarily unavailable.

Delete version 1 of the map.

supctl -q version=1 delete strongbox vaults popcorn-systems secrets db-user

or

supctl do strongbox vaults popcorn-systems secrets db-user delete --versions 1

Delete the latest version (version 3) of the key value map.

supctl do strongbox vaults popcorn-systems secrets db-user delete

Un-delete a key value map from a versioned vault​

To un-delete the previously deleted versions 1 and 2 of the db-user map.

supctl do strongbox vaults popcorn-systems secrets db-user undelete --versions 1 2

Destroy a key value map in a versioned vault​

Permanently remove a version of the key value map.

supctl do strongbox vaults popcorn-systems secrets db-user destroy --versions 1

Permanently remove the entire key value map.

supctl do strongbox vaults popcorn-systems secrets db-user destroy

Delete a versioned vault​

Remove the entire versioned vault.

supctl delete strongbox vaults popcorn-systems