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

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

  1. deployment:
  2.     role: traditional
  3.     role_traditional:
  4.         config_provider: etcd
  5.     etcd:
  6.        host:
  7.            - http://xxxx
  8.        prefix: /apisix
  9.        timeout: 30

Decoupled

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

  1. deployment:
  2.     role: data_plane
  3.     role_data_plane:
  4.        config_provider: control_plane
  5.        control_plane:
  6.            host:
  7.                - xxxx:9280
  8.            timeout: 30
  9.     certs:
  10.         cert: /path/to/ca-cert
  11.         cert_key: /path/to/ca-cert
  12.         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

  1. deployment:
  2.     role: control_plane
  3.     role_control_plan:
  4.         config_provider: etcd
  5.         conf_server:
  6.             listen: 0.0.0.0:9280
  7.             cert: /path/to/ca-cert
  8.             cert_key: /path/to/ca-cert
  9.             client_ca_cert: /path/to/ca-cert
  10.     etcd:
  11.        host:
  12.            - https://xxxx
  13.        prefix: /apisix
  14.        timeout: 30
  15.     certs:
  16.         cert: /path/to/ca-cert
  17.         cert_key: /path/to/ca-cert
  18.         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

  1. deployment:
  2.     role: control_plane
  3.     role_control_plan:
  4.         config_provider: etcd
  5.         conf_server:
  6.             listen: 0.0.0.0:9280
  7.             cert: /path/to/ca-cert
  8.             cert_key: /path/to/ca-cert
  9.     etcd:
  10.        host:
  11.            - https://xxxx
  12.        prefix: /apisix
  13.        timeout: 30
  14.     certs:
  15.         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

  1. deployment:
  2.     role: data_plane
  3.     role_data_plane:
  4.        config_provider: yaml