环境变量
API7 网关支持使用环境变量配置消费 者凭证、SSL 证书和某些插件。有一些环境变量保留用于特殊用途，还有一些可以使用自定义名称创建并引用。
Reserved 环境变量
API7 网关目前保留以下环境变量：
| 变量名称 | 描述 |
|---|---|
APISIX_DEPLOYMENT_ETCD_HOST | etcd 主机地址。 |
APISIX_WORKER_PROCESSES | 工作进程数量。 |
要使用这些配置，请在启动网关前为环境变量赋值。
Custom 环境变量
你可以在配置文件和某些插件中使用自定义环境变量。
注意
环境变量直接配置在每个数据面（网关实例）上，并在重启后立即生效。由于这种配置方式，你无法从控制面查看实际值。此外，同一网关组中不同网关实例的环境变量配置不一致，可能导致不可预测的行为和潜在的 API 故障。
消费者凭证
消费者凭证中的以下敏感字段可以通过 NGINX env 指令存储在环境变量中：
- Key Authentication 凭证中的
key - Basic Authentication 凭证中的
password - JWT Authentication 凭证中的
secret、public key - HMAC Authentication 凭证中的
secret key
以下示例演示如何配置 Key Authentication 凭证，以从环境变量获取用户身份验证密钥。
设置环境变量
- Docker
- Kubernetes
部署网关实例时设置环境变量。请按照使用 Docker Compose 部署的说明，然后将环境变量添加到生成的脚本中。
Docker 示例：将自定义环境变量添加到 docker run 命令：
docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='["https://your-host-or-ip:443"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e ALICE_AUTH_KEY=alice-key \
-e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-e API7_CONTROL_PLANE_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:latest
备注
部署后，必须重启网关实例才能修改其环境变量。
部署网关实例时设置环境变量。请按照在 Kubernetes 上部署的说明，然后将环境变量添加到生成的脚本/YAML 中。
脚本示例：将自定义环境变量添加到 helm upgrade 命令：
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:443" \
--set "apisix.replicaCount=1" \
--set "apisix.image.repository=api7/api7-ee-3-gateway" \
--set "apisix.image.tag=latest"
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: latest
extraEnvVars:
- name: API7_GATEWAY_GROUP_SHORT_ID
value: "default"
- name: ALICE_AUTH_KEY
value: "alice-key"
etcd:
host:
- "https://your-host-or-ip:443"
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
备注
部署后，必须重启网关实例才能修改其环境变量。
使用环境变量配置消费者凭证
- 从侧边导航栏中选择网关组的消费者（Consumers）。
- 点击添加消费者（+ Add Consumer）。
- 在对话框中执行以下操作：
- 在**名称（Name）**字段中输入
Alice。 - 点击添加（Add）。
- 在**名称（Name）**字段中输入
- 在凭证（Credentials）选项卡中，点击添加密钥身份验证凭证（+ Add Key Authentication Credential）。
- 在对话框中执行以下操作：
- 在**名称（Name）**字段中输入
primary-key。 - 在密钥（Key）字段中选择手动输入（Manually Input），然后输入
$env://ALICE_AUTH_KEY。 - 点击添加（Add）。
- 在**名称（Name）**字段中输入
- 要进行验证，请在服务级别启用
key-auth插件（参阅消费者和凭证），然后使用 API 密钥发送请求，以验证身份验证是否生效。
SSL 证书
SSL 证书中的敏感字段 private key 和 certificate 可以通过 NGINX env 指令存储在环境变量中。
以下示例演示如何配置 SSL 证书，以从环境变量获取敏感数据。
设置环境变量
- Docker
- Kubernetes
部署网关实例时设置环境变量。请按照使用 Docker Compose 部署的说明，然后将环境变量添加到生成的脚本中。
Docker 示例：将自定义环境变量添加到 docker run 命令：
docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='["https://your-host-or-ip:443"]' \
-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_CONTROL_PLANE_CERT="..." \
-e API7_CONTROL_PLANE_KEY="..." \
-e API7_CONTROL_PLANE_CA="..." \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:latest
备注
部署后，必须重启网关实例才能修改其环境变量。
部署网关实例时设置环境变量。请按照在 Kubernetes 上部署的说明，然后将环境变量作为 Kubernetes Secret 添加到生成的脚本或 YAML 文件中。
脚本示例：
# ... 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
# ...
备注
部署后，必须重启网关实例才能修改其环境变量。
使用环境变量配置 SSL 证书
- 从侧边导航栏中选择网关组的SSL 证书（SSL Certificates）。
- 点击添加 SSL 证书（+ Add SSL Certificate）。
- 在对话框中执行以下操作：
- 在**证书（Certificate）**字段中输入
$env://SSL_CERTIFICATE。 - 在**密钥（Key）**字段中输入
$env://SSL_PRIVATE_KEY。 - 点击添加（Add）。
- 在**证书（Certificate）**字段中输入