Skip to main content
Version: 2.15

Deployment Role

Concept#

Previously, the DP (Data Plane) and the CP (Control Plane) are not separate explicitly.

Although we clearly distinguish the different responsibilities of DP and CP in the documentation, not everyone has correctly deployed APISIX in the production environment.

Therefore, we introduce new concepts called deployment modes/roles, to help users deploy APISIX easily and safely.

APISIX under different deployment modes will act differently.

The table below shows the relationship among deployment modes and roles:

Deployment ModesRoleDescription
traditionaltraditionalDP + CP are deployed together by default. People need to disable enable_admin manually
decoupleddata_plane / control_planeDP and CP are deployed independently.
standalonedata_planeOnly DP, load the all configurations from local yaml file

Deployment Modes#

Traditional#

In the traditional deployment mode, one instance can be both DP & CP.

There will be a conf server listens on UNIX socket and acts as a proxy between APISIX and etcd.

Both the DP part and CP part of the instance will connect to the conf server via HTTP protocol.

Here is the example of configuration:

conf/config.yaml
deployment:
role: traditional
role_traditional:
config_provider: etcd
etcd:
host:
- http://xxxx
prefix: /apisix
timeout: 30

Decoupled#

The instance deployed as data_plane will:

  1. Fetch configurations from the CP, the default port is 9280
  2. Before the DP service starts, it will perform a health check on all CP addresses
    • If all CP addresses are unavailable, the startup fails and an exception message is output to the screen.
    • If at least one CP address is available, print the unhealthy CP check result log, and then start the APISIX service.
    • If all CP addresses are normal, start the APISIX service normally.
  3. Handle user requests.

Here is the example of configuration:

conf/config.yaml
deployment:
role: data_plane
role_data_plane:
config_provider: control_plane
control_plane:
host:
- xxxx:9280
timeout: 30
certs:
cert: /path/to/ca-cert
cert_key: /path/to/ca-cert
trusted_ca_cert: /path/to/ca-cert

The instance deployed as control_plane will:

  1. Listen on 9180 by default, and provide Admin API for Admin user
  2. Provide conf server which listens on port 9280 by default. Both the DP instances and this CP instance will connect to the conf server via HTTPS enforced by mTLS.

Here is the example of configuration:

conf/config.yaml
deployment:
role: control_plane
role_control_plan:
config_provider: etcd
conf_server:
listen: 0.0.0.0:9280
cert: /path/to/ca-cert
cert_key: /path/to/ca-cert
client_ca_cert: /path/to/ca-cert
etcd:
host:
- https://xxxx
prefix: /apisix
timeout: 30
certs:
cert: /path/to/ca-cert
cert_key: /path/to/ca-cert
trusted_ca_cert: /path/to/ca-cert

As OpenResty <= 1.21.4 doesn't support sending mTLS request, if you need to accept the connections from APISIX running on these OpenResty versions, you need to disable client certificate verification in the CP instance.

Here is the example of configuration:

conf/config.yaml
deployment:
role: control_plane
role_control_plan:
config_provider: etcd
conf_server:
listen: 0.0.0.0:9280
cert: /path/to/ca-cert
cert_key: /path/to/ca-cert
etcd:
host:
- https://xxxx
prefix: /apisix
timeout: 30
certs:
trusted_ca_cert: /path/to/ca-cert

Standalone#

In this mode, APISIX is deployed as DP and reads configurations from yaml file in the local file system.

Here is the example of configuration:

conf/config.yaml
deployment:
role: data_plane
role_data_plane:
config_provider: yaml