Skip to main content

Version: 3.3.0

Built-In Variables

Built-in variables in APISIX are pre-defined variables that can be directly referenced in configurations. The actual value of these variables will be replaced into the program at runtime, making APISIX configurations more descriptive and easier to manage.

APISIX supports three types of built-in variables:

  • NGINX Variables
  • APISIX Variables
  • Custom Variables

They are evaluated in a given order.

NGINX Variables

APISIX supports NGINX variables in:

  1. Plugin configurations
  2. Custom logging formats in the configuration YAML files, similar to NGINX

Some of the commonly used variables include:

  • upstream_addr
  • remote_addr
  • request_uri
  • server_name
  • uri
  • http_user_agent

See the complete list of NGINX variables for more information.

APISIX Variables

In addition to NGINX variables, APISIX offers a variety of built-in variables to be used in plugins:

Variable NameDescription
balancer_ipUpstream server IP
balancer_portUpstream server port
consumer_nameConsumer username
consumer_group_idConsumer group ID
graphql_nameGraphQL operation name
graphql_operationGraphQL operation type
graphql_root_fieldsGraphQL root fields
route_idRoute ID
route_nameRoute name
service_idService ID
service_nameService name
resp_bodyHTTP response body
mqtt_client_idClient ID in MQTT protocol
redis_cmd_lineRedis command
rpc_timeRPC request round-trip time

Custom Variables

You can create your own variables and use them as built-in variables in plugins.

For more details on how to create custom variables, please refer to the plugins development guide (coming soon).

Evaluation Order

APISIX evaluates variables in the given order:

  1. Custom Variables
  2. APISIX Variables
  3. NGINX Variables

If a variable is successfully sourced in custom variables, APISIX will not continue to look in APISIX variables or NGINX variables.

In other words, custom variables will overwrite variables of the same names defined in APISIX variables or NGINX variables, to better meet requirements of your specific use cases. Logo

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



SOC2 Type IRed Herring

Copyright © HONG KONG APISEVEN LIMITED. 2019 – 2023. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the Apache Software Foundation