Deployment Modes

The deployment mode determines whether configuration management shares an instance with request proxying and how APISIX receives configuration. Traditional mode combines the roles, decoupled mode separates them, and standalone mode runs without etcd:

• Traditional mode
• Decoupled mode
• Standalone mode

Traditional Mode

In traditional mode, every APISIX instance runs as both a control plane and data plane. APISIX configurations are stored in etcd. The APISIX instance dynamically routes requests and responses, as well as interacts with etcd to synchronize configurations.

This example shows a sample configuration for deploying APISIX in traditional mode:

config.yaml

apisix:
  node_listen:
    - port: 9080
deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  admin:
    admin_listen:
      port: 9180
    admin_key_required: true
    allow_admin:
      - 127.0.0.0/24
    admin_key:
      -
        name: admin
        key: ${{CUSTOM_API_WRITE_KEY}}
        role: admin
      -
        name: viewer
        key: ${{CUSTOM_API_VIEW_KEY}}
        role: viewer

Running APISIX in traditional mode is the simplest way to get APISIX started and can reduce additional configuration management and overhead. However, there are some downsides too. As the responsibilities of data plane and control plane are not separate, deploying APISIX in traditional mode may not meet the production requirements in resiliency and availability.

Decoupled Mode

In decoupled mode, data-plane instances proxy client requests, while control-plane instances manage the configuration that data planes use. In the etcd setup below, the control plane writes configuration to etcd, where data planes receive updates. Client requests do not pass through the control plane.

This example shows a sample configuration for deploying APISIX as a data plane in decoupled mode:

config.yaml

deployment:
  role: data_plane
  role_data_plane:
    config_provider: etcd

This example shows a sample configuration for deploying APISIX as a control plane in decoupled mode:

config.yaml

deployment:
  role: control_plane
  role_control_plane:
    config_provider: etcd
  admin:
    admin_key_required: true
    allow_admin:
      - 127.0.0.0/24
    admin_key:
      -
        name: admin
        key: ${{CUSTOM_API_WRITE_KEY}}
        role: admin
      -
        name: viewer
        key: ${{CUSTOM_API_VIEW_KEY}}
        role: viewer 

Running APISIX in decoupled mode brings some benefits:

• Improve scalability

  Separate roles let you add data-plane instances as request traffic grows without adding control-plane instances. Configuration still reaches them through etcd.

• Improve security

  Separate control-plane and data-plane instances let you restrict access to the Admin API independently from the proxy listeners. This is not a complete security boundary: a compromised control plane can change the configuration that data planes receive through etcd. If a control plane is offline, data planes continue using their last configuration.

Separation also adds operational complexity: you must manage both roles and their connectivity to etcd. A new configuration takes effect on a data plane only after it receives the update.

For details about how to get started with APISIX in decoupled mode, see Install APISIX in decoupled mode using Docker.

Standalone Mode

Standalone mode runs without etcd. In file-driven mode, APISIX uses the data-plane role and loads configuration from apisix.yaml. In API-driven mode, it uses the traditional role with the YAML configuration provider and receives configuration through the standalone Admin API, storing it in memory.

File-Driven

This example shows a sample configuration for deploying APISIX in file-driven standalone mode:

config.yaml

apisix:
  enable_admin: false
deployment:
  role: data_plane
  role_data_plane:
    config_provider: yaml   # yaml or json

The combination of standalone mode and declarative configuration has a number of benefits:

• Reduce complexity

  You do not need to install and manage the etcd. In this mode, all APISIX configurations are stored in-memory on the node.

• Consolidate your APISIX configurations

  All APISIX configurations are kept in a single source of truths to reduce the possibility of errors and even simplify configuration management.

For details about how to get started with APISIX in file-driven standalone mode, see Install APISIX in standalone mode using Docker.

For details about how to configure APISIX, see File-Driven Standalone configurations.

API-Driven

API-driven mode stores routing configuration in memory rather than in a configuration file. A controller sends complete snapshots through the dedicated standalone Admin API. Workers load accepted updates without a gateway restart, but acceptance and worker synchronization are separate events. A bounded wait can confirm synchronization on the receiving instance; a controller must still deliver and verify configuration on each instance in a multi-instance deployment.

caution

This feature is designed specifically for the APISIX Ingress Controller and is primarily intended for integration with ADC. APISIX provides an official, end-to-end, stateless Ingress Controller implementation. Do not use this feature directly unless you fully understand its internal workings and behavior.

This example starts both the gateway and the API-driven Admin API with the YAML configuration provider:

config.yaml

deployment:
  role: traditional
  role_traditional:
    config_provider: yaml

This disables the local file-based configuration source in favor of the API. When APISIX starts, it awaits configuration updates through the API.

For details about how to work with the standalone Admin API, see API-Driven Standalone configurations.