Deployment modes

APISIX has three different deployment modes for different production use cases. The table below summarises the deployment modes:

Deployment modeRolesDescription
traditionaltraditionalData plane and control plane are deployed together. enable_admin attribute should be disabled manually.
decoupleddata_plane / control_planeData plane and control plane are deployed independently.
standalonedata_planeOnly data_plane is deployed and the configurations are loaded from a local YAML file.

Each of these deployment modes are explained in detail below.

Traditional

In the traditional deployment mode, one instance of APISIX will be both the data_plane and the control_plane.

traditional deployment mode

There will be a conf server that listens on the UNIX socket and acts as a proxy between APISIX and etcd. Both the data and the control planes connect to this conf server via HTTP.

An example configuration of the traditional deployment mode is shown below:

conf/config.yaml

  1. apisix:
  2.     node_listen:
  3.         - port: 9080
  4. deployment:
  5.     role: traditional
  6.     role_traditional:
  7.         config_provider: etcd
  8.     admin:
  9.         admin_listen:
  10.             port: 9180
  11.     etcd:
  12.        host:
  13.            - http://${etcd_IP}:${etcd_Port}
  14.        prefix: /apisix
  15.        timeout: 30
  16. #END

The instance of APISIX deployed as the traditional role will:

  1. Listen on port 9080 to handle user requests, controlled by node_listen.
  2. Listen on port 9180 to handle Admin API requests, controlled by admin_listen.

Decoupled

In the decoupled deployment mode the data_plane and control_plane instances of APISIX are deployed separately, i.e., one instance of APISIX is configured to be a data plane and the other to be a control plane.

decoupled

The instance of APISIX deployed as the data plane will:

  1. Fetch the configuration from the control plane. The default port is 9280.
  2. Performs a health check on all configured control plane addresses before starting the service.
    1. If the control plane addresses are unavailable, the startup fails and an exception is thrown.
    2. If at least one control plane address is available, it prints the unhealthy control planes logs, and starts the APISIX service.
    3. If all control planes are normal, APISIX service is started normally.
  3. Once the service is started, it will handle the user requests.

The example below shows the configuration of an APISIX instance as data plane in the decoupled mode:

conf/config.yaml

  1. deployment:
  2.     role: data_plane
  3.     role_data_plane:
  4.        config_provider: control_plane
  5.        control_plane:
  6.            host:
  7.                - https://${Control_Plane_IP}:9280
  8.            prefix: /apisix
  9.            timeout: 30
  10.     certs:
  11.         cert: /path/to/ca-cert
  12.         cert_key: /path/to/ca-cert
  13.         trusted_ca_cert: /path/to/ca-cert
  14. #END

The instance of APISIX deployed as the control plane will:

  1. Listen on port 9180 and handle Admin API requests.
  2. Provide the conf server which will listen on port 9280. Both the control plane and the data plane will connect to this via HTTPS enforced by mTLS.

The example below shows the configuration of an APISIX instance as control plane in the decoupled mode:

conf/config.yaml

  1. deployment:
  2.     role: control_plane
  3.     role_control_plane:
  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://${etcd_IP}:${etcd_Port}
  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
  19. #END
Deployment modes - 图3tip

As OpenResty <= 1.21.4 does not support sending mTLS requests, to accept connections from APISIX running on these OpenResty versions, you need to disable the client certificate verification in the control plane instance as shown below:

conf/config.yaml

  1. deployment:
  2.     role: control_plane
  3.     role_control_plane:
  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://${etcd_IP}:${etcd_Port}
  12.        prefix: /apisix
  13.        timeout: 30
  14.     certs:
  15.         trusted_ca_cert: /path/to/ca-cert
  16. #END

Standalone

Turning on the APISIX node in Stand-alone mode will no longer use the default etcd as the configuration center.

This method is more suitable for two types of users:

  1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules with a full yaml configuration.
  2. Different configuration centers: There are many implementations of the configuration center, such as Consul, etc., using the full yaml file for intermediate conversion.

The routing rules in the conf/apisix.yaml file are loaded into memory immediately after the APISIX node service starts. And every time interval (default 1 second), will try to detect whether the file content is updated, if there is an update, reload the rule.

Note: Reloading and updating routing rules are all hot memory updates. There is no replacement of working processes, since it’s a hot update.

Since the current Admin API is based on the etcd configuration center solution, enable Admin API is not allowed when the Stand-alone mode is enabled.

Standalone mode can only be enabled when we set the role of APISIX as data plane. We set deployment.role to data_plane and deployment.role_data_plane.config_provider to yaml.

Refer to the example below:

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

How to configure rules

All of the rules are stored in one file which named conf/apisix.yaml, APISIX checks if this file has any change every second. If the file is changed & it ends with #END, APISIX loads the rules from this file and updates its memory.

Here is a mini example:

  1. routes:
  2.   -
  3.     uri: /hello
  4.     upstream:
  5.         nodes:
  6.             "127.0.0.1:1980": 1
  7.         type: roundrobin
  8. #END

WARNING: APISIX will not load the rules into memory from file conf/apisix.yaml if there is no #END at the end.

How to configure Router

Single Router：

  1. routes:
  2.   -
  3.     uri: /hello
  4.     upstream:
  5.         nodes:
  6.             "127.0.0.1:1980": 1
  7.         type: roundrobin
  8. #END

Multiple Router：

  1. routes:
  2.   -
  3.     uri: /hello
  4.     upstream:
  5.         nodes:
  6.             "127.0.0.1:1980": 1
  7.         type: roundrobin
  8.   -
  9.     uri: /hello2
  10.     upstream:
  11.         nodes:
  12.             "127.0.0.1:1981": 1
  13.         type: roundrobin
  14. #END

How to configure Router + Service

  1. routes:
  2.     -
  3.         uri: /hello
  4.         service_id: 1
  5. services:
  6.     -
  7.         id: 1
  8.         upstream:
  9.             nodes:
  10.                 "127.0.0.1:1980": 1
  11.             type: roundrobin
  12. #END

How to configure Router + Upstream

  1. routes:
  2.     -
  3.         uri: /hello
  4.         upstream_id: 1
  5. upstreams:
  6.     -
  7.         id: 1
  8.         nodes:
  9.             "127.0.0.1:1980": 1
  10.         type: roundrobin
  11. #END

How to configure Router + Service + Upstream

  1. routes:
  2.     -
  3.         uri: /hello
  4.         service_id: 1
  5. services:
  6.     -
  7.         id: 1
  8.         upstream_id: 2
  9. upstreams:
  10.     -
  11.         id: 2
  12.         nodes:
  13.             "127.0.0.1:1980": 1
  14.         type: roundrobin
  15. #END

How to configure Plugins

  1. # plugins listed here will be hot reloaded and override the boot configuration
  2. plugins:
  3.   - name: ip-restriction
  4.   - name: jwt-auth
  5.   - name: mqtt-proxy
  6.     stream: true # set 'stream' to true for stream plugins
  7. #END

How to enable SSL

  1. ssls:
  2.     -
  3.         cert: |
  4.             -----BEGIN CERTIFICATE-----
  5.             MIIDrzCCApegAwIBAgIJAI3Meu/gJVTLMA0GCSqGSIb3DQEBCwUAMG4xCzAJBgNV
  6.             BAYTAkNOMREwDwYDVQQIDAhaaGVqaWFuZzERMA8GA1UEBwwISGFuZ3pob3UxDTAL
  7.             BgNVBAoMBHRlc3QxDTALBgNVBAsMBHRlc3QxGzAZBgNVBAMMEmV0Y2QuY2x1c3Rl
  8.             ci5sb2NhbDAeFw0yMDEwMjgwMzMzMDJaFw0yMTEwMjgwMzMzMDJaMG4xCzAJBgNV
  9.             BAYTAkNOMREwDwYDVQQIDAhaaGVqaWFuZzERMA8GA1UEBwwISGFuZ3pob3UxDTAL
  10.             BgNVBAoMBHRlc3QxDTALBgNVBAsMBHRlc3QxGzAZBgNVBAMMEmV0Y2QuY2x1c3Rl
  11.             ci5sb2NhbDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJ/qwxCR7g5S
  12.             s9+VleopkLi5pAszEkHYOBpwF/hDeRdxU0I0e1zZTdTlwwPy2vf8m3kwoq6fmNCt
  13.             tdUUXh5Wvgi/2OA8HBBzaQFQL1Av9qWwyES5cx6p0ZBwIrcXQIsl1XfNSUpQNTSS
  14.             D44TGduXUIdeshukPvMvLWLezynf2/WlgVh/haWtDG99r/Gj3uBdjl0m/xGvKvIv
  15.             NFy6EdgG9fkwcIalutjrUnGl9moGjwKYu4eXW2Zt5el0d1AHXUsqK4voe0p+U2Nz
  16.             quDmvxteXWdlsz8o5kQT6a4DUtWhpPIfNj9oZfPRs3LhBFQ74N70kVxMOCdec1lU
  17.             bnFzLIMGlz0CAwEAAaNQME4wHQYDVR0OBBYEFFHeljijrr+SPxlH5fjHRPcC7bv2
  18.             MB8GA1UdIwQYMBaAFFHeljijrr+SPxlH5fjHRPcC7bv2MAwGA1UdEwQFMAMBAf8w
  19.             DQYJKoZIhvcNAQELBQADggEBAG6NNTK7sl9nJxeewVuogCdMtkcdnx9onGtCOeiQ
  20.             qvh5Xwn9akZtoLMVEdceU0ihO4wILlcom3OqHs9WOd6VbgW5a19Thh2toxKidHz5
  21.             rAaBMyZsQbFb6+vFshZwoCtOLZI/eIZfUUMFqMXlEPrKru1nSddNdai2+zi5rEnM
  22.             HCot43+3XYuqkvWlOjoi9cP+C4epFYrxpykVbcrtbd7TK+wZNiK3xtDPnVzjdNWL
  23.             geAEl9xrrk0ss4nO/EreTQgS46gVU+tLC+b23m2dU7dcKZ7RDoiA9bdVc4a2IsaS
  24.             2MvLL4NZ2nUh8hAEHiLtGMAV3C6xNbEyM07hEpDW6vk6tqk=
  25.             -----END CERTIFICATE-----
  26.         key: |
  27.             -----BEGIN PRIVATE KEY-----
  28.             MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCf6sMQke4OUrPf
  29.             lZXqKZC4uaQLMxJB2DgacBf4Q3kXcVNCNHtc2U3U5cMD8tr3/Jt5MKKun5jQrbXV
  30.             FF4eVr4Iv9jgPBwQc2kBUC9QL/alsMhEuXMeqdGQcCK3F0CLJdV3zUlKUDU0kg+O
  31.             Exnbl1CHXrIbpD7zLy1i3s8p39v1pYFYf4WlrQxvfa/xo97gXY5dJv8RryryLzRc
  32.             uhHYBvX5MHCGpbrY61JxpfZqBo8CmLuHl1tmbeXpdHdQB11LKiuL6HtKflNjc6rg
  33.             5r8bXl1nZbM/KOZEE+muA1LVoaTyHzY/aGXz0bNy4QRUO+De9JFcTDgnXnNZVG5x
  34.             cyyDBpc9AgMBAAECggEAatcEtehZPJaCeClPPF/Cwbe9YoIfe4BCk186lHI3z7K1
  35.             5nB7zt+bwVY0AUpagv3wvXoB5lrYVOsJpa9y5iAb3GqYMc/XDCKfD/KLea5hwfcn
  36.             BctEn0LjsPVKLDrLs2t2gBDWG2EU+udunwQh7XTdp2Nb6V3FdOGbGAg2LgrSwP1g
  37.             0r4z14F70oWGYyTQ5N8UGuyryVrzQH525OYl38Yt7R6zJ/44FVi/2TvdfHM5ss39
  38.             SXWi00Q30fzaBEf4AdHVwVCRKctwSbrIOyM53kiScFDmBGRblCWOxXbiFV+d3bjX
  39.             gf2zxs7QYZrFOzOO7kLtHGua4itEB02497v+1oKDwQKBgQDOBvCVGRe2WpItOLnj
  40.             SF8iz7Sm+jJGQz0D9FhWyGPvrN7IXGrsXavA1kKRz22dsU8xdKk0yciOB13Wb5y6
  41.             yLsr/fPBjAhPb4h543VHFjpAQcxpsH51DE0b2oYOWMmz+rXGB5Jy8EkP7Q4njIsc
  42.             2wLod1dps8OT8zFx1jX3Us6iUQKBgQDGtKkfsvWi3HkwjFTR+/Y0oMz7bSruE5Z8
  43.             g0VOHPkSr4XiYgLpQxjbNjq8fwsa/jTt1B57+By4xLpZYD0BTFuf5po+igSZhH8s
  44.             QS5XnUnbM7d6Xr/da7ZkhSmUbEaMeHONSIVpYNgtRo4bB9Mh0l1HWdoevw/w5Ryt
  45.             L/OQiPhfLQKBgQCh1iG1fPh7bbnVe/HI71iL58xoPbCwMLEFIjMiOFcINirqCG6V
  46.             LR91Ytj34JCihl1G4/TmWnsH1hGIGDRtJLCiZeHL70u32kzCMkI1jOhFAWqoutMa
  47.             7obDkmwraONIVW/kFp6bWtSJhhTQTD4adI9cPCKWDXdcCHSWj0Xk+U8HgQKBgBng
  48.             t1HYhaLzIZlP/U/nh3XtJyTrX7bnuCZ5FhKJNWrYjxAfgY+NXHRYCKg5x2F5j70V
  49.             be7pLhxmCnrPTMKZhik56AaTBOxVVBaYWoewhUjV4GRAaK5Wc8d9jB+3RizPFwVk
  50.             V3OU2DJ1SNZ+W2HBOsKrEfwFF/dgby6i2w6MuAP1AoGBAIxvxUygeT/6P0fHN22P
  51.             zAHFI4v2925wYdb7H//D8DIADyBwv18N6YH8uH7L+USZN7e4p2k8MGGyvTXeC6aX
  52.             IeVtU6fH57Ddn59VPbF20m8RCSkmBvSdcbyBmqlZSBE+fKwCliKl6u/GH0BNAWKz
  53.             r8yiEiskqRmy7P7MY9hDmEbG
  54.             -----END PRIVATE KEY-----
  55.         snis:
  56.             - "yourdomain.com"
  57. #END

How to configure global rule

  1. global_rules:
  2.     -
  3.         id: 1
  4.         plugins:
  5.             response-rewrite:
  6.                 body: "hello\n"
  7. #END

How to configure consumer

  1. consumers:
  2.   - username: jwt
  3.     plugins:
  4.         jwt-auth:
  5.             key: user-key
  6.             secret: my-secret-key
  7. #END

How to configure plugin metadata

  1. upstreams:
  2.   - id: 1
  3.     nodes:
  4.       "127.0.0.1:1980": 1
  5.     type: roundrobin
  6. routes:
  7.   -
  8.     uri: /hello
  9.     upstream_id: 1
  10.     plugins:
  11.         http-logger:
  12.             batch_max_size: 1
  13.             uri: http://127.0.0.1:1980/log
  14. plugin_metadata:
  15.   - id: http-logger # note the id is the plugin name
  16.     log_format:
  17.         host: "$host",
  18.         remote_addr: "$remote_addr"
  19. #END

How to configure stream route

  1. stream_routes:
  2.   - server_addr: 127.0.0.1
  3.     server_port: 1985
  4.     id: 1
  5.     upstream_id: 1
  6.     plugins:
  7.       mqtt-proxy:
  8.         protocol_name: "MQTT"
  9.         protocol_level: 4
  10. upstreams:
  11.   - nodes:
  12.       "127.0.0.1:1995": 1
  13.     type: roundrobin
  14.     id: 1
  15. #END