# Environment Variables API7 Gateway supports the use of environment variables for [consumer credentials](https://docs.api7.ai/api7-gateway/key-concepts/consumers-and-credentials.md), [SSL certificates](https://docs.api7.ai/api7-gateway/key-concepts/ssl-certificates.md), 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[​](#reserved-environment-variables "Direct link to Reserved Environment Variables") API7 Gateway currently reserves the following environment variables: | Variable Name | Description | | ----------------------------- | --------------------------------------- | | `APISIX_DEPLOYMENT_ETCD_HOST` | JSON array of DP Manager endpoint URLs. | | `APISIX_WORKER_PROCESSES` | Number of worker processes. | Quote the endpoint array so the shell preserves valid JSON: ``` export APISIX_DEPLOYMENT_ETCD_HOST='["https://your-host-or-ip:7943"]' ``` The generated gateway enrollment commands also use the following connection variables: | Variable | Purpose | | ----------------------------- | ------------------------------------------------------------------------------------------------ | | `API7_DP_MANAGER_ENDPOINTS` | JSON array of DP Manager endpoint URLs. | | `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. `API7_DP_MANAGER_ENDPOINTS` takes precedence over `API7_CONTROL_PLANE_ENDPOINTS`, which takes precedence over `APISIX_DEPLOYMENT_ETCD_HOST`. The gateway JSON-decodes the selected value. If it is malformed, the loader prints a parse error, does not apply that endpoint value, and does not try a lower-priority endpoint variable. The same failure also skips the certificate, key, CA, and SNI environment values. The error text names `API7_DP_MANAGER_ENDPOINTS` even when another variable supplied the value. Set the required connection variables before starting the gateway. ## Custom Environment Variables[​](#custom-environment-variables "Direct link to 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[​](#consumer-credentials "Direct link to Consumer Credentials") The following sensitive fields in consumer credentials can be stored in environment variables through the [NGINX `env` directive](https://nginx.org/en/docs/ngx_core_module.html#env): * `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-environment-variables "Direct link to Set Environment Variables") * Docker * Kubernetes Set the environment variable when deploying the gateway instance. Follow [Deploy with Docker Compose](https://docs.api7.ai/api7-gateway/install/deploy-with-docker-compose.md), then add the environment variables to the generated script. Docker example, add custom environment variables to the `docker run` command: ``` docker run -d --restart always -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:3.10.9 ``` note 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](https://docs.api7.ai/api7-gateway/install/deploy-on-kubernetes.md), 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[​](#configure-consumer-credential-with-environment-variable "Direct link to 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](https://docs.api7.ai/api7-gateway/key-concepts/consumers-and-credentials.md)), then send a request with the API key to verify authentication works. ### SSL Certificates[​](#ssl-certificates "Direct link to SSL Certificates") The sensitive fields `private key` and `certificate` in SSL Certificates can be stored in environment variables through the [NGINX `env` directive](https://nginx.org/en/docs/ngx_core_module.html#env). The following example demonstrates how you can configure the SSL certificate to fetch sensitive data from an environment variable. #### Set Environment Variables[​](#set-environment-variables-1 "Direct link to Set Environment Variables") * Docker * Kubernetes Set the environment variable when deploying the gateway instance. Follow [Deploy with Docker Compose](https://docs.api7.ai/api7-gateway/install/deploy-with-docker-compose.md), then add the environment variables to the generated script. Docker example, add custom environment variables to the `docker run` command: ``` docker run -d --restart always -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:3.10.9 ``` note 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](https://docs.api7.ai/api7-gateway/install/deploy-on-kubernetes.md), then incorporate environment variables as Kubernetes Secrets into the generated script or YAML file. Script example: ``` # ... existing setup ... kubectl apply -n demo -f - < SSL_PRIVATE_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: SSL_PRIVATE_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[​](#configure-ssl-certificate-with-environment-variables "Direct link to 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**.