Manage secrets in ADCM

Adelya Zvyagintseva

ADCM supports various secret backends, which makes it possible to securely handle sensitive data and use external systems.

Below is a table of secrets that are created during the initial ADCM startup.

Primary secrets
Secret path Description

/adcm/ansible/ansible_vault

Secret used by Ansible to encrypt sensitive data

/adcm/django/secret_key

Secret key used by the Django application

/adcm/backend/status_service_token

Token used by the Backend Server to authenticate with the Status Server

/adcm/status_service/adcm_token

Token used by the Status Server to authenticate with ADCM

/adcm/status_checker/status_service_token

Token used by the component that sends heartbeat data about the component state on the host to authenticate with the Status Server

ADCM provides the following ways to store secrets:

  • in the filesystem (FilesystemBackend);

  • in Vault (VaultBackend).

The secret backend is selected via the SECRET_BACKEND environment variable.

By default, the filesystem is used. If necessary, you can configure Vault.

Filesystem secret backend

By default, ADCM stores secrets in the filesystem. Secrets are saved in the /adcm/data/vars/secrets_v2.json file, which is created automatically during ADCM installation. The filesystem secret backend requires no additional configuration and is applied unless another secret backend is specified.

Example of the secrets_v2.json file structure:

{
  "adcm": {
    "ansible": {
      "ansible_vault": "..."
    },
    "django": {
      "secret_key": "..."
    },
    "backend": {
      "status_service_token": "..."
    },
    "status_service": {
      "adcm_token": "..."
    },
    "status_checker": {
      "status_service_token": "..."
    }
  }
}

Vault

NOTE
During the initial installation, ADCM automatically generates the required secrets and stores them in the selected backend. If ADCM is upgraded with a switch from file-based storage to Vault, the secrets must be migrated manually in advance. For more details, see Migration of secrets to Vault.

ADCM supports integration with Vault, which can be either HashiCorp Vault or other compatible solutions (such as OpenBao).

To use Vault, the following prerequisites should be met:

  • A token with read/write permissions for secrets is created.

  • A mount point to be used by ADCM (VAULT_MOUNT_POINT) is created.

The token should be saved to a file on the ADCM host, as this file will later be referenced in the VAULT_TOKEN_FILE environment variable.

Integration of ADCM with Vault is configured using the corresponding environment variables. Detailed information about the environment variables used to configure the Vault connection is provided in the Installation article.

NOTE
To enable Vault, set the SECRET_BACKEND environment variable to VaultBackend. If the SECRET_BACKEND variable is not defined, the filesystem secret backend (FilesystemBackend) is used by default.

Example of running ADCM with Vault is provided below.

$ docker run -d --name adcm -p 8000:8000 -v /opt/adcm:/adcm/data -v /opt/adcm/conf/ssl:/etc/ssl/certs -v /opt/adcm/token:/adcm/token -e DB_HOST="<DB_HOST>" -e DB_PORT="<DB_PORT>" -e DB_USER="<DB_USER>" -e DB_NAME="<DB_NAME>" -e DB_PASS="<DB_PASSWORD>" -e SECRET_BACKEND="VaultBackend" -e VAULT_URL="<VAULT_URL>" -e VAULT_MOUNT_POINT="<VAULT_MOUNT_POINT>" -e VAULT_TOKEN_FILE="/adcm/data/token" hub.arenadata.io/adcm/adcm:<version>

where <version> is a desired ADCM image version in one of the following formats:

  • <major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.

  • <major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

You can use the VAULT_CA_FILE, VAULT_CLIENT_CERT_FILE, and VAULT_CLIENT_KEY_FILE environment variables to establish a secure connection to Vault.

Prepare the SSL certificate files and place them in an accessible directory (for example, /etc/ssl/certs). Then specify the paths to them using environment variables:

-e VAULT_CA_FILE="/adcm/data/conf/ssl/ca.crt" -e VAULT_CLIENT_CERT_FILE="/adcm/data/conf/ssl/client.crt" -e VAULT_CLIENT_KEY_FILE="/adcm/data/conf/ssl/client.key"
IMPORTANT

  • latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.

  • Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

Migration of secrets to Vault

When switching from the filesystem (FilesystemBackend) to Vault (VaultBackend), you should migrate existing secrets to Vault. To do this, use the load command of the manage_secrets.py script, which transfers secrets from the secrets_v2.json file to Vault.

IMPORTANT
Reverse migration of secrets from Vault to the filesystem is not supported.

The load command reads secrets from a file (the default is /adcm/data/vars/secrets_v2.json) and uploads them to the configured Vault instance.

The command also supports the following flags:

  • --force — allows overwriting existing secrets in Vault.

  • --file <file_path> — defines the path to the secrets file.

To migrate secrets from local storage to Vault, perform the following steps:

  1. Stop and remove the ADCM container:

    $ sudo docker rm -f adcm
    IMPORTANT
    Do not delete the /opt/adcm/var directory, as it contains the secrets file.

  2. Start the ADCM container in MIGRATION_MODE, specifying the Vault connection settings without specifying a value for the SECRET_BACKEND variable:

    $ docker run -d -it --name adcm -p 8000:8000 -v /opt/adcm:/adcm/data -v /opt/adcm/conf/ssl:/etc/ssl/certs -v /opt/adcm/token:/adcm/token -e DB_HOST="<DB_HOST>" -e DB_PORT="<DB_PORT>" -e DB_USER="<DB_USER>" -e DB_NAME="<DB_NAME>" -e DB_PASS="<DB_PASSWORD>" -e VAULT_URL="<VAULT_URL>" -e VAULT_MOUNT_POINT="<VAULT_MOUNT_POINT>" -e VAULT_TOKEN_FILE="/adcm/token" -e MIGRATION_MODE=1 hub.arenadata.io/adcm/adcm:<version>

    where <version> is a desired ADCM image version in one of the following formats:

    • <major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.

    • <major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

  3. Upload the secrets to Vault:

    $ docker exec -it adcm python3 /adcm/python/manage_secrets.py load

    Expected command output:

    Secrets were loaded

  4. Stop and remove the ADCM container:

    $ sudo docker rm -f adcm

  5. Start ADCM in normal mode using the SECRET_BACKEND="VaultBackend" variable:

    $ docker run -d --name adcm -p 8000:8000 -v /opt/adcm:/adcm/data -v /opt/adcm/conf/ssl:/etc/ssl/certs -v /opt/adcm/token:/adcm/token -e DB_HOST="<DB_HOST>" -e DB_PORT="<DB_PORT>" -e DB_USER="<DB_USER>" -e DB_NAME="<DB_NAME>" -e DB_PASS="<DB_PASSWORD>" -e SECRET_BACKEND="VaultBackend" -e VAULT_URL="<VAULT_URL>" -e VAULT_MOUNT_POINT="<VAULT_MOUNT_POINT>" -e VAULT_TOKEN_FILE="/adcm/token" -e VAULT_CA_FILE="<CA_CERT_PATH>" -e VAULT_CLIENT_CERT_FILE="<CLIENT_CERT_PATH>" -e VAULT_CLIENT_KEY_FILE="<CLIENT_KEY_PATH>" hub.arenadata.io/adcm/adcm:<version>

  6. After starting ADCM in normal mode, ensure that:

    • The ADCM web interface is accessible and functioning correctly.

    • Secret entries was successfully created in the Vault interface at the path specified in the VAULT_MOUNT_POINT variable.

Found a mistake? Seleсt text and press Ctrl+Enter to report it