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.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-1_amd64.deb

   rpm

   rpm -i aerospike-secret-agent-VERSION_NUMBER-1.x86_64.rpm

   Replace VERSION_NUMBER with the Secret Agent version number (for example, 1.3.0), and adjust the architecture as needed (amd64 or arm64). As of Secret Agent 1.3.0, package names are platform-independent. The filenames contain version and architecture only. Previous releases followed a different filename syntax: aerospike-secret-agent-VERSION_NUMBER-1.DISTRIBUTION.ARCHITECTURE.rpm/deb. See the Secret Agent download page for details and download links.

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.

Command-line options

The aerospike-secret-agent binary accepts three flags. Listeners, secret manager settings, logging, and metrics are configured in the YAML file passed with --config-file. See the configuration template for those options.

Flag	Required	Description
--config-file	Yes	Path to the Secret Agent YAML configuration file.
--help	No	Print usage and exit.
--version	No	Print the build version and exit. Requires --config-file on the command line.

To start Secret Agent manually after a package install, run:

aerospike-secret-agent --config-file /etc/aerospike-secret-agent/config.yaml

Troubleshooting

Check Secret Agent logs first.

Linux (systemd)

journalctl -u aerospike-secret-agent -e

Docker

docker logs aerospike-secret-agent

If Aerospike Database fails to start or reports secret fetch errors, check Aerospike logs as well.

Linux (systemd)

journalctl -u aerospike -e

Docker

docker logs aerospike-server

See Log management for more information on log sinks, severity levels, and logging contexts. On systemd hosts, see Server logs with systemd for additional journalctl options.

To confirm Secret Agent is running before you start Aerospike Database:

Linux (systemd)

systemctl is-active aerospike-secret-agent

Docker

docker ps --filter name=aerospike-secret-agent

Symptom	What to check
Secret Agent exits immediately on start	Startup config validation failed. Logs show a fatal error for bad YAML, a missing listener, multiple secret managers, or invalid TLS settings. Compare your file with the configuration template.
Missing config file	--config-file was not passed or points to the wrong path. In Docker, confirm the path in the flag matches the volume mount inside the container.
Aerospike fails to fetch secrets	Start Secret Agent before Aerospike Database. Verify secrets-address-port matches the TCP endpoint in the Secret Agent configuration (hostname and port, or the Docker container name).
Secret Agent runs but secrets still fail	Resource alias mismatch. The alias in secrets:alias:key in the Aerospike configuration must match a key under secret-manager.*.resources in the Secret Agent configuration. See Integrating with secrets management services.
Errors fetching from the secret manager	Credentials, region, Vault authentication, or proxy settings. See AWS, GCP, HashiCorp Vault, or Configure a proxy.