Aerospike Secret Agent

Aerospike Secret Agent is an independent process which fetches secrets from external secret managers such as AWS Secrets Manager. 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

   OR

   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:

   service:
     tcp:
       endpoint: 0.0.0.0:3005
   
   secret-manager:
     aws:
       region: us-west-1
       arn:
         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

   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 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 user-defined name (alias) for the corresponding resource and should be unique. The process which fetches the secret uses this alias to fetch the secret from the corresponding resource.

   If you use AWS Secrets Manager, the value is the Amazon Resource Name (ARN) of the secret. Refer to the AWS configuration guide for more details.

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

   The following configuration options are available :

   service: # at least one service is required
     tcp:
       endpoint: 0.0.0.0:3005 # required if tcp is specified
       tls: # optional
         cert-file : <path-to-cert-file>
         key-file : <path-to-key-file>
     uds:
       socket-path : <path-to-socket> # required if uds is specified
   
   secret-manager: # exactly one secret manager is required
     aws:
       region: <region> # required
       arn: # required
         <resource-name-1>: <arn-1>
         <resource-name-2>: <arn-2>
         <resource-name-3>: <arn-3>
       access-key-id: <access-key-id> # optional
       secret-access-key: <secret-access-key> # optional
       assume-role: <role-arn> # optional
    
    log: # optional
       file: <path-to-log-file> # optional (default is stdout)
       level: <level> # optional : supported values are "error", "warn", "info", "debug", "trace" (default is "info")

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.

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

Communicating with Secret Agent

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