APISIX etcd configurations

apisix-etcd.md

APISIX etcd configurations

APISIX

• URL: https://github.com/apache/apisix
• Version: v2.14.1

Config file

Default config file: config-default.yaml

apisix:
  config_center: etcd  # use etcd to store the config value

etcd:
  prefix: /apisix  # apisix configurations prefix

The above default configurations can be overrided by the user config file: config.yaml

etcd configurations

Prefix: /apisix (as specified above)

Directories: (see apisix/constants.lua)

• /consumers
• /global_rules
• /plugins
• /plugin_configs
• /plugin_metadata
• /proto
• /routes
• /services
• /ssl
• /stream_routes
• /upstreams

The above etcd structure can be initialized by the apisix start command, which would execute the init_etcd subcommand.

After the initialization, the above etcd directories would have an initial value of init_dir. (see apisix/cli/etcd.lua)

Global rules

Key: /global_rules/<id>

Value:

{
  "id": "<id>",
  "create_time": <create_timestamp>,
  "update_time": <update_timestamp>,
  "plugins": {
    "<name>": {
      "<config>": <value>,
      ...
    },
    ...
  }
}

Plugin require-id

{
  "id": "1",
  "create_time": 1658975221,
  "update_time": 1658975221,
  "plugins": {
    "request-id": { "disable": false }
  }
}

Consumers

Key: /consumers/<name>

Value:

{
  "username": "<name>",
  "desc": "<description>",
  "plugins": {
    "<name>": {
      "<config>": <value>,
      ...
    },
    ...
  },
  "create_time": 1658978213,
  "update_time": 1658980592
}

• <name>: the unique name to identify the consumer
• plugins: configure the plugins associated with the consumer

Upstreams

Key: /upstreams/<id>

Value:

{
  "id": "<id>",
  "name": "<name>",
  "desc": "<description>",
  "create_time": 1658976786,
  "update_time": 1658976786,
  "nodes": {
    "<address>:<port>": 1,
    ...
  },
  "retries": 2,
  "timeout": {
    "connect": 6,
    "send": 6,
    "read": 6
  },
  "type": "roundrobin",
  "scheme": "http",
  "pass_host": "pass",
  "keepalive_pool": {
    "idle_timeout": 60,
    "requests": 1000,
    "size": 320
  },
  "retry_timeout": 3
}

Services

Key: /services/<id>

Value:

{
  "id": "<id>",
  "name": "<name>",
  "desc": "<description>",
  "create_time": 1658993149,
  "update_time": 1658993149,
  "upstream_id": "<upstream_id>",
  "plugins": {
    "<name>": {
      "<config>": <value>,
      ...
    },
    ...
  },
  "hosts": [
    "test.example.com",
    "another.example.com"
  ]
}

• upstream_id: refer to the previously added upstream, match the ID at /upstreams/<id>

Routes

Key: /routes/<id>

Value: (standalone example)

{
  "id": "<id>",
  "name": "<name>",
  "desc": "<description>",
  "create_time": 1658976629,
  "update_time": 1658976629,
  "uri": "/*",
  "methods": [
    "GET",
    "POST",
    "PUT",
    "DELETE",
    "PATCH",
    "HEAD",
    "OPTIONS",
    "CONNECT",
    "TRACE"
  ],
  "host": "test.example.com",
  "remote_addr": "10.0.0.0/8",
  "plugins": {
    "<name>": {
      "<config>": <value>,
      ...
    },
    ...
  },
  "upstream": {
    "nodes": {
      "<address>:<port>": 1,
      ...
    },
    "retries": 2,
    "timeout": {
      "connect": 6,
      "send": 6,
      "read": 6
    },
    "type": "roundrobin",
    "scheme": "http",
    "pass_host": "pass",
    "keepalive_pool": {
      "idle_timeout": 60,
      "requests": 1000,
      "size": 320
    },
    "retry_timeout": 3
  },
  "labels": {
    "API_VERSION": "<version>",
    "label1": "value1",
    "label2": "value2",
    "xxx": "yyy"
  },
  "enable_websocket": true,
  "status": 1
}

With multiple hosts and remote addresses:

{
  ...
  "hosts": [
    "test.example.com",
    "another.example.com"
  ],
  "remote_addrs": [
    "10.0.0.0/8",
    "127.0.0.0/8"
  ],
  ...
}

Use a service:

{
  "id": "418542649352390249",
  "create_time": 1659000459,
  "update_time": 1659000459,
  "uri": "<uri>",
  "name": "<name>",
  "desc": "<description>",
  "methods": [
    "GET",
    "POST",
    "PUT",
    "DELETE",
    "PATCH",
    "HEAD",
    "OPTIONS",
    "CONNECT",
    "TRACE"
  ],
  "host": "www.example.com",
  "plugins": {
    "redirect": {
      "http_to_https": true
    },
    ...
  },
  "service_id": "<service_id>",
  "labels": {
    "API_VERSION": "<version>",
    ...
  },
  "enable_websocket": true,
  "status": 1
}

• service_id: refer to the previously added service, match the ID at /services/<id>

Plugin configurations

Plugin data

Plugin server-info

Write the following data to etcd:

Key: /data_plane/server_info/<id>

Value:

{
  "etcd_version": "3.5.0",
  "hostname": "<hostname>",
  "boot_time": 1658920797,
  "id": "<id>",
  "version": "2.14.1"
}

• <id>: the auto-generated instance ID (UUID-format)
• <hostname>: the hostname where APISIX runs on
• boot_time: the start time of APISIX (seconds since UNIX epoch)