---
title: "Configure a proxy with Secret Agent"
description: "Route Secret Agent outbound connections to AWS, GCP, and HashiCorp Vault through an HTTP or HTTPS proxy."
---

# Configure a proxy with Secret Agent

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/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](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/aws), [GCP Secret Manager](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/gcp), or [HashiCorp Vault](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/vault).

For an overview of Secret Agent, see [Aerospike Secret Agent](https://aerospike.com/docs/database/tools/secret-agent).

**Applies to:** Secret Agent 1.4.0 or later.

## Prerequisites

-   Secret Agent is [installed](https://aerospike.com/docs/database/tools/secret-agent/install) 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.

1.  Secret Agent sends a request to the proxy such as `CONNECT secretsmanager.us-west-1.amazonaws.com:443 HTTP/1.1`.
    
2.  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.

1.  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 |
    
    Terminal window
    
    ```bash
    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:
    
    ```yaml
    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
    ```
    
2.  For a `systemd` service, add the environment variables to the service unit.
    
    ```ini
    [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
    ```
    
3.  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.
    
    ```yaml
    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](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/aws#proxy), [GCP Secret Manager](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/gcp#proxy), and [HashiCorp Vault](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/vault#proxy).

## 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](https://aerospike.com/docs/database/tools/secret-agent/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.

1.  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
    
    ```bash
    curl -x http://proxy.corp.example.com:3128 -I https://secretsmanager.us-west-1.amazonaws.com
    ```
    
2.  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.
    
3.  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](https://aerospike.com/docs/database/tools/secret-agent/metrics#proxy-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](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/aws#proxy), [GCP](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/gcp#proxy), or [HashiCorp Vault](https://aerospike.com/docs/database/tools/secret-agent/secret-manager/vault#proxy).
-   Review the [configuration template](https://aerospike.com/docs/database/tools/secret-agent/template) for all available `proxy` options.
-   Monitor proxy connections with [Metrics](https://aerospike.com/docs/database/tools/secret-agent/metrics#proxy-metrics).