Configure Upstream HTTPS

TLS (Transport Layer Security) is a cryptographic protocol designed to secure communication between two parties, such as a web browser and a web server. Services often require TLS if traffic between the API gateway and upstream services is not considered secure or private.

APISIX can encrypt upstream traffic over HTTPS. Encryption alone does not establish that the upstream is trusted: enable certificate verification to check its certificate chain and hostname.

The following steps configure HTTPS between APISIX and an upstream service, then enable certificate chain and hostname verification.

Prerequisite(s)

• Install Docker.
• Install cURL to send requests to the services for validation.
• Install and run APISIX, or follow the Getting Started tutorial to start a new APISIX instance in Docker or on Kubernetes.

Create a Route With TLS Enabled

Create a route to an example upstream httpbin.org on its default HTTPS port 443:

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" -d '
{
  "id": "quickstart-tls-upstream",
  "uri": "/ip",
  "upstream": {
    "scheme": "https",
    "nodes": {
      "httpbin.org:443": 1
    },
    "type": "roundrobin"
  }
}'

services:
  - name: httpbin Service
    routes:
      - uris:
          - /ip
        name: quickstart-tls-upstream
    upstream:
      type: roundrobin
      scheme: https
      nodes:
        - host: httpbin.org
          port: 443
          weight: 1

adc sync -f adc.yaml

Test TLS between APISIX and Upstream

Send a request to the route:

curl -i "http://127.0.0.1:9080/ip"

An HTTP/1.1 200 OK response verifies that APISIX has successfully established a connection and communicated with the upstream service over HTTPS.

Verify the Upstream Certificate

APISIX can trust upstream certificates through a per-upstream tls.ca_certs list or a shared CA store loaded at startup. A per-upstream list replaces the shared store for that upstream. The following example uses the system CA bundle commonly available in Linux images as the shared store. If your installation stores the bundle elsewhere, replace the path before merging these settings into config.yaml:

apisix:
  ssl:
    ssl_trusted_certificate: /etc/ssl/certs/ca-certificates.crt
nginx_config:
  http_server_configuration_snippet: |
    proxy_ssl_verify on;
    proxy_ssl_verify_depth 5;

❶ ssl_trusted_certificate loads the shared CA store when APISIX starts.

❷ proxy_ssl_verify enables certificate verification for HTTPS upstreams that inherit the global setting.

❸ proxy_ssl_verify_depth sets the maximum certificate-chain depth. This example allows five levels.

Reload APISIX to apply the configuration:

docker exec apisix-quickstart apisix reload

Update the route to verify the certificate and use a hostname covered by it:

curl "http://127.0.0.1:9180/apisix/admin/routes/quickstart-tls-upstream" \
  -X PATCH -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "upstream": {
      "pass_host": "rewrite",
      "upstream_host": "httpbin.org",
      "tls": {
        "verify": true
      }
    }
  }'

❶ pass_host and upstream_host use httpbin.org for the upstream Host header and TLS name.

❷ tls.verify enables verification for this upstream. If omitted, the upstream inherits the global setting. Setting it to false disables verification. Enabling it alone does not load CA certificates.

Send a request to verify that APISIX can connect to the upstream with certificate verification enabled:

curl -i "http://127.0.0.1:9080/ip"

A successful response with verification enabled confirms that the TLS handshake passed the configured trust and hostname checks. An untrusted certificate or hostname mismatch fails the upstream handshake; inspect APISIX's error log when the request returns a gateway error.

Next Steps

APISIX also supports TLS connection between clients and APISIX. See configure HTTPS between Client and APISIX.