配置示例

APISIX Ingress Controller 支持 Ingress 资源和 Gateway API 用于 Kubernetes 中的流量管理。虽然两者都受支持，但 Gateway API 提供了更高的灵活性和可扩展性。建议新用户在未来的部署中采用 Gateway API。

除了这些标准的 Kubernetes API 之外，APISIX Ingress Controller 还支持一组专为 APISIX 原生功能设计的 CRD（自定义资源定义）。

本文档提供了常见配置的示例，涵盖了如何以及何时使用这些资源。你应该根据你的环境调整自定义值，例如命名空间、路由 URI 和凭证。

备注

目前，APISIX Ingress Controller 和 API7 Ingress Controller 在功能上没有差异，尽管它们的发布计划可能不同。

配置控制面端点和管理员密钥

要在运行时更新 APISIX Ingress Controller 与控制面之间的连接控制面端点和管理员密钥：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: ingress-apisix
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
      - http://127.0.0.1:9180
      auth:
        type: AdminKey
        adminKey:
          value: replace-with-your-admin-key # 替换为你的管理员密钥

定义 Ingress Controller 和网关

在应用进一步配置之前，指定负责处理资源的 Ingress Controller：

Gateway API
Ingress
APISIX CRD

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: apisix
spec:
  // Annotate 1
  controllerName: "apisix.apache.org/apisix-ingress-controller"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  namespace: ingress-apisix
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      // Annotate 2
      group: apisix.apache.org
      // Annotate 3
      kind: GatewayProxy
      // Annotate 4
      name: apisix-config

❶ 如果在同一个集群中运行多个不同的 APISIX Ingress Controller 实例（而不是具有多个副本的单个实例），则应自定义 Controller 名称。每个 Ingress Controller 实例必须在其配置文件中使用唯一的 controllerName，并且相应的 GatewayClass 应引用该值。

❷ 被引用资源的 API 组。

❸ 被引用资源的种类。

❹ 被引用资源的名称。应与 GatewayProxy 资源的 metadata.name 匹配。

备注

Gateway 监听器中的 port 是必需的但会被忽略。这是由于数据平面的限制：它无法动态打开新端口。由于 Ingress Controller 不管理数据平面部署，因此它无法自动更新配置或重启数据平面以应用端口更改。

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apisix
spec:
  // Annotate 1
  controller: apisix.apache.org/apisix-ingress-controller
  parameters:
    // Annotate 2
    apiGroup: apisix.apache.org
    // Annotate 3
    kind: GatewayProxy
    // Annotate 4
    name: apisix-config
    // Annotate 5
    namespace: ingress-apisix
    // Annotate 6
    scope: Namespace

❶ 如果在同一个集群中运行多个不同的 APISIX Ingress Controller 实例（而不是具有多个副本的单个实例），则应自定义 Controller 名称。每个 Ingress Controller 实例必须在其配置文件中使用唯一的 controllerName，并且相应的 IngressClass 应引用该值。

❷ 被引用资源的 API 组。

❸ 被引用资源的种类。

❹ 被引用资源的名称。应与 GatewayProxy 资源的 metadata.name 匹配。

❺ 定义被引用资源的命名空间。

❻ 被引用资源的作用域。

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apisix
spec:
  // Annotate 1
  controller: apisix.apache.org/apisix-ingress-controller
  parameters:
    // Annotate 2
    apiGroup: apisix.apache.org
    // Annotate 3
    kind: GatewayProxy
    // Annotate 4
    name: apisix-config
    // Annotate 5
    namespace: ingress-apisix
    // Annotate 6
    scope: Namespace

❷ 被引用资源的 API 组。

❸ 被引用资源的种类。

❹ 被引用资源的名称。应与 GatewayProxy 资源的 metadata.name 匹配。

❺ 定义被引用资源的命名空间。

❻ 被引用资源的作用域。

路由到 Kubernetes 服务

创建一条路由，将请求代理到 Kubernetes 上的服务：

Gateway API
Ingress
APISIX CRD

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin
      port: 80

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /ip
        pathType: Exact
        backend:
          service:
            name: httpbin
            port:
              number: 80

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  ingressClassName: apisix
  http:
  - name: httpbin
    match:
      paths:
      - /ip
    backends:
    - serviceName: httpbin
      servicePort: 80

路由到外部服务

创建一条路由，将请求代理到公共托管的服务：

Gateway API
Ingress
APISIX CRD

apiVersion: v1
kind: Service
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: get-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin-external-domain
      port: 80

apiVersion: v1
kind: Service
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: ingress-apisix
  name: get-ip
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /ip
        pathType: Exact
        backend:
          service:
            name: httpbin-external-domain
            port:
              number: 80

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: get-ip
spec:
  ingressClassName: apisix
  http:
    - name: get-ip
      match:
        paths:
          - /ip
      upstreams:
      - name: httpbin-external-domain

配置带权重的服务

创建一条路由，按权重将流量代理到上游服务：

Gateway API
APISIX CRD

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /ip
    backendRefs:
    - name: httpbin-1
      port: 80
      weight: 3
    - name: httpbin-2
      port: 80
      weight: 7

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  ingressClassName: apisix
  http:
  - name: httpbin
    match:
      paths:
      - /ip
    backends:
    - serviceName: httpbin-1
      servicePort: 80
      weight: 3
    - serviceName: httpbin-2
      servicePort: 80
      weight: 7

Ingress 资源不支持此配置。

配置上游

配置上游相关设置，包括负载均衡算法、如何将 Host 标头传递给上游、服务超时等：

Gateway API
APISIX CRD

apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  targetRefs:
  - name: httpbin
    kind: Service
    group: ""
  timeout:
    send: 10s
    read: 10s
    connect: 10s
  scheme: http
  retries: 10
  loadbalancer:
    type: roundrobin
  passHost: rewrite
  upstreamHost: httpbin.example.com

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  ingressClassName: apisix
  timeout:
    send: 10s
    read: 10s
    connect: 10s
  scheme: http
  retries: 10
  loadbalancer:
    type: roundrobin
  passHost: rewrite
  upstreamHost: httpbin.example.com

使用 appProtocol 检测上游协议

Service 端口上的 appProtocol 字段告知 APISIX 如何与后端通信。 APISIX 会根据此值自动配置上游协议方案。如果未设置，默认方案为 http。

APISIX Ingress Controller 支持 Service 端口的以下 appProtocol 值：

值	描述
`http`	将上游协议方案设置为 `http`。
`https`	将上游协议方案设置为 `https`。
`kubernetes.io/ws`	将上游协议方案设置为 `http`，并在路由上设置 `enable_websocket` 为 `true`。
`kubernetes.io/wss`	将上游协议方案设置为 `https`，并在路由上设置 `enable_websocket` 为 `true`。

以下是一个 Service 配置示例，为 HTTP 和 HTTPS 端口设置了 appProtocol 值：

apiVersion: v1
kind: Service
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  selector:
    app: httpbin
  ports:
    - name: http
      port: 80
      targetPort: 80
      appProtocol: http
    - name: https
      port: 443
      targetPort: 443
      appProtocol: https

然后，你可以创建一条指向该 Service 端口的路由，让 APISIX 自动检测上游协议。使用以下配置，APISIX 会自动将上游协议方案设置为 https：

Gateway API
Ingress
APISIX CRD

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: httpbin-route
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /anything
    backendRefs:
    - name: httpbin
      port: 443

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: ingress-apisix
  name: httpbin-route
spec:
  ingressClassName: apisix
  rules:
    - http:
        paths:
          - path: /anything
            pathType: Exact
            backend:
              service:
                name: httpbin
                port:
                  number: 443

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: httpbin-route
spec:
  ingressClassName: apisix
  http:
  - name: httpbin-route
    match:
      paths:
      - /anything
    backends:
    - serviceName: httpbin
      servicePort: 443

配置消费者和凭证

Gateway API
APISIX CRD

直接在消费者上创建消费者并配置认证凭证：

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: ingress-apisix
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: primary-key
      config:
        key: alice-primary-key # 替换为你的密钥

你也可以使用 Secret 资源，其中凭证应进行 base64 编码：

apiVersion: v1
kind: Secret
metadata:
  namespace: ingress-apisix
  name: key-auth-primary
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk= # alice-primary-key 的 base64 编码
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: ingress-apisix
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth-primary
      secretRef:
        name: key-auth-primary

直接在消费者上创建消费者并配置认证凭证：

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: ingress-apisix
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: alice-primary-key # 替换为你的密钥

你也可以使用 Secret 资源，其中凭证应进行 base64 编码：

apiVersion: v1
kind: Secret
metadata:
  namespace: ingress-apisix
  name: key-auth-primary
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk= # alice-primary-key 的 base64 编码
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: ingress-apisix
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      secretRef:
        name: key-auth-primary

在消费者上配置插件

在消费者上配置插件，例如限流插件：

Gateway API
APISIX CRD

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: ingress-apisix
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: alice-key
      config:
        key: alice-key # 替换为你的密钥
  plugins:
    - name: limit-count
      config:
        count: 3
        time_window: 60
        key: remote_addr
        key_type: var
        policy: local
        rejected_code: 429
        rejected_msg: Too many requests # 请求过多
        show_limit_quota_header: true
        allow_degradation: false

配置路由优先级和匹配条件

在目标路由上配置路由优先级和请求匹配条件：

Gateway API
APISIX CRD

apiVersion: apisix.apache.org/v1alpha1
kind: HTTPRoutePolicy
metadata:
  namespace: ingress-apisix
  name: http-route-policy
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
  priority: 10
  vars:
  - - http_x_test_name
    - ==
    - new_name
  - - arg_test
    - ==
    - test_name

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  ingressClassName: apisix
  http:
  - name: httpbin
    match:
      paths:
      - /*
      exprs:
      - subject:
          scope: Header
          name: X-Test-Name
        op: Equal
        value: new_name
      - subject:
          scope: Query
          name: test
        op: Equal
        value: test_name
    priority: 10
    backends:
    - serviceName: httpbin
      servicePort: 80

在路由上配置插件

在路由上配置插件：

Gateway API
APISIX CRD

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: ingress-apisix
  name: auth-plugin-config
spec:
  plugins:
    - name: key-auth
      config:
        _meta:
          disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: get-ip
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches: 
    - path:
        type: Exact
        value: /ip
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: auth-plugin-config
    backendRefs:
    - name: httpbin
      port: 80

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: get-ip
spec:
  ingressClassName: apisix
  http:
    - name: get-ip
      match:
        paths:
          - /ip
      plugins:
      - name: limit-count
        enable: true
        config:
          count: 2
          time_window: 10
          rejected_code: 429
      backends:
      - serviceName: httpbin
        servicePort: 80

配置全局插件

配置全局插件：

Gateway API
APISIX CRD

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: ingress-apisix
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # 在此处添加你的控制面连接配置
      # ...
  plugins:
  - name: clickhouse-logger
    config:
      endpoint_addr: http://clickhouse-clickhouse-installation.apisix.svc.cluster.local:8123
      user: quickstart-user # 替换为你的用户名
      password: quickstart-pass # 替换为你的密码
      logtable: test
      database: quickstart_db

apiVersion: apisix.apache.org/v2
kind: ApisixGlobalRule
metadata:
  namespace: ingress-apisix
  name: apisix-global-rule-logging
spec:
  ingressClassName: apisix
  plugins:
  - name: clickhouse-logger
    enable: true
    config:
      endpoint_addr: http://clickhouse-clickhouse-installation.apisix.svc.cluster.local:8123
      user: quickstart-user # 替换为你的用户名
      password: quickstart-pass # 替换为你的密码
      logtable: test
      database: quickstart_db

配置插件元数据

配置插件元数据：

Gateway API
APISIX CRD

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: ingress-apisix
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # 在此处添加你的控制面连接配置
      # ...
  pluginMetadata:
    opentelemetry: {
      "trace_id_source": "x-request-id",
      "resource": {
        "service.name": "APISIX"
      },
      "collector": {
        "address": "simplest-collector:4318",
        "request_timeout": 3,
        "request_headers": {
          "Authorization": "token"
        }
      },
      "batch_span_processor": {
        "drop_on_queue_full": false,
        "max_queue_size": 1024,
        "batch_timeout": 2,
        "inactive_timeout": 1,
        "max_export_batch_size": 16
      },
      "set_ngx_var": true
    }

配置插件配置

创建插件配置并在路由中引用它：

Gateway API
APISIX CRD

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: ingress-apisix
  name: example-plugin-config
spec:
  plugins:
  - name: response-rewrite
    enable: true
    config:
      headers:
        X-Plugin-Config: "example-response-rewrite"
        X-Plugin-Test: "enabled"
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches: 
    - path:
        type: Exact
        value: /ip
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: example-plugin-config
    backendRefs:
    - name: httpbin
      port: 80

apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
  namespace: ingress-apisix
  name: example-plugin-config
spec:
  ingressClassName: apisix
  plugins:
  - name: response-rewrite
    enable: true
    config:
      headers:
        X-Plugin-Config: "example-response-rewrite"
        X-Plugin-Test: "enabled"
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: httpbin
spec:
  ingressClassName: apisix
  http:
  - name: get-ip
    match:
      paths:
      - /ip
    backends:
    - serviceName: httpbin
      servicePort: 80
    plugin_config_name: example-plugin-config

配置网关访问信息

这些配置允许 Ingress Controller 用户访问网关。

Gateway API
Ingress
APISIX CRD

配置 statusAddress：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: ingress-apisix
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # 在此处添加你的控制面连接配置
      # ...
  statusAddress:
    - 10.24.87.13

如果你使用的是 Ingress 资源，可以配置 statusAddress 或 publishService。

配置 statusAddress：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: ingress-apisix
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # 在此处添加你的控制面连接配置
      # ...
  statusAddress:
    - 10.24.87.13

配置 publishService：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: ingress-apisix
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # 在此处添加你的控制面连接配置
      # ...
  publishService: apisix-gateway

使用 publishService 时，请确保你的网关 Service 类型为 LoadBalancer，以便能够填充地址。Ingress Controller 将使用此 Service 的端点来更新 Ingress 资源的状态信息。格式可以是 命名空间/服务名称，如果默认命名空间设置正确，也可以仅使用 服务名称。

配置控制面端点和管理员密钥​

定义 Ingress Controller 和网关​

路由到 Kubernetes 服务​

路由到外部服务​

配置带权重的服务​

配置上游​

使用 appProtocol 检测上游协议​

配置消费者和凭证​

在消费者上配置插件​

配置路由优先级和匹配条件​

在路由上配置插件​

配置全局插件​

配置插件元数据​

配置插件配置​

配置网关访问信息​

配置控制面端点和管理员密钥

定义 Ingress Controller 和网关

路由到 Kubernetes 服务

路由到外部服务

配置带权重的服务

配置上游

使用 appProtocol 检测上游协议

配置消费者和凭证

在消费者上配置插件

配置路由优先级和匹配条件

在路由上配置插件

配置全局插件

配置插件元数据

配置插件配置

配置网关访问信息