Aerospike Secret Agent

Aerospike Database Enterprise Edition relies on sensitive configuration values like TLS certificates, encryption keys, passwords, and feature-key files to operate securely. Storing these values as plaintext files on disk creates security risks, especially in environments with strict compliance or governance requirements.

Aerospike Secret Agent solves this problem. Secret Agent is a standalone process that retrieves secrets from an external secret manager and provides them to Aerospike Database at startup. Instead of managing secret files directly on each database node, you configure Secret Agent to retrieve them from the centralized secret manager your organization already uses.

Note

Aerospike Community Edition does not support fetching secrets from external secret managers. Secret Agent requires Aerospike Database Enterprise Edition 6.4 or later.

How Secret Agent works

Secret Agent runs as a separate process, either as a systemd service or in a Docker container. It acts as a proxy between Aerospike Database and your external secret manager:

1. You start Secret Agent. It connects to the configured external secret manager using that provider’s native SDK.
2. You start Aerospike Database. When Aerospike reads its configuration file and finds a parameter value that begins with the secrets: prefix, it sends a request to Secret Agent for that value.
3. Secret Agent fetches the requested secret from the external secret manager and returns it to Aerospike Database.

With this architecture, Aerospike Database does not need direct access to your secret manager. Secret Agent handles authentication with the secret manager and translates requests into the format each provider requires. If your organization changes secret managers in the future, you reconfigure Secret Agent without modifying the Aerospike Database configuration.

For details on how to reference secrets in the Aerospike configuration file and the full secrets:resource:key syntax, see Integrating with secrets management services.

Supported secret managers

Secret Agent integrates with the following secret managers:

• AWS Secrets Manager
• GCP Secret Manager
• HashiCorp Vault KV Secrets Engine (V2)

You can configure one secret manager per Secret Agent instance. For setup details specific to each provider, see the linked pages.

Supported connection types

Secret Agent supports four listener types. Configure at least one:

• TCP: Binary protocol with optional TLS (v1.2 and v1.3). Use TCP when Secret Agent runs on a different host from Aerospike Database.
• Unix Domain Socket (UDS): Binary protocol with lower overhead when Secret Agent and the client run on the same host.
• HTTP and HTTPS: REST API for fetching secrets over HTTP or HTTPS. Use these when clients, such as orchestrators, sidecars, scripts, or other services, need to fetch secrets using standard HTTP semantics.

You can configure one or more listeners (TCP, UDS, HTTP, HTTPS) on the same Secret Agent instance. Aerospike Database connects only over TCP or UDS. REST clients use HTTP or HTTPS.

Note

Aerospike Database communicates with Secret Agent automatically over TCP or UDS. If you are developing a custom tool that fetches secrets through Secret Agent, use the REST API (HTTP/HTTPS) or implement Secret Agent’s JSON-based request and response protocol over TCP or UDS.

Configuration parameters that support secrets

The following Aerospike Database configuration parameters can retrieve their values from an external secret manager through Secret Agent:

• feature-key-file
• cert-file
• key-file
• key-file-password
• encryption-key-file
• encryption-old-key-file
• auth-password-file
• default-password-file
• query-user-password-file

Note

The ca-file parameter cannot be fetched from an external secret manager.

Secret Agent configuration file

The Secret Agent configuration file has three main sections:

• The service context defines how Secret Agent listens for requests. You can configure TCP, UDS, and HTTP or HTTPS listeners.
• The secret-manager context specifies the external secret manager to use and the authentication details for connecting to it. You define one or more resources as a map of key-value pairs, where the key is an alias that Aerospike uses to reference the resource, and the value is the path from which the secret is fetched.
• The log context specifies the level and output destination for Secret Agent logging.

See the configuration template for a sample Secret Agent configuration file with all available options.

Next steps

• Install Secret Agent on Linux or with Docker.
• Configure your secret manager: AWS, GCP, or HashiCorp Vault.
• Integrate secrets into your Aerospike configuration using the secrets:resource:key syntax.