Environment Variables

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

API7 Gateway currently reserves the following environment variables:

Variable Name	Description
APISIX_DEPLOYMENT_ETCD_HOST	etcd host address.
APISIX_WORKER_PROCESSES	Number of worker processes.

The generated gateway enrollment commands also use the following connection variables:

Variable	Purpose
API7_DP_MANAGER_ENDPOINTS	JSON array of DP Manager endpoint URLs. Takes precedence over API7_CONTROL_PLANE_ENDPOINTS, then APISIX_DEPLOYMENT_ETCD_HOST.
API7_DP_MANAGER_CERT	Gateway client certificate in PEM format. API7_CONTROL_PLANE_CERT is an accepted alias.
API7_DP_MANAGER_KEY	Matching client private key in PEM format. API7_CONTROL_PLANE_KEY is an accepted alias.
API7_DP_MANAGER_CA	CA certificate used for the DP Manager connection. API7_CONTROL_PLANE_CA is an accepted alias.
API7_DP_MANAGER_SNI	Optional TLS server name. API7_CONTROL_PLANE_SNI is an accepted alias.
API7_GATEWAY_GROUP_SHORT_ID	Gateway group's configuration prefix, supplied by the enrollment command.

Supply the client certificate and key together. If either is absent, the connection setup does not apply either environment value or the CA value from this group of overrides. Use the material generated for the same gateway group and deployment.

Set the required connection variables before starting the gateway.

Custom Environment Variables

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

warning

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

Docker

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_DP_MANAGER_CA="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:latest

note

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

Kubernetes

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 \
  --version "~3.10.0" \
  --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"

YAML example:

apiVersion: v1
kind: Secret
metadata:
  namespace: test
  name: api7-ee-3-gateway-tls
type: kubernetes.io/tls
# ...
---
apisix:
  replicaCount: 1
  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

note

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

Configure Consumer Credential with Environment Variable

1. Select Consumers of your gateway group from the side navigation bar.
2. Click + Add Consumer.
3. In the dialog box, do the following:
   • In the Name field, enter Alice.
   • Click Add.
4. Under the Credentials tab, click + Add Key Authentication Credential.
5. 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.
6. 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

Docker

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_DP_MANAGER_CA="..." \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:latest

note

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

Kubernetes

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 \
  --version "~3.10.0" \
  --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
# ...

note

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

Configure SSL Certificate with Environment Variables

1. Select SSL Certificates of your gateway group from the side navigation bar.
2. Click + Add SSL Certificate.
3. 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.