跳到主要内容

API 驱动的独立模式

API 驱动的独立模式 是 APISIX 独立部署模式的最新补充。在此模式下，路由规则完全存储在内存中，而不是配置文件中。所有更新必须通过专用的独立 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 白名单。

获取所有配置​

要获取所有配置：

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,
  "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 "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 "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。

更新资源​

在 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 "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 "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 "Content-Type: application/json" \
  -d '{}'

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

验证配置​

使用/apisix/admin/configs/validate端点验证一个完整的独立配置有效载荷而不应用它:

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" \
  -d '
    {
      "routes": [
        {
          "id": "getting-started-ip",
          "uri": "/ip",
          "upstream": {
            "type": "roundrobin",
            "nodes": {
              "httpbin.org:80": 1
            }
          }
        }
      ]
    }'

如果配置有效, 您应该收到HTTP/1.1 200 OK响应 。