Skip to main content

Version: 3.2.16.3

Environment Variables

API7 Enterprise supports the use of consumer credentials, SSL certificate, 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 Enterprise currently reserves the following environment variables:

Variable NameDescription
APISIX_DEPLOYMENT_ETCD_HOSTetcd host address.
APISIX_WORKER_PROCESSESNumber of worker processes.

To use these configurations, assign values to the environment variables before starting APISIX.

Custom Environment Variables

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

danger

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 field 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 user authentication key from an environment variable.

Set Environment Variables

Set the environment variable when deploy the gateway instance. Follow add gateway instance, 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_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-----
MIIBiDCCATqgAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe
Fw0yNDEwMjkwMzM4NTJaFw0yNTExMjgwMzM4NTJaMDAxDTALBgNVBAoTBEFQSTcx
HzAdBgNVBAMTFmFwaTdlZTMtYXBpc2l4LWdhdGV3YXkwKjAFBgMrZXADIQBpBV0D
YBeCedUrIWvyk2YHORcmzBeCiActHJk3u4ZkyKNkMGIwDgYDVR0PAQH/BAQDAgeA
MBMGA1UdJQQMMAoGCCsGAQUFBwMCMC0GA1UdDgQmBCQyOWEzZmVlZi1hNzM2LTQy
OTEtODlmZS0xOWI4MDFjODNjZWQwDAYDVR0jBAUwA4ABMDAFBgMrZXADQQA0aeIB
5Gy5cVYrRgM+PRduSumjDMyDFNbH01GNQ/5RTeyMaH3lAj64JLOO4sQe7gy3dDxx
b7N9mKGl8iMzSLwF
-----END CERTIFICATE-----" \
-e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ6hn4EQKXSh4U+2SFPJhBh3RxN/1trnsu2Zjp6hRB5A
-----END PRIVATE KEY-----" \
-e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
BhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcxETAPBgNV
BAMTCEFQSTcgSW5jMB4XDTI0MDkwNzA4MTc0NVoXDTM0MDkwNTA4MTc0NVowRDEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcx
ETAPBgNVBAMTCEFQSTcgSW5jMCowBQYDK2VwAyEAkTj447bpztG1dc0HVW74za+v
NEAhU7mySYSmUSwdRfCjLzAtMA4GA1UdDwEB/wQEAwIChDAPBgNVHRMBAf8EBTAD
AQH/MAoGA1UdDgQDBAEwMAUGAytlcANBAKxxBg/CEnOoxQnVd8ixHKJCgChZ2IZE
BLCHaQTEbmfy8RQ+po0cKOthWFDx8gsx2AjdkLO5PPaHPujIXyfz8QI=
-----END CERTIFICATE-----" \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:dev
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.
  1. Under the Credentials tab, click + Add Key Authentication Credential.
  2. 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.
  1. To validate, see enable key authentication for APIs for instruction, and enable the Key Auth Plugin on the service level. Then follow validate key authentication instruction.

SSL Certificates

The sensitive field 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 add gateway instance, 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_CONTROL_PLANE_ENDPOINTS='["https://your-host-or-ip:443"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e SSL_CERTIFICATE="-----BEGIN CERTIFICATE-----
MIIBiDCCATqgAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe
Fw0yNDEwMjkwMzM4NTJaFw0yNTExMjgwMzM4NTJaMDAxDTALBgNVBAoTBEFQSTcx
HzAdBgNVBAMTFmFwaTdlZTMtYXBpc2l4LWdhdGV3YXkwKjAFBgMrZXADIQBpBV0D
YBeCedUrIWvyk2YHORcmzBeCiActHJk3u4ZkyKNkMGIwDgYDVR0PAQH/BAQDAgeA
MBMGA1UdJQQMMAoGCCsGAQUFBwMCMC0GA1UdDgQmBCQyOWEzZmVlZi1hNzM2LTQy
OTEtODlmZS0xOWI4MDFjODNjZWQwDAYDVR0jBAUwA4ABMDAFBgMrZXADQQA0aeIB
5Gy5cVYrRgM+PRduSumjDMyDFNbH01GNQ/5RTeyMaH3lAj64JLOO4sQe7gy3dDxx
b7N9mKGl8iMzSLwF
-----END CERTIFICATE-----" \
-e SSL_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ6hn4EQKXSh4U+2SFPJhBh3RxN/1trnsu2Zjp6hRB5A
-----END PRIVATE KEY-----" \
-e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
MIIBiDCCATqgAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe
Fw0yNDEwMjkwMzM4NTJaFw0yNTExMjgwMzM4NTJaMDAxDTALBgNVBAoTBEFQSTcx
HzAdBgNVBAMTFmFwaTdlZTMtYXBpc2l4LWdhdGV3YXkwKjAFBgMrZXADIQBpBV0D
YBeCedUrIWvyk2YHORcmzBeCiActHJk3u4ZkyKNkMGIwDgYDVR0PAQH/BAQDAgeA
MBMGA1UdJQQMMAoGCCsGAQUFBwMCMC0GA1UdDgQmBCQyOWEzZmVlZi1hNzM2LTQy
OTEtODlmZS0xOWI4MDFjODNjZWQwDAYDVR0jBAUwA4ABMDAFBgMrZXADQQA0aeIB
5Gy5cVYrRgM+PRduSumjDMyDFNbH01GNQ/5RTeyMaH3lAj64JLOO4sQe7gy3dDxx
b7N9mKGl8iMzSLwF
-----END CERTIFICATE-----" \
-e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ6hn4EQKXSh4U+2SFPJhBh3RxN/1trnsu2Zjp6hRB5A
-----END PRIVATE KEY-----" \
-e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
BhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcxETAPBgNV
BAMTCEFQSTcgSW5jMB4XDTI0MDkwNzA4MTc0NVoXDTM0MDkwNTA4MTc0NVowRDEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcx
ETAPBgNVBAMTCEFQSTcgSW5jMCowBQYDK2VwAyEAkTj447bpztG1dc0HVW74za+v
NEAhU7mySYSmUSwdRfCjLzAtMA4GA1UdDwEB/wQEAwIChDAPBgNVHRMBAf8EBTAD
AQH/MAoGA1UdDgQDBAEwMAUGAytlcANBAKxxBg/CEnOoxQnVd8ixHKJCgChZ2IZE
BLCHaQTEbmfy8RQ+po0cKOthWFDx8gsx2AjdkLO5PPaHPujIXyfz8QI=
-----END CERTIFICATE-----" \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:dev
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.

API7.ai Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.

Product

API7 Cloud

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation