Aerospike Secret Agent

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

For more information about Secret Agent features and usage, see Integrating with secrets management services.

Installation (Linux only)

Download

Download the Secret Agent package.
Create a systemd daemon

Use one of the following commands, based on your preferred package manager:
- dpkg
- rpm
Terminal window
sudo dpkg -i aerospike-secret-agent_<VERSION_NUMBER>-1ubuntu20.04_amd64.deb
Terminal window
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 accordingly.
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 Secrets Manager. For GCP Secret Manager,
refer to the GCP configuration guide. For Hashicorp Vault Secret Manager, 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
```
For GCP Secret Manager, refer to the GCP configuration guide. For Hashicorp Vault Secret Manager, see the Hashicorp Vault configuration guide.

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.

See Configuration Template for a sample Secret Agent configuration file with all available options.
Start the Secret Agent process before starting the Aerospike Database.
Terminal window
```
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.
```
[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
```

Docker

Pull the Secret Agent Docker image. Aerospike provides a Secret Agent Docker image on Docker Hub.
Terminal window
```
docker pull aerospike/aerospike-secret-agent
```
Start the Secret Agent container.

Mount a local directory that contains the Secret Agent’s configuration file, TLS certificates, and any secret manager credential files as a volume to verify that all files are accessible from the container.

The following sample command generates a Secret Agent configuration file and starts the Secret Agent in the container.
Terminal window
```
docker run -d --name aerospike-secret-agent -v ~/secretagent:/secretagent aerospike/aerospike-secret-agent --config-file /secretagent/config.yaml
```

Verify that the Secret Agent is started and running successfully in the container.

$ docker ps
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

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

The following sample Aerospike Database configuration shows the Secret Agent configuration parameter under secrets-address-port.
```
service {
...
secrets-address-port aerospike-secret-agent 3005
...
}
```
For details see Integrating with secrets management services.

Aerospike Community Edition does not support fetching secrets from external secret managers.
Pull the aerospike/aerospike-server-enterprise image.
Terminal window
```
docker pull aerospike/aerospike-server-enterprise
```

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

Verify that all provided configuration files like the Aerospike configuration file, TLS certificates, and feature-key file are accessible from the Aerospike Database container, and verify that Aerospike Database is running in the container.

$ docker ps
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, see Install on macOS and Windows with Docker.

Troubleshooting

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

Communicating with Secret Agent

Application code that communicates with Secret Agent must transmit requests and receive responses that conform to the Secret Agent specifications shown on this page.