Configuration Files

APISIX has the following configuration files under /conf:

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

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.

apisix.yaml

In APISIX 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 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.

For more information about how to use debug mode, see Debug and Troubleshooting (coming soon).

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

In APISIX, you can use environment variables in the config.yaml or apisix.yaml configuration files for values that should be configurable during deployments, using the ${{ENV_VAR}} syntax or ${{ENV_VAR:default_value}} syntax.

The example below sets the listening ports for client requests and Admin API in environment variables:

export APISIX_NODE_LISTEN=8132
export ADMIN_API_PORT=9232

In config.yaml, 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.

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.