跳到主要内容
版本：3.10.x

配置示例

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

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

本文档提供了涵盖如何以及何时使用这些资源的常见配置示例。请确保将任何占位符值（例如命名空间、路由 URI 和凭证）替换为与你自己环境匹配的值。

备注

目前，APISIX Ingress Controller 和 API7 Ingress Controller 之间没有功能差异，尽管它们的发布时间表可能不同。

配置 CP 端点和 Admin Key​

要在运行时更新控制平面端点和 Admin Key 以实现 API7 Ingress Controller 与控制平面之间的连接：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: api7
  name: apisix-proxy-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
      - https://xxx.xxx.xxx.xxx:7443  # 替换为你的 CP 端点
      auth:
        type: AdminKey
        adminKey:
          value: xxxxxxxxxxx          # 替换为你的 admin key
important

同一网关组内的所有资源必须使用相同的 IngressClass（针对 Ingress / APISIX CRD）或 Gateway（针对 Gateway API），并且每个资源都指向同一个 GatewayProxy。

对于单个网关组，使用多个 GatewayProxy、IngressClass 或 Gateway 资源可能会导致冲突和意外的资源覆盖。

定义控制器和网关​

要在应用进一步配置之前指定负责处理资源的控制器：

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: apisix
spec:
  controllerName: "apisix.apache.org/apisix-ingress-controller"
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  namespace: api7
  name: apisix
spec:
  gatewayClassname: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-proxy-config

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

❷ 引用资源的 API 组。

❸ 引用资源的 Kind。

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

备注

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

路由到 K8s 服务​

要创建一个将请求代理到 K8s 上服务的路由：

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

路由到外部服务​

要创建一个将请求代理到公开托管服务的路由：

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

配置加权服务​

要创建一个按权重将流量代理到上游服务的路由：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: api7
  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

Ingress 资源不支持此配置。

配置上游​

要配置上游相关的配置，包括负载均衡算法、请求头如何传递到上游、服务超时等：

apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
  namespace: api7
  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

使用 appProtocol 探测上游协议​

Service 端口上的 appProtocol 字段告诉网关如何与后端进行通信。 上游 Scheme 将根据此值自动配置。如果未设置，则默认 Scheme 为 http。

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

值描述
http此选项将上游 Scheme 设置为 http。
https此选项将上游 Scheme 设置为 https。
kubernetes.io/ws此选项将上游 Scheme 设置为 http，并将路由上的 enable_websocket 设置为 true。
kubernetes.io/wss此选项将上游 Scheme 设置为 https，并将路由上的 enable_websocket 设置为 true。

以下是为 HTTP 和 HTTPS 端口配置了 appProtocol 值的 Service 示例：

apiVersion: v1
kind: Service
metadata:
  namespace: api7
  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 会自动将上游 Scheme 设置为 https：

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

配置端口级别的上游设置​

ApisixUpstream 中的 PortLevelSettings 允许你为每个端口定义特定于协议的配置。这对于在不同端口上公开多种协议，或需要端口级别定制（例如超时、负载均衡或 TLS 设置）的服务非常有用。

信息

仅 APISIX CRD 支持端口级别的设置。使用 Gateway API 时，上游配置通过 BackendTrafficPolicy 处理，它不支持特定于端口的设置。

假设你有一个具有多个端口的 Service，其中 8443 用作自定义 HTTPS 端口：

apiVersion: v1
kind: Service
metadata:
  namespace: api7
  name: httpbin
spec:
  selector:
    app: httpbin
  ports:
    - name: http
      port: 80
      targetPort: 80
    - name: https-custom
      port: 8443
      targetPort: 8443

要配置特定于端口的设置，请创建一个包含 PortLevelSettings 的 ApisixUpstream：

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: api7
  name: httpbin
spec:
  ingressClassName: apisix
  loadbalancer:        # 上游默认设置
    type: roundrobin
  timeout:
    connect: 6s
    send: 6s
    read: 6s
  retries: 3
  portLevelSettings:
    - port: 8443       # 匹配 Service 的 HTTPS 端口
      scheme: https    # 为此端口强制使用 HTTPS Scheme
      timeout:         # 配置特定于端口的超时时间
        connect: 10s
        send: 10s
        read: 10s
    - port: 80         # 匹配 Service 的 HTTP 端口
      scheme: http     # 为此端口强制使用 HTTP Scheme
                       # 使用其他上游默认设置

最后，创建一个引用该 Service 的 ApisixRoute：

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: api7
  name: httpbin
spec:
  ingressClassName: apisix
  http:
  - name: httpbin
    match:
      paths:
      - /anything
    backends:
    - serviceName: httpbin
      servicePort: 8443    # 这将强制使用 HTTPS Scheme 以及其他相关的上游设置

配置消费者和凭证​

要创建消费者并直接在消费者上配置身份验证凭证：

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: primary-key
      config:
        key: alice-primary-key

你还可以使用 Secret CRD，其中凭证应进行 base64 编码：

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

在消费者上配置插件​

要在消费者上配置插件，例如速率限制插件：

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  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

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

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

apiVersion: apisix.apache.org/v1alpha1
kind: HTTPRoutePolicy
metadata:
  namespace: api7
  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

在服务/路由上配置插件​

Gateway API 目前不支持在路由上启用插件。要在服务上启用插件：

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: api7
  name: auth-plugin-config
spec:
  plugins:
    - name: key-auth
      config:
        _meta:
          disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: api7
  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/v1alpha1
kind: GatewayProxy
metadata:
  namespace: api7
  name: apisix-proxy-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
        - https://xxx.xxx.xxx.xxx:7443  # 替换为你的 CP 端点
      auth:
        type: AdminKey
        adminKey:
          value: xxxxxxxxxxx            # 替换为你的 admin key
  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/v1alpha1
kind: GatewayProxy
metadata:
  namespace: api7
  name: apisix-proxy-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
        - https://xxx.xxx.xxx.xxx:7443  # 替换为你的 CP 端点
      auth:
        type: AdminKey
        adminKey:
          value: xxxxxxxxxxx            # 替换为你的 admin key
  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
    }

配置插件配置​

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

apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: api7
  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: api7
  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

配置下游 (m)TLS​

要配置下游 TLS：

apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: test-tls-secret
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded cert>
  tls.key: <base64-encoded key>
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  namespace: api7
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: apisix.test
      tls:
        certificateRefs:
        - kind: Secret
          group: ""
          name: test-tls-secret
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-proxy-config
备注

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

要配置下游 mTLS：

不支持。

配置网关访问信息​

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

要配置 statusAddress：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: api7
  name: apisix-proxy-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
        - https://xxx.xxx.xxx.xxx:7443  # 替换为你的 CP 端点
      auth:
        type: AdminKey
        adminKey:
          value: xxxxxxxxxxx            # 替换为你的 admin key
  statusAddress:
    - 10.24.87.13