API 驱动的独立模式

API 驱动的独立模式将路由配置存储在内存中，而不是配置文件中。控制器向专用的独立 Admin API 发送完整配置快照，工作进程无需重启网关即可加载已接受的更新。接受更新并不表示所有工作进程都已应用该更新；有限时长的等待可以确认本地工作进程的同步状态。

警告

此功能专为 APISIX Ingress Controller 设计，主要用于与 ADC 集成。APISIX 提供官方的、端到端的、无状态的 Ingress Controller 实现。除非你完全了解其内部工作原理和行为，否则不要直接使用此功能。

本文档提供了在 API 驱动的独立模式下使用 APISIX 的一些示例。要了解有关可用配置选项的更多信息，请参阅 Admin API 参考（但不要使用这些端点）。这些配置选项可以转换为 JSON 或 YAML，以便在 API 驱动的独立模式下使用。

示例

在 API 驱动的独立模式下，你将使用 /apisix/admin/configs API，而不是传统模式的 Admin API 端点。该 API 接受 JSON 和 YAML 输入。

独立模式 Admin API 具有与 config.yaml 中配置的传统模式 Admin API 相同的安全要求，包括 API 密钥、(m)TLS、CORS 和 IP 白名单。

每个 PUT 请求都必须包含 X-Digest 请求头。该标识符由客户端选择，并且预期配置发生变化时必须更改。APISIX 比较的是此标识符，而不是服务器根据请求正文计算的哈希值。重复使用当前 digest 会直接返回 204 No Content，不会应用新的请求正文，即使正文内容不同。

每次更新都是完整快照，而不是资源补丁。除非显式保留某种资源类型的配置版本，否则快照中省略的资源会被删除。应用前请验证完整文档，并保留最近一次可用的快照，以便控制器在重启或发布失败后恢复配置。

获取所有配置

要获取所有配置：

curl "http://127.0.0.1:9180/apisix/admin/configs" -H "X-API-KEY: ${ADMIN_API_KEY}"

如果你没有配置任何资源，你应该看到以下响应：

{
  "consumer_groups_conf_version": 0,
  "secrets_conf_version": 0,
  "global_rules_conf_version": 0,
  "upstreams_conf_version": 0,
  "ssls_conf_version": 0,
  "protos_conf_version": 0,
  "plugin_metadata_conf_version": 0,
  "routes_conf_version": 0,
  "stream_routes_conf_version": 0,
  "plugins_conf_version": 0,
  "services_conf_version": 0,
  "plugin_configs_conf_version": 0,
  "consumers_conf_version": 0
}

创建资源

例如，要创建一个路由：

curl -i -X PUT "http://127.0.0.1:9180/apisix/admin/configs" \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "X-Digest: getting-started-v1" \
  -H "Content-Type: application/json" \
  -d '
    {
      "routes": [
        {
          "id": "getting-started-ip",
          "uri": "/ip",
          "upstream": {
            "type": "roundrobin",
            "nodes": {
              "httpbin.org:80": 1
            }
          }
        }
      ]
    }'

或者，你也可以使用 YAML 输入：

curl -X PUT "http://127.0.0.1:9180/apisix/admin/configs" \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "X-Digest: getting-started-yaml-v1" \
  -H "Content-Type: application/yaml" \
  --data-binary @- <<EOF
routes:
  - id: getting-started-ip
    uri: /ip
    upstream:
      type: roundrobin
      nodes:
        "httpbin.org:80": 1
EOF

你应该收到 HTTP/1.1 202 Accepted 响应。

当你获取所有配置时，每个 *_conf_version 都已增加 1。响应还包含提交的 digest 和最后修改元数据。该操作读取的是已接受的快照，并不能证明所有工作进程上的流量都已经使用该快照。

验证配置

在应用带有限时等待的后续快照前，先创建包含完整预期配置的 apisix.json。例如：

apisix.json

{
  "routes": [
    {
      "id": "getting-started-ip",
      "uri": "/ip",
      "upstream": {
        "type": "roundrobin",
        "nodes": {
          "httpbin.org:80": 1
        }
      }
    }
  ]
}

验证文件但不应用配置：

curl -i -X POST "http://127.0.0.1:9180/apisix/admin/configs/validate" \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @apisix.json

如果配置有效，你应该收到 HTTP/1.1 200 OK 响应。验证不会更改配置版本或实时资源。有关支持的资源部分、请求限制、聚合错误和验证边界，请参阅 Admin API 参考中的 Schema 校验。

等待本地工作进程

在配置更新中添加 wait 查询参数，可以等待接收请求的 APISIX 实例上的工作进程。该值为毫秒单位的超时时间，上限为 60000。省略该参数或将其设置为零都不会等待。

验证成功后，使用新的 digest 提交快照，并等待五秒：

curl -i -X PUT "http://127.0.0.1:9180/apisix/admin/configs?wait=5000" \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "X-Digest: rollout-v2" \
  -H "Content-Type: application/json" \
  --data-binary @apisix.json

发送流量前，请根据状态码判断结果：

状态	含义
200 OK	所有本地工作进程都已针对其 HTTP 子系统和启用的流子系统所跟踪的资源类型报告本次提交的 digest。
202 Accepted	快照已接受，但请求未等待，或在确认同步前等待超时。工作进程之后仍可能应用该快照。
204 No Content	digest 已与存储的快照匹配，因此没有执行更新或同步等待。

超时不会回滚快照。不要将之后使用相同 digest 得到的 204 当作就绪检查。切换流量前，请验证具有代表性的请求并完成控制器的发布检查。本地 200 不代表配置已交付到其他 APISIX 实例，也不代表上游健康或应用流量成功。

更新资源

在 API 驱动模式下，APISIX 使用两个版本跟踪器来管理更新：

• *_conf_version：资源类型的配置版本。
• modifiedIndex：资源类型中资源的修改索引。

例如，具有相同 routes_conf_version 的路由可以具有不同的 modifiedIndex。

*_conf_version 和 modifiedIndex 的更新规则按以下逻辑评估：

假设你发送带有上游的路由更新，如下所示：

curl -X PUT "http://127.0.0.1:9180/apisix/admin/configs" \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "X-Digest: resources-v2000" \
  -H "Content-Type: application/json" \
  -d '
    {
      "routes_conf_version": 2000,
      "routes": [
        {
          "modifiedIndex": 1,
          "id": "ip",
          "uri": "/ip",
          "upstream_id": "u1"
        }
      ],
      "upstreams_conf_version": 2000,
      "upstreams": [
        {
          "modifiedIndex": 1,
          "id": "u1",
          "nodes": {
            "127.0.0.1:1980": 1,
            "127.0.0.1:2980": 1
          },
          "type": "roundrobin"
        }
      ]
    }'

当 获取所有配置 时，你应该看到类似以下的响应：

{
  "upstreams": [
    {
      "id": "u1",
      "type": "roundrobin",
      "modifiedIndex": 1,
      "nodes": {
        "127.0.0.1:2980": 1,
        "127.0.0.1:1980": 1
      }
    }
  ],
  "ssls_conf_version": 2,
  "upstreams_conf_version": 2000,
  "routes": [
    {
      "id": "ip",
      "upstream_id": "u1",
      "modifiedIndex": 1,
      "uri": "/ip"
    }
  ],
  "protos_conf_version": 2,
  "consumers_conf_version": 2,
  "services_conf_version": 2,
  "plugin_configs_conf_version": 2,
  "plugin_metadata_conf_version": 2,
  "consumer_groups_conf_version": 2,
  "secrets_conf_version": 2,
  "global_rules_conf_version": 2,
  "routes_conf_version": 2000
}

现在，如果你增加 upstreams_conf_version，更新上游的 modifiedIndex 和节点地址，更新路由 URI 并保持 routes_conf_version 不变：

curl -X PUT "http://127.0.0.1:9180/apisix/admin/configs" \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "X-Digest: resources-v2001" \
  -H "Content-Type: application/json" \
  -d '
    {
      "routes_conf_version": 2000,
      "routes": [
        {
          "modifiedIndex": 1,
          "id": "ip",
          "uri": "/new-ip",
          "upstream_id": "u1"
        }
      ],
      "upstreams_conf_version": 2001,
      "upstreams": [
        {
          "modifiedIndex": 5,
          "id": "u1",
          "nodes": {
            "127.0.0.1:1980": 1,
            "127.0.0.1:3980": 1
          },
          "type": "roundrobin"
        }
      ]
    }'

当 获取所有配置 时，你应该看到类似以下的响应，虽然路由配置未更改，但上游已更新：

{
  "upstreams": [
    {
      "id": "u1",
      "type": "roundrobin",
      "modifiedIndex": 5,
      "nodes": {
        "127.0.0.1:3980": 1,
        "127.0.0.1:1980": 1
      }
    }
  ],
  "services_conf_version": 3,
  "plugin_configs_conf_version": 3,
  "plugin_metadata_conf_version": 3,
  "consumer_groups_conf_version": 3,
  "secrets_conf_version": 3,
  "routes": [
    {
      "id": "ip",
      "uri": "/ip",
      "modifiedIndex": 1,
      "upstream_id": "u1"
    }
  ],
  "upstreams_conf_version": 2001,
  "routes_conf_version": 2000,
  "consumers_conf_version": 3,
  "ssls_conf_version": 3,
  "global_rules_conf_version": 3,
  "protos_conf_version": 3
}

清除所有资源

空快照会删除所有路由和插件资源。仅当你确实要停止提供已配置的流量时才执行此操作，并保留完整备份以供恢复：

curl -X PUT "http://127.0.0.1:9180/apisix/admin/configs" \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "X-Digest: clear-resources-v1" \
  -H "Content-Type: application/json" \
  -d '{}'

请注意，此操作不会重置 *_conf_version。它们将继续增加。