Install Secret Agent

This page describes how to install Aerospike Secret Agent on Linux or with a Docker container. For an overview of what Secret Agent does and how it fits into your Aerospike deployment, see the Secret Agent overview.

Deployment recommendations

• Start Secret Agent before Aerospike Database. Aerospike requests secrets during startup, so Secret Agent must be running and ready to respond.
• Run one Secret Agent process per Aerospike node to avoid creating a single point of failure. While multiple Aerospike nodes can share a single Secret Agent process, this is not recommended for production deployments.
• Secret Agent can run on the same host as Aerospike Database or on a separate host. When both run on the same host, you can use UDS for lower-overhead communication.

Install on Linux

Package locations

When you install the Secret Agent package using a package manager, the executable is placed in /usr/local/bin/. The default configuration file is at /etc/aerospike-secret-agent/config.yaml, and the systemd service file is at /etc/systemd/system/aerospike-secret-agent.service.

Relocate RPM packages

The following command relocates etc, var, and usr directories to /foosa:

rpm --relocate /=/foosa/ --badreloc -Uvh aerospike-secret-agent-VERSION_NUMBER-1.el9.x86_64.rpm

Installation steps

1. Download the Secret Agent package.

2. Install the package to create a systemd daemon.

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

   dpkg

   dpkg -i aerospike-secret-agent_VERSION_NUMBER-1ubuntu20.04_amd64.deb

   rpm

   rpm -i aerospike-secret-agent_VERSION_NUMBER-1.el8.x86_64.rpm

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

3. Edit the Secret Agent configuration file to match your environment.

   The following example fetches secrets from AWS Secrets Manager.

   • For GCP Secret Manager, see the GCP configuration guide.
   • For HashiCorp Vault, see the HashiCorp Vault configuration guide.

   service:
     tcp:
       endpoint: 0.0.0.0:3005
   
   secret-manager:
     aws:
       region: us-west-1
       resources:
         TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j
         NodeSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:NodeSecret-tN6s2j
   
   log:
     level: info

   See the configuration template for all available options.

4. Start Secret Agent before starting Aerospike Database.

   systemctl start aerospike-secret-agent

   Secret Agent runs as root by default when started as a systemd service. To run Secret Agent as a non-root user, edit the systemd service file (/etc/systemd/system/aerospike-secret-agent.service). Set the User and Group options in the [Service] section:

   [Unit]
   Description=Aerospike Secret Agent
   Wants=network.target
   After=network-online.target
   
   [Service]
   EnvironmentFile=-/etc/environment
   ExecStart=/usr/local/bin/aerospike-secret-agent --config-file /etc/aerospike-secret-agent/config.yaml
   User=aerospike
   Group=aerospike
   
   [Install]
   WantedBy=default.target

Install with Docker

Aerospike provides a Secret Agent Docker image on Docker Hub.

1. Pull the Secret Agent Docker image.

   docker pull aerospike/aerospike-secret-agent

2. Start the Secret Agent container.

   Mount a local directory containing the Secret Agent configuration file, TLS certificates, and any secret manager credential files as a volume to make them accessible from the container.

   The following command starts Secret Agent using a configuration file at ~/secretagent/config.yaml:

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

3. Verify that Secret Agent is running.

   docker ps

   Expected output:

   CONTAINER ID   IMAGE                              COMMAND                  CREATED         STATUS        PORTS     NAMES
   19a2f22d8a7d   aerospike/aerospike-secret-agent   "/app/aerospike-secr…"   2 seconds ago   Up 1 second             aerospike-secret-agent

4. Configure the Aerospike Database configuration file to connect to Secret Agent.

   Set the secrets-address-port parameter in the Aerospike configuration:

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

   For details, see Integrating with secrets management services.

5. Pull the Aerospike Database Enterprise Edition image.

   docker pull aerospike/aerospike-server-enterprise

6. Start the Aerospike Database 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

7. Verify that both containers are running.

   docker ps

   Expected output:

   CONTAINER ID   IMAGE                                   COMMAND                  CREATED         STATUS         PORTS           NAMES
   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 information about running Aerospike in Docker, see Install on macOS and Windows with Docker.

Troubleshooting

To diagnose errors, check the logs of the respective containers:

docker logs aerospike-secret-agent

docker logs aerospike-server