apisix/docs/en/latest/control-api.md

title
Control API

The control API can be used to

• expose APISIX internal state
• control the behavior of a single isolate APISIX data panel

By default, the control API server is enabled and listens to 127.0.0.1:9090. You can change it via the control section under apisix in conf/config.yaml:

apisix:
  ...
  enable_control: true
  control:
    ip: "127.0.0.1"
    port: 9090

Note that the control API server should not be configured to listen to the public traffic!

Control API Added via plugin

Plugin can add its control API when it is enabled. If a plugin adds such a control API, please refer to each plugin's documentation for those APIs.

Plugin independent Control API

Here is the supported API:

GET /v1/schema

Introduced since v2.2.

Return the jsonschema used by this APISIX instance in the format below:

{
    "main": {
        "route": {
            "properties": {...}
        },
        "upstream": {
            "properties": {...}
        },
        ...
    },
    "plugins": {
        "example-plugin": {
            "consumer_schema": {...},
            "metadata_schema": {...},
            "schema": {...},
            "type": ...,
            "priority": 0,
            "version": 0.1
        },
        ...
    }
}

For plugins part, only enabled plugins will be returned. Some plugins may lack of fields like consumer_schema or type, it is depended on by the plugin's definition.

GET /v1/healthcheck

Introduced since v2.3.

Return current health check status in the format below:

[
    {
        "healthy_nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            }
        ],
        "name": "upstream#/upstreams/1",
        "nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            },
            {
                "host": "127.0.0.2",
                "port": 1988,
                "priority": 0,
                "weight": 1
            }
        ],
        "src_id": "1",
        "src_type": "upstreams"
    },
    {
        "healthy_nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            }
        ],
        "name": "upstream#/routes/1",
        "nodes": [
            {
                "host": "127.0.0.1",
                "port": 1980,
                "priority": 0,
                "weight": 1
            },
            {
                "host": "127.0.0.1",
                "port": 1988,
                "priority": 0,
                "weight": 1
            }
        ],
        "src_id": "1",
        "src_type": "routes"
    }
]

Each entry contains fields below:

• src_type: where the health checker comes from. The value is one of ["routes", "services", "upstreams"].
• src_id: the id of object which creates the health checker. For example, if Upstream object with id 1 creates a health checker, the src_type is upstreams and the src_id is 1.
• name: the name of the health checker.
• nodes: the target nodes of the health checker.
• healthy_nodes: the healthy node known by the health checker.

User can also use /v1/healthcheck/$src_type/$src_id can get the status of a health checker.

For example, GET /v1/healthcheck/upstreams/1 returns:

{
    "healthy_nodes": [
        {
            "host": "127.0.0.1",
            "port": 1980,
            "priority": 0,
            "weight": 1
        }
    ],
    "name": "upstream#/upstreams/1",
    "nodes": [
        {
            "host": "127.0.0.1",
            "port": 1980,
            "priority": 0,
            "weight": 1
        },
        {
            "host": "127.0.0.2",
            "port": 1988,
            "priority": 0,
            "weight": 1
        }
    ],
    "src_id": "1",
    "src_type": "upstreams"
}