Environment Variables

Explore the use of environment variables in API7 Gateway for configuring consumer credentials, SSL certificates, and plugins.

API7 Gateway supports the use of environment variables for consumer credentials, SSL certificates, and certain plugins. There are a few environment variables reserved for special purposes, and others that can be created with custom names and referenced.

Reserved Environment Variables

The gateway reads the following variables at startup, before NGINX loads. They are how the connection to the control plane is supplied, and they overwrite the equivalent keys in config.yaml — setting a value in both places does not conflict, the environment wins.

Every connection setting has two accepted names: an API7_DP_MANAGER_* form and an API7_CONTROL_PLANE_* form. API7_DP_MANAGER_* is the canonical form — it is what the API7 Dashboard writes into the deployment command it generates for you. The API7_CONTROL_PLANE_* form is kept for compatibility with instances deployed before the rename. If both are set, API7_DP_MANAGER_* wins and the other is ignored silently.

Canonical variable	Accepted alias	What it sets
`API7_DP_MANAGER_ENDPOINTS`	`API7_CONTROL_PLANE_ENDPOINTS`, then `APISIX_DEPLOYMENT_ETCD_HOST`	`deployment.etcd.host`. A JSON array of URLs, for example `'["https://dp-manager:7943"]'` — not a bare URL.
`API7_DP_MANAGER_CERT`	`API7_CONTROL_PLANE_CERT`	The client certificate the instance presents to DP Manager. Written to `conf/cert/api7ee.crt`; the path is set in `deployment.etcd.tls.cert`.
`API7_DP_MANAGER_KEY`	`API7_CONTROL_PLANE_KEY`	The matching private key. Written to `conf/cert/api7ee.key`; the path is set in `deployment.etcd.tls.key`.
`API7_DP_MANAGER_CA`	`API7_CONTROL_PLANE_CA`	The CA that signs the DP Manager server certificate. Written to `conf/cert/api7ee_ca.crt` and appended to `apisix.ssl.ssl_trusted_certificate`, so any CA already listed there is kept.
`API7_DP_MANAGER_SNI`	`API7_CONTROL_PLANE_SNI`	`deployment.etcd.tls.sni`. Needed when you reach DP Manager at an address that is not in its certificate's SAN list.
`API7_DP_MANAGER_TOKEN`	`API7_CONTROL_PLANE_TOKEN`	Sent as the `Control-Plane-Token` header. Used instead of a client certificate in token-authenticated deployments.
`API7_GATEWAY_GROUP_SHORT_ID`	—	Which gateway group the instance joins. Always required.
`APISIX_WORKER_PROCESSES`	—	Overrides `nginx_config.worker_processes`.
`APISIX_PROFILE`	—	Selects the configuration profile, so the instance reads `conf/config-<profile>.yaml`.
`GCP_SERVICE_ACCOUNT`	—	A GCP service account JSON, read at runtime by the AI plugins as an alternative to putting it in the plugin configuration.

CERT and KEY are applied as a pair. If only one of the two is set, the gateway stops there: tls.cert, tls.key and the CA are all left at whatever config.yaml holds. The endpoints and the SNI are read before that point and still take effect, so the instance connects to the right address and then fails the handshake — a certificate-verification failure that looks unrelated to the variable you forgot, because the CA silently never took effect.

The same stop applies when neither is set, which is the case in a token-authenticated deployment. API7_DP_MANAGER_CA is ignored there too; supply the CA through config.yaml instead.

The mixed prefixes in the Dashboard-generated command are expected, not a mistake. The command sets API7_DP_MANAGER_ENDPOINTS, API7_DP_MANAGER_CERT and API7_DP_MANAGER_KEY, but API7_CONTROL_PLANE_CA. Both prefixes resolve to the same setting, so the command works as generated — and so does rewriting the CA line to API7_DP_MANAGER_CA if you prefer one prefix throughout.

Referencing Variables in `config.yaml`

Anywhere in config.yaml you can substitute an environment variable with ${{VAR}}, or supply a fallback with ${{VAR:=default}}. The doubled braces are deliberate — NGINX has already taken $var and ${var}.

deployment:
  etcd:
    host:
      - ${{DP_MANAGER_URL:=https://dp-manager:7943}}

If a variable is referenced without a default and is not set in the environment, the gateway refuses to start rather than falling back to an empty value.

Custom Environment Variables

You can use custom environment variables in configuration files and for certain plugins.

Environment variables are configured directly on each data plane (gateway instance) and take effect immediately upon restart. Due to this configuration method, you cannot view the actual values from the control plane. Additionally, inconsistencies in environment variable configurations across different gateway instances within a gateway group can lead to unpredictable behavior and potential API failures.

Consumer Credentials

The following sensitive fields in consumer credentials can be stored in environment variables through the NGINX env directive:

key in Key Authentication credential
password in Basic Authentication credential
secret, public key in JWT Authentication credential
secret key in HMAC Authentication credential

The following example demonstrates how you can configure the key authentication credential to fetch a user authentication key from an environment variable.

Set Environment Variables

Set the environment variable when deploying the gateway instance. Follow Deploy with Docker Compose, then add the environment variables to the generated script.

Docker example, add custom environment variables to the docker run command:

docker run -d -e API7_DP_MANAGER_ENDPOINTS='["https://your-host-or-ip:7943"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e ALICE_AUTH_KEY=alice-key \
-e API7_DP_MANAGER_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-e API7_DP_MANAGER_KEY="-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----" \
-e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:3.10.7

Once deployed, gateway instance environment variables cannot be modified without restarting the instance.

Set the environment variable when deploying the gateway instance. Follow Deploy on Kubernetes, then add the environment variables to the generated script/YAML.

Script example, add custom environment variables to the helm upgrade command:

helm repo add api7 https://charts.api7.ai
helm repo update
# ... existing setup ...
helm upgrade --install -n test --create-namespace api7-ee-3-gateway api7/gateway \
  --set "etcd.auth.tls.enabled=true" \
  --set "etcd.auth.tls.existingSecret=api7-ee-3-gateway-tls" \
  --set "etcd.auth.tls.certFilename=tls.crt" \
  --set "etcd.auth.tls.certKeyFilename=tls.key" \
  --set "etcd.auth.tls.verify=true" \
  --set "gateway.tls.existingCASecret=api7-ee-3-gateway-tls" \
  --set "gateway.tls.certCAFilename=ca.crt" \
  --set "apisix.extraEnvVars[0].name=API7_GATEWAY_GROUP_SHORT_ID" \
  --set "apisix.extraEnvVars[0].value=default" \
  --set "apisix.extraEnvVars[1].name=ALICE_AUTH_KEY" \
  --set "apisix.extraEnvVars[1].value=alice-key" \
  --set "etcd.host[0]=https://your-host-or-ip:7943" \
  --set "apisix.replicaCount=1" \
  --set "apisix.image.repository=api7/api7-ee-3-gateway" \
  --set "apisix.image.tag=3.10.7"

YAML example:

apiVersion: v1
kind: Secret
metadata:
  namespace: test
  name: api7-ee-3-gateway-tls
type: kubernetes.io/tls
# ...
---
apisix:
  replicaCount: 1
  image:
    repository: api7/api7-ee-3-gateway
    tag: "3.10.7"
  extraEnvVars:
  - name: API7_GATEWAY_GROUP_SHORT_ID
    value: "default"
  - name: ALICE_AUTH_KEY
    value: "alice-key"
etcd:
  host:
  - "https://your-host-or-ip:7943"
  auth:
    tls:
      enabled: true
      existingSecret: api7-ee-3-gateway-tls
      certFilename: tls.crt
      certKeyFilename: tls.key
      verify: true
gateway:
  tls:
    existingCASecret: api7-ee-3-gateway-tls
    certCAFilename: ca.crt

Once deployed, gateway instance environment variables cannot be modified without restarting the instance.

Configure Consumer Credential with Environment Variable

Select Consumers of your gateway group from the side navigation bar.
Click + Add Consumer.
In the dialog box, do the following:
- In the Name field, enter Alice.
- Click Add.
Under the Credentials tab, click + Add Key Authentication Credential.
In the dialog box, do the following:
- In the Name field, enter primary-key.
- In the Key field, choose Manually Input, then enter $env://ALICE_AUTH_KEY.
- Click Add.
To validate, enable the key-auth plugin at the service level (see Consumers and Credentials), then send a request with the API key to verify authentication works.

SSL Certificates

The sensitive fields private key and certificate in SSL Certificates can be stored in environment variables through the NGINX env directive.

The following example demonstrates how you can configure the SSL certificate to fetch sensitive data from an environment variable.

Set Environment Variables

Set the environment variable when deploying the gateway instance. Follow Deploy with Docker Compose, then add the environment variables to the generated script.

Docker example, add custom environment variables to the docker run command:

docker run -d -e API7_DP_MANAGER_ENDPOINTS='["https://your-host-or-ip:7943"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e SSL_CERTIFICATE="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-e SSL_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----" \
-e API7_DP_MANAGER_CERT="..." \
-e API7_DP_MANAGER_KEY="..." \
-e API7_CONTROL_PLANE_CA="..." \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:3.10.7

Once deployed, gateway instance environment variables cannot be modified without restarting the instance.

Set the environment variable when deploying the gateway instance. Follow Deploy on Kubernetes, then incorporate environment variables as Kubernetes Secrets into the generated script or YAML file.

Script example:

# ... existing setup ...
kubectl apply -n demo -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  namespace: demo
  name: env-secrets
type: Opaque
data:
  SSL_CERTIFICATE: <base64-encoded-cert>
  SSL_PRIVATE_KEY: <base64-encoded-key>
EOF
helm upgrade --install -n demo --create-namespace api7-ee-3-gateway api7/gateway \
  --set "apisix.extraEnvVarsSecret=env-secrets" \
  # ... other settings ...

YAML example:

apiVersion: v1
kind: Secret
metadata:
  name: env-secrets
  namespace: demo
type: Opaque
data:
  SSL_CERTIFICATE: <base64-encoded-cert>
  SSL_PRIVATE_KEY: <base64-encoded-key>
---
apisix:
  replicaCount: 1
  extraEnvVarsSecret: env-secrets
# ...

Once deployed, gateway instance environment variables cannot be modified without restarting the instance.

Configure SSL Certificate with Environment Variables

Select SSL Certificates of your gateway group from the side navigation bar.
Click + Add SSL Certificate.
In the dialog box, do the following:
- In the Certificate field, enter $env://SSL_CERTIFICATE.
- In the Key field, enter $env://SSL_PRIVATE_KEY.
- Click Add.