Configuration Files

APISIX has the following configuration files under /conf:

• config.yaml
• config.yaml.example
• apisix.yaml
• debug.yaml

In addition, you can place apisix.json under /conf if you wish to work with JSON in the file-driven standalone mode.

This document provides a reference for how configuration files are used and how to manage configuration files by environments.

Usage

config.yaml and config.yaml.example

APISIX comes with a configuration file config.yaml, which is used to customize a number of parameters, including the listening interface, deployment mode, plugin attributes, and more.

The default values for these parameters can be found in apisix/cli/config.lua.

You may find the sample configuration file for config.yaml at config.yaml.example:

apisix:
  # node_listen: 9080               # APISIX listening port (single)
  node_listen:                      # APISIX listening ports (multiple)
    - 9080
  #   - port: 9081
  #     enable_http2: true          # If not set, the default value is `false`.
  #   - ip: 127.0.0.2
  #     port: 9082
  #     enable_http2: true
  enable_admin: true
  enable_dev_mode: false
  enable_reuseport: true 
  # ...

Configurations in config.yaml is loaded once at startup. If you make any updates to this file, reload APISIX for changes to take effect.

Select the AI Gateway HTTP Client

AI Proxy, AI Proxy Multi, and AI Request Rewrite use ngx_http_ffi_client by default for requests to LLM upstreams. Set the shared plugin attribute to lua-resty-http when the installed runtime does not provide the FFI client module or when you need the Lua client path:

config.yaml

plugin_attr:
  ai-proxy:
    http_client: lua-resty-http

The accepted values are ngx_http_ffi_client and lua-resty-http. An unknown value fails plugin attribute validation. Selecting ngx_http_ffi_client on a runtime without resty.ngx_http_ffi_client causes AI upstream requests to fail when the client is created.

Plan Shared Memory

Several non-evictable shared-memory zones have larger defaults in this version so metrics, discovery state, and traces are less likely to exhaust their zones under production cardinality. The zones are shared across workers, so do not multiply their configured size by the worker count.

Feature or zone	Current default	Previous default
HTTP-only prometheus-metrics	128 MiB	10 MiB
prometheus-metrics when the Stream plugin is enabled	128 MiB	15 MiB
HTTP Nacos discovery	64 MiB	10 MiB
Stream Nacos discovery	64 MiB	10 MiB
Consul discovery shared_size	64 MiB	1 MiB
Kubernetes discovery shared_size	64 MiB	1 MiB
SkyWalking tracing_buffer	32 MiB	10 MiB

Some zones are rendered only when the corresponding plugin or discovery is enabled, while runtime-level Nacos zones are rendered with the APISIX runtime template. Before upgrading a memory-constrained gateway, compare the generated NGINX configuration and enabled plugins and discoveries with the container or host memory limit. Preserve explicit smaller overrides only after confirming they can hold the expected metric cardinality, discovery inventory, or trace load; these zones do not evict old entries to make room.

Trust Forwarding Headers

APISIX sanitizes X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, and the RFC 7239 Forwarded header in the NGINX rewrite stage before Lua plugins run. Configure apisix.trusted_addresses only with load balancer addresses or networks whose forwarding headers APISIX should accept:

config.yaml

apisix:
  trusted_addresses:
    - 192.168.1.0/24
    - 2001:db8:1234::/48

Direct peer	Forwarding behavior
No trust list configured	Preserve the inbound X-Forwarded-For chain and append the direct peer. Replace Proto, Host, and Port with values observed by APISIX, and clear Forwarded.
In trusted_addresses	Preserve the inbound X-Forwarded-For chain and append the direct peer. Restore inbound Proto, Host, Port, and Forwarded values when the peer supplied them; otherwise use the values observed by APISIX.
Outside a configured trust list	Discard the inbound X-Forwarded-For chain so the upstream receives only the direct peer. Replace Proto, Host, and Port with observed values, and clear Forwarded.

Trusting a network allows any peer in it to supply these identity-bearing values. Keep the list limited to proxies you control.

APISIX retains the client-supplied values for audit and diagnostics:

Context	Sanitized or effective value	Original client value
Lua plugin	ctx.var.http_x_forwarded_proto, ctx.var.http_x_forwarded_host, ctx.var.http_x_forwarded_port, and ctx.var.http_x_forwarded_for	ctx.var.original_x_forwarded_proto, ctx.var.original_x_forwarded_host, ctx.var.original_x_forwarded_port, ctx.var.original_x_forwarded_for, and ctx.var.original_forwarded
NGINX configuration	$scheme, $var_x_forwarded_host, and $var_x_forwarded_port	$original_x_forwarded_proto, $original_x_forwarded_host, $original_x_forwarded_port, $original_x_forwarded_for, and $original_forwarded

Lua no longer exposes ctx.var.var_x_forwarded_proto, ctx.var.var_x_forwarded_host, or ctx.var.var_x_forwarded_port. NGINX still defines $var_x_forwarded_host and $var_x_forwarded_port; use $scheme for the sanitized protocol.

In an NGINX access-log format, if, or map, $http_x_forwarded_proto, $http_x_forwarded_host, $http_x_forwarded_port, and $http_forwarded retain the raw client values cached before APISIX replaces the headers. Use the variables in the table above when the sanitized or original meaning must be explicit. $http_x_forwarded_for follows the effective value and is cleared for an untrusted peer when a trust list is configured.

apisix.yaml

In APISIX file-driven standalone deployment mode, apisix.yaml is used to configure APISIX resources, such as routes, upstreams, consumers, and others.

These configurations are loaded by APISIX into memory at startup. Changes to this file do not require a reload of APISIX as the file is monitored for changes at a regular interval.

For more information about how to configure apisix.yaml, see File-Driven Standalone Mode.

apisix.json

apisix.json is apisix.yaml's JSON-equivalent in the file-driven standalone deployment mode to configure APISIX resources.

For more information about how to configure apisix.json, see File-Driven Standalone Mode.

debug.yaml

You can enable and customize APISIX debug mode using configuration options in debug.yaml.

Changes to this file do not require a reload of APISIX as the file is monitored for changes at a regular interval.

To learn more, see Use Debug Mode.

Manage Configuration Files by Environments

Keeping configuration files separate for different environments, such as development, staging, and production, can provide several benefits, including increased flexibility, improved security, and easier maintenance.

APISIX supports separation of configuration files by environment. You can set the APISIX_PROFILE environment variable to differentiate which set of other configuration files APISIX should use.

By default, when APISIX_PROFILE is not set, APISIX looks for the following configuration files:

• conf/config.yaml
• conf/apisix.yaml
• conf/debug.yaml

If the value of APISIX_PROFILE is set to prod, APISIX looks for the following configuration files:

• conf/config-prod.yaml
• conf/apisix-prod.yaml
• conf/debug-prod.yaml

You can set APISIX_PROFILE to any other value that matches your environment.

Use Environment Variables in Configuration Files

Use ${{ENV_VAR}} for a required environment variable or ${{ENV_VAR:=default_value}} to provide a fallback. APISIX reports an error when a required variable is unavailable.

Environment substitution follows different type rules by file:

File	When substitution occurs	Type behavior
apisix.yaml	Before YAML parsing	YAML determines the resulting type. Quote a placeholder to preserve a numeric or boolean-looking value as a string.
config.yaml	After YAML parsing	A substituted numeric value becomes a number, and true or false becomes a boolean. Quoting the placeholder does not override this conversion.
apisix.json	After JSON parsing	A substituted numeric value becomes a number, and true or false becomes a boolean. JSON quoting is required for the placeholder syntax but does not prevent conversion.

Examples

If you are running APISIX locally (outside Docker), you could use the export command to set the environment variable:

export YOUR_VARIABLE=value

If you are running APISIX in Docker, you should set the environment variable using the -e flag when starting the container.

Use Environment Variables in config.yaml

The example below sets the listening ports of client requests and Admin API in environment variables.

For instance, set APISIX_NODE_LISTEN:8132 and ADMIN_API_PORT:9232 in environment variables. In config.yaml, you can reference the environment variables as follows:

config.yaml

apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT}}

After being started, APISIX will listen on port 8132 for client requests and port 9232 for Admin API requests.

Use Environment Variables in apisix.yaml

The example below sets the upstream node address of a route in an environment variable.

For instance, set UPSTREAM_ADDR:httpbin.org in an environment variable. In apisix.yaml, you can reference the environment variable as follows:

apisix.yaml

routes:
  - uri: /ip
    upstream:
      nodes:
        "${{UPSTREAM_ADDR}}": 1
      type: roundrobin

In standalone mode, APISIX will hot reload the configurations and start proxying requests to this route to httpbin.org.

Environment variables in apisix.yaml are resolved before YAML parsing. For example, if ROUTE_ID is set to 1001, quote the placeholder so that YAML parses the route ID as a string:

apisix.yaml

routes:
  - id: "${{ROUTE_ID}}"
    uri: /ip
    upstream:
      nodes:
        "${{UPSTREAM_ADDR}}": 1
      type: roundrobin

The same rule applies to Boolean values and other numbers. For example, if RETRIES=3, use retries: ${{RETRIES}} for an integer. If API_KEY=12345, use key: "${{API_KEY}}" to preserve the credential as a string.

Use Environment Variables in apisix.json

The example below sets the upstream node address of a route in an environment variable.

For instance, set UPSTREAM_ADDR:httpbin.org in an environment variable. In apisix.json, you can reference the environment variable as follows:

apisix.json

{
    "routes": [
      {
        "uri": "/ip",
        "upstream": {
          "nodes": {
            "${{UPSTREAM_ADDR}}": 1
          },
          "type": "roundrobin"
        }
      }
    ]
}

In standalone mode, APISIX will hot reload the configurations and start proxying requests to this route to httpbin.org.

Unlike apisix.yaml, apisix.json is parsed before substitution. If a placeholder resolves to 3, true, or false, APISIX converts it to a number or boolean even though the placeholder is written inside a JSON string.

Set a Fallback Value

You can also configure default values to fall back to if no environment variables are set, for example:

config.yaml

apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN:=9080}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT:=9180}}

If APISIX cannot resolve values for APISIX_NODE_LISTEN and ADMIN_API_PORT in the environment, it will default to listen on port 9080 for client requests and port 9180 for Admin API requests.