--- title: "Integrating with secrets management services" description: "Integrate Aerospike Database with AWS, GCP, and Hashicorp Vault using the Secret Agent proxy for secure configuration." --- # Integrating with secrets management services > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt) > > All documentation pages available in markdown. ![Integrating Aerospike with a secrets management service](https://aerospike.com/docs/_astro/secrets-overview.CWhtJfct_Z2bxV3d.png) Figure 1: Integrating Aerospike with a secrets management service As of Database 6.4.0, Aerospike Database Enterprise Edition can fetch sensitive configurations from secrets management services, using an intermediate process called Secret Agent. The agent acts as a proxy between Aerospike server and one or more external secrets management services, such as AWS Secrets Manager. Secret Agent can be deployed on the same host where the Aerospike cluster node is running, or on a different host. To learn more, refer to the Secret Agent [reference page](https://aerospike.com/docs/database/tools/secret-agent). While multiple Aerospike servers can use a single Secret Agent process, we recommend avoiding a single point of failure by running a Secret Agent process locally with each Aerospike cluster node. Aerospike Secret Agent integrates with [AWS Secrets Manager](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/aws), [GCP Secrets Manager](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/gcp) and [Hashicorp Vault Secrets Manager](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/vault). Additional services will be added in the future, independently of server releases. ## Encoding Secrets The Aerospike server expects a fetched secret value in base64 encoded format. If secrets in the external secret management service are saved as plain text then set the Secret Agent’s configuration parameter `convert-to-base64` to `true` to return all the fetched secrets in base64 encoded format. Users may want to save secrets in base64-encoded format to avoid potential non-printable and control characters. ::: caution Embedding non-trailing whitespace in base64-encoded secrets is not supported. For instance, when using `base64` command-line utility, do `base64 -w0` to prevent the default line break every 76 characters. ::: ::: caution For AWS Secret Manager, multi-line secret values (like tls certificates) should be stored in base64 encoded format only. This is not necessary when using GCP Secret Manager. For GCP Secret Manager, secret values can be stored as plain text and use Secret Agent’s configuration parameter `convert-to-base64`. ::: ## Connecting to Aerospike Secret Agent Aerospike Secret Agent acts as a proxy layer between Aerospike server and one or more external secrets management services, fetching secrets on behalf of the server. Aerospike server can communicate with Secret Agent with the following connection methods: 1. [TCP connection (plain or TLS)](#tcp-connection) 2. [Unix Domain Socket (UDS)](#uds-connection) ::: note Both TCP and UDS cannot be configured at the same time in an Aerospike server configuration. ::: ### TCP connection For a plain TCP connection, set the Secret Agent’s IP address and port in the [`secrets-address-port`](https://aerospike.com/docs/database/reference/config#service__secrets-address-port) configuration parameter. ```plaintext service { ... secrets-address-port 127.0.0.1 3005 ... } ``` #### Configuring TLS To use TLS over a TCP connection: 1. In the `network` context, create a TLS sub-context with a [`ca-file`](https://aerospike.com/docs/database/reference/config#network__ca-file) or [`ca-path`](https://aerospike.com/docs/database/reference/config#network__ca-path) specified. If mutual authentication is needed between the Aerospike server and the Secret Agent then additionally add [`cert-file`](https://aerospike.com/docs/database/reference/config#network__cert-file) and [`key-file`](https://aerospike.com/docs/database/reference/config#network__key-file) configuration parameters along with `ca-file` or `ca-path` in the TLS sub-context. 2. Add a third parameter in [`secrets-address-port`](https://aerospike.com/docs/database/reference/config#service__secrets-address-port), which is used as the TLS name. The TLS name should be either the common name or one of the Subject Alternate Names (SAN) in the TLS certificate. 3. Configure [`secrets-tls-context`](https://aerospike.com/docs/database/reference/config#service__secrets-tls-context), and specify the TLS sub-context name. All the other configuration parameters (including `protocols` and `cipher-suite`) allowed in the [TLS sub-context](https://aerospike.com/docs/database/8.1.2/manage/network/tls#tls-configuration-parameters) are honored. Sample Aerospike configuration file for one way authentication (Aerospike server authenticates Secret Agent). ```plaintext service { ... secrets-address-port 127.0.0.1 3005 secretagent #'secretagent' is a TLS name. secrets-tls-context secrets-tls ... } network { ... tls secrets-tls { ca-file /path/to/ca-file.pem } ... } ``` Sample Aerospike configuration file for mutual authentication between Aerospike server and Secret Agent. ```plaintext service { ... secrets-address-port 127.0.0.1 3005 secretagent #'secretagent' is a TLS name. secrets-tls-context secrets-tls ... } network { ... tls secrets-tls { cert-file /path/to/cert-file.pem key-file /path/to/key-file.pem ca-file /path/to/ca-file.pem } ... } ``` ### UDS Connection Unix Domain Sockets (UDS) enable inter-process communication (IPC) between processes running on the same host with less overhead than network protocols, using file system paths instead of network addresses. UDS Considerations: - Aerospike server and Secret Agent should run on the same host, with the same user and group ownership for both processes. - The same UDS path should be provided in both Aerospike server and Secret Agent’s configuration file. - The socket file which used for communication between Aerospike server and Secret Agent is created with 660 file permissions (read/write access for owner and group) when Secret Agent starts. ```plaintext service { ... secrets-uds-path /path/to/uds.sock ... } ``` ## Supported configuration parameters The following configuration parameter values can be fetched from an external secret manager: - [`auth-password-file`](https://aerospike.com/docs/database/reference/config#xdr__auth-password-file) - [`cert-blacklist`](https://aerospike.com/docs/database/reference/config#network__cert-blacklist) - [`cert-file`](https://aerospike.com/docs/database/reference/config#network__cert-file) - [`default-password-file`](https://aerospike.com/docs/database/reference/config#security__default-password-file) - [`encryption-key-file`](https://aerospike.com/docs/database/reference/config#namespace__encryption-key-file) - [`encryption-old-key-file`](https://aerospike.com/docs/database/reference/config#namespace__encryption-old-key-file) - [`feature-key-file`](https://aerospike.com/docs/database/reference/config#service__feature-key-file) - [`key-file`](https://aerospike.com/docs/database/reference/config#network__key-file) - [`key-file-password`](https://aerospike.com/docs/database/reference/config#network__key-file-password) - [`query-user-password-file`](https://aerospike.com/docs/database/reference/config#security__query-user-password-file) ::: note The [`ca-file`](https://aerospike.com/docs/database/reference/config#network__ca-file) parameter cannot be fetched from the external secret manager. ::: To fetch secret values for the supported configuration parameters from the external secret manager like AWS, GCP and Hashicorp Vault, a user must specify that configuration value in `secrets:[resource:]key` format. 1. `secrets:`\- A required prefix. It indicates that the configuration parameter value will be fetched from the external secret manager. 2. `resource`\- Resource name in Secret Agent’s configuration file. **Required** as of Secret Agent 1.3.0. The agent always validates the resource name. The secret is fetched from the path corresponding to this resource. Refer to the Secret Agent [configuration documentation](https://aerospike.com/docs/database/tools/secret-agent) for more information. 3. `key` - Required field. It identifies the secret to be fetched. AWS and Hashicorp Vault allows multiple key-values in one secret. `key` field determines which key-value will be fetched. GCP allows single value in one secret. `key` field is used only to cross-check that it is a substring of the resource path to avoid user mistakes. Following is a sample configuration file to fetch the `feature-key-file` configuration parameter value from an external secret manager. ```plaintext service { ... secrets-address-port 127.0.0.1 3005 feature-key-file secrets:TestingSecret:FeatureKey ... } ``` In the above example, `TestingSecret` is an alias for a resource in Secret Agent’s configuration file. `FeatureKey` is an identifier for the actual feature-key file stored in an external secret manager. ::: note The example above uses a plain TCP connection to connect to Secret Agent. You can also use [TLS over TCP connection](#tcp-connection) or [UDS](#uds-connection) instead. :::