Skip to main content

Aerospike Secret Agent

Aerospike Secret Agent is an independent process which fetches secrets from external secret managers such as AWS Secrets Manager, GCP Secrets Manager and Hashicorp Vault KV Secret Engine. Its purpose is to provide a unified interface to fetch secrets from different secret managers. Secret Agent acts as a proxy between the external secret managers and the processes which need to fetch secrets. Other processes can use Secret Agent to fetch secrets from different external secret managers with reusable code. Secret Agent uses native SDKs of the corresponding secret managers.

For more information about Secret Agent features and usage, see the main documentation page.

Installation (Linux only)

  1. Download

    Download the Secret Agent package.

  2. Create a systemd daemon

    Use one of the following commands, based on your preferred package manager:

    sudo dpkg -i aerospike-secret-agent_<VERSION_NUMBER>-1ubuntu20.04_amd64.deb


    sudo rpm -i aerospike-secret-agent_<VERSION_NUMBER>-1.el8.x86_64.rpm

    Replace <VERSION_NUMBER> with the current Secret Agent version number, and adjust the Linux architecture designation as needed.

  3. Edit the Secret Agent configuration file

    Edit your configuration file to match your system's configuration. The following is an example to fetch secrets from AWS secret manager. For GCP secret manager,
    refer to the GCP configuration guide. For Hashicorp Vault secret manager, refer to the Hashicorp Vault configuration guide.


    region: us-west-1
    TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j
    NodeSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:NodeSecret-tN6s2j

    level: info

    The service context defines how Secret Agent listens for requests. Secret Agent supports listening on TCP and UDS (Unix Domain Socket). You can specify the endpoint for TCP and the path for UDS. Refer to the TCP configuration guide and UDS configuration guide for more details.

    The secret-manager context specifies one or more external secrets managers. Within each specified secrets manager, use the additional options to provide authentication details. You can specify multiple resources for a secret manager as a map of key value pairs. The key is a resource name and the corresponding value is a path from which the secret will be fetched. Requests specify the resource name that should be used.

    The log context specifies the level and output of Secret Agent logging.

    This is template of Secret Agent's configuration file with all the available options.

  4. Start the Secret Agent process

    Start the Secret Agent process before starting Aerospike server.

    systemctl start aerospike-secret-agent

    Secret Agent runs as root by default when started as a systemd service. If you prefer to run Secret Agent as a non-root user, you can edit the systemd service file (/etc/systemd/system/aerospike-secret-agent.service). Update the User and Group options in the [Service] section as shown in the following example.

    Description=Aerospike Secret Agent

    ExecStart=/usr/local/bin/aerospike-secret-agent --config-file /etc/aerospike-secret-agent/config.yaml



  1. Pull the Secret Agent docker image. Aerospike provides Secret Agent Docker image on Docker Hub.

    docker pull aerospike/aerospike-secret-agent
  2. Start the Secret Agent container.

    Make sure that all provided configuration files like Secret Agent's configuration file, TLS certificates, credential file (in case of GCP secret manager) are accessible from the container. This can be achieved by mounting a local directory which contains these files as a volume.

    The following sample command generates a Secret Agent's configuration file and starts the Secret Agent in the container.

    docker run -d --name aerospike-secret-agent -v ~/secretagent:/secretagent aerospike/aerospike-secret-agent --config-file /secretagent/config.yaml

    For details of Secret Agent's configuration file, see Aerospike Secret Agent

    1. Verify that the Secret Agent is started and running successfully in the container.
    $ docker ps
    19a2f22d8a7d aerospike/aerospike-secret-agent "/app/aerospike-secr…" 2 seconds ago Up 1 second aerospike-secret-agent
  3. Configure the server configuration file to connect to the Secret Agent.

    The following sample Aerospike Server configuration shows the Secret Agent's configuration parameter.

    service {
    secrets-address-port aerospike-secret-agent 3005

    For details see Integrating with secrets management services.

    Note: Fetching secrets from external secret managers is a feature only in Aerospike Enterprise.

  1. Pull the aerospike/aerospike-server-enterprise server image.

    docker pull aerospike/aerospike-server-enterprise
  2. Start the Aerospike server container.

    docker run -d --name aerospike-server -v ~/myfiles/:/etc/aerospike/ -e "FEATURE_KEY_FILE=/etc/aerospike/features.conf" aerospike/aerospike-server-enterprise --config-file /etc/aerospike/aerospike.conf

    Make sure that all provided configuration files like Aerospike Server configuration file, TLS certificates, Feature Key file etc are accessible from aerospike-server container.

    Make sure that Aerospike Server is started and running successfully in container.

    $ docker ps
    0f3829cbb6c4 aerospike/aerospike-secret-agent "/app/aerospike-secr…" 8 minutes ago Up 8 minutes aerospike-secret-agent
    96063fd95597 aerospike/aerospike-server-enterprise "/usr/bin/as-tini-st…" 9 minutes ago Up 9 minutes aerospike-server

    For more details, see Deploying Aerospike clusters with Docker.


In case of any errors, use docker log to see the logs of the respective containers.

Communicating with Secret Agent

Application code which communicates with Secret Agent should transmit requests and receive responses which conform to the Secret Agent specification.