Configure a proxy with Secret Agent

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Configure a proxy when Secret Agent 1.4.0 or later cannot reach secret managers directly and must route those connections through an HTTP or HTTPS proxy because of network policy, compliance requirements, or your network architecture. Proxy settings apply only to connections from Secret Agent to secret managers. Traffic from Aerospike Database or other clients to Secret Agent is not proxied.

If your host can reach the secret manager directly, you do not need proxy settings. Configure your backend instead: AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault.

For an overview of Secret Agent, see Aerospike Secret Agent.

Applies to: Secret Agent 1.4.0 or later.

Prerequisites

Secret Agent is installed and you know which secret manager backend you use.
A proxy URL and any required TLS credentials (CA certificate file or client certificate).
Edit access to the Secret Agent configuration file (YAML) or the environment where Secret Agent runs (for example, a systemd unit or container).

How proxy routing works

When a proxy is configured, Secret Agent tunnels outbound secret manager traffic through the proxy using the HTTP CONNECT method.

Secret Agent sends a request to the proxy such as CONNECT secretsmanager.us-west-1.amazonaws.com:443 HTTP/1.1.
If the proxy accepts the connection (HTTP 200), Secret Agent uses that tunnel for TLS and API traffic to the secret manager.

Proxy URL schemes

Supported proxy URLs use http:// or https:// schemes.

With http://, the TCP connection to the proxy is cleartext and the CONNECT request is sent in plain HTTP.
With https://, Secret Agent first establishes TLS to the proxy, then sends the same CONNECT request over that encrypted connection.

Configuration sources and precedence

Secret Agent reads proxy settings from environment variables (HTTP_PROXY, HTTPS_PROXY, and NO_PROXY) or from a proxy block in the Secret Agent configuration file (YAML) under each secret-manager backend (aws, gcp, or vault).

For each backend, proxy.url in the YAML file overrides the HTTP_PROXY and HTTPS_PROXY environment variables. If no proxy URL is set, Secret Agent connects directly to secret managers.

TLS to the proxy (proxy.tls)

For an https:// proxy URL, optional TLS settings go in a nested proxy.tls block in the YAML file (ca-file, cert-file, key-file, and tls-name).

These options cannot be set with environment variables. They apply only to TLS between Secret Agent and the proxy, not to TLS inside the tunnel to AWS, Google APIs, or Vault.

Backend behavior inside the tunnel

All backends use the same proxy tunnel mechanism but handle internal encryption differently:

AWS Secrets Manager: The proxy carries Secrets Manager API calls and STS role-assumption requests. TLS to AWS inside the tunnel uses your operating system’s trusted certificate store.
GCP Secret Manager: Outbound gRPC calls to secretmanager.googleapis.com go through the same proxy tunnel. gRPC handles its own TLS to Google inside that tunnel.
HashiCorp Vault: Vault HTTP API calls use the same proxy tunnel. Vault server TLS options in the YAML file (ca-file, client-cert-file, and related settings) are separate from proxy.tls settings for the proxy itself.

Proxy exclusions (NO_PROXY)

When a proxy is configured, Secret Agent still connects directly, without the proxy, to cloud metadata endpoints and local hosts. It also skips the proxy for any hosts listed in NO_PROXY.

The following hosts are always excluded from the proxy:

Host	Reason for exclusion
`169.254.169.254`	AWS instance metadata service
`metadata.google.internal`	GCP instance metadata service
`localhost`, `127.0.0.1`, `::1`	Local services (for example Vault on the same host)

Configure a proxy

Set proxy settings for all backends with environment variables, or override them per backend in the Secret Agent configuration file. To authenticate to the proxy with a username and password, embed credentials in proxy.url (for example, http://user:password@proxy.corp.example.com:3128). For mutual TLS (mTLS) to the proxy, set proxy.tls.cert-file and proxy.tls.key-file in the configuration file.

Set the proxy URL using environment variables or the configuration file.

Use environment variables when the same proxy applies to every backend on the host:

Variable	Purpose
`HTTPS_PROXY` / `https_proxy`	Proxy URL when the secret manager connection uses HTTPS (AWS and GCP)
`HTTP_PROXY` / `http_proxy`	Proxy URL when the secret manager connection uses HTTP (Vault with an `http://` endpoint)
`NO_PROXY` / `no_proxy`	Comma-separated hostnames and IP ranges that must not use the proxy

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=internal.corp,10.0.0.0/8

To override environment variables for one backend, add a proxy block under that backend in the secret-manager section of the configuration file:

secret-manager:
  aws:
    region: us-west-1
    proxy:
      url: http://proxy.corp.example.com:3128
    resources:
      TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j

For a systemd service, add the environment variables to the service unit.

[Service]
Environment="HTTPS_PROXY=http://proxy.corp.example.com:3128"
Environment="NO_PROXY=169.254.169.254,metadata.google.internal"
ExecStart=/usr/local/bin/aerospike-secret-agent --config-file /etc/aerospike-secret-agent/config.yaml

For an HTTPS proxy with a private CA or mutual TLS (mTLS), add a tls block under proxy in the configuration file. Mount the certificate files on the host or in a container.

These TLS file paths cannot be set with environment variables.

secret-manager:
  aws:
    region: us-east-1
    proxy:
      url: https://proxy.corp.example.com:3128
      tls:
        ca-file: /etc/aerospike-secret-agent/proxy-ca.crt
        cert-file: /etc/aerospike-secret-agent/proxy-client.crt
        key-file: /etc/aerospike-secret-agent/proxy-client.key
        tls-name: proxy.corp.example.com
    resources:
      TestingSecret: arn:aws:secretsmanager:us-east-1:123456789012:secret:TestingSecret-xxxxx

For backend-specific examples, see AWS Secrets Manager, GCP Secret Manager, and HashiCorp Vault.

Configuration reference

Parameter	Description
`proxy.url`	HTTP or HTTPS proxy URL. When set in the configuration file, overrides `HTTP_PROXY` and `HTTPS_PROXY` for that backend.
`proxy.tls.ca-file`	CA certificate file (PEM format) used to verify the proxy’s server certificate when `proxy.url` uses `https://`. Applies only to TLS between Secret Agent and the proxy.
`proxy.tls.cert-file`	Client certificate file (PEM format) for mTLS to the proxy. Must be set together with `proxy.tls.key-file`.
`proxy.tls.key-file`	Private key file (PEM format) for `proxy.tls.cert-file`.
`proxy.tls.tls-name`	Hostname to send during TLS to the proxy (SNI) when it differs from the hostname in `proxy.url`.

See the configuration template for all available proxy options.

Verify the configuration

When a proxy URL is configured (proxy.url in the YAML file or HTTP_PROXY / HTTPS_PROXY in the environment), Secret Agent validates the settings at startup and exits with an error if anything is invalid. Validation checks that certificate files exist and match, that Secret Agent can reach the proxy over TCP, and, for https:// proxy URLs, that a TLS connection to the proxy succeeds using your configured CA and client certificate.

Test proxy reachability before starting Secret Agent.

Use curl with the -x flag to route the request through the proxy. For mTLS, add matching --cacert, --cert, and --key options.
Terminal window
```
curl -x http://proxy.corp.example.com:3128 -I https://secretsmanager.us-west-1.amazonaws.com
```
Start Secret Agent and confirm the proxy is active in the logs.

At startup, Secret Agent logs Using proxy: ... when a proxy is active. Usernames and passwords in the URL are redacted in the log.
Monitor proxy connections on the Prometheus metrics endpoint.

When a proxy is configured, Secret Agent reports connection attempts, successes, and errors with the label module="proxy". See Metrics.

Troubleshoot

Message	Likely cause	Fix
`dial proxy ...`	Secret Agent could not open a TCP connection to the proxy	Confirm the proxy host and port are reachable from the Secret Agent host.
`tls handshake to proxy`	Secret Agent connected to the proxy but TLS verification failed	Verify certificate files and try `proxy.tls.tls-name` if the proxy certificate name differs from the URL host.
`proxy CONNECT failed: 407`	The proxy rejected the request because authentication is required	Add credentials to `proxy.url`.
`proxy CONNECT failed: 403`	The proxy rejected the tunnel to the secret manager host	Ask your network team to allow the secret manager endpoint through the proxy.
`proxy cert-file and key-file must be set together`	Only one of the mTLS client certificate files is configured	Set both `proxy.tls.cert-file` and `proxy.tls.key-file`.

Next steps

Add proxy settings to your secret manager configuration: AWS, GCP, or HashiCorp Vault.
Review the configuration template for all available proxy options.
Monitor proxy connections with Metrics.