跳到主要内容

配置示例

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

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

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

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

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

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  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 # 替换为你的管理员密钥

信任私有控制面 CA​

API7 Ingress Controller 2.2.1 可以验证由私有或自签名证书颁发机构签发的控制面证书。APISIX Ingress Controller 2.2.0 不包含 caCert 字段。

将 tlsVerify 设置为 true，并在 GatewayProxy 中提供 PEM 编码的证书颁发机构证书包：

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: api7-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
      - https://api7-control-plane.example.com
      tlsVerify: true
      caCert:
        value: |
          -----BEGIN CERTIFICATE-----
          REPLACE_WITH_BASE64_ENCODED_CA_CERTIFICATE
          -----END CERTIFICATE-----
      auth:
        type: AdminKey
        adminKey:
          valueFrom:
            secretKeyRef:
              name: api7-admin-key
              key: token

该示例引用同一命名空间中已有的 api7-admin-key Secret，其中 Admin API Key 存储在 token 下。对于此连接，自定义 CA 证书包会替换系统信任存储。Controller 会拒绝无效的 PEM 证书数据。当 tlsVerify 为 false 时，caCert 不生效。

定义 Ingress Controller 和网关​

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

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: aic
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: apisix-config

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

❷ 被引用资源的 API 组。

❸ 被引用资源的种类。

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

port 用于选择 Gateway 监听器，但不会打开数据面端口。有关可选的物理端口匹配，请参阅配置文件。

路由到 Kubernetes 服务​

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

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

路由到外部服务​

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

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

配置带权重的服务​

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

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  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 资源不支持此配置。

配置上游​

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

apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
  namespace: aic
  name: httpbin
spec:
  targetRefs:
  - name: httpbin
    kind: Service
    group: ""
  timeout:
    send: 10s
    read: 10s
    connect: 10s
  scheme: http
  retries: 10
  healthCheck:
    active:
      type: http
      httpPath: /status/200
      healthy:
        interval: 2s
        successes: 1
        httpCodes:
        - 200
      unhealthy:
        interval: 1s
        timeouts: 3
        httpFailures: 3
        httpCodes:
        - 500
  loadbalancer:
    type: roundrobin
  passHost: rewrite
  upstreamHost: httpbin.example.com

配置端口级上游设置​

ApisixUpstream 中的 PortLevelSettings 可以按端口定义协议相关配置。对于暴露多个协议的 Service，或需要在不同端口上分别配置超时、负载均衡、TLS 等上游行为的场景，这很有用。

信息

PortLevelSettings 仅在 APISIX CRD 中支持。使用 Gateway API 时，请通过 BackendTrafficPolicy 配置上游行为。控制器可以使用 targetRefs[].sectionName 指向命名的 Service 端口。BackendTrafficPolicy 不提供 ApisixUpstream 使用的 PortLevelSettings 结构。

假设有一个包含多个端口的 Service，其中 8443 是自定义 HTTPS 端口：

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  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: aic
  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 协议
      timeout:         # 配置端口专属超时
        connect: 10s
        send: 10s
        read: 10s
    - port: 80         # 匹配 Service 的 HTTP 端口
      scheme: http     # 强制此端口使用 HTTP 协议
                       # 使用其他上游默认设置

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

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

配置消费者和凭证​

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

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  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: aic
  name: key-auth-primary
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk= # alice-primary-key 的 base64 编码
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth-primary
      secretRef:
        name: key-auth-primary

在消费者上配置插件​

认证插件​

credentials 字段支持四种认证插件，包括 key-auth、basic-auth、jwt-auth 和 hmac-auth。示例如下：

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

其他插件​

以下示例将 limit-count 插件应用到消费者：

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: aic
  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: aic
  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/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: auth-plugin-config
spec:
  plugins:
    - name: key-auth
      config:
        _meta:
          disable: false
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  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: aic
  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/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  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
    }

配置插件配置​

PluginConfig支持提取和复用通用插件配置，减少不同路由中的重复插件定义，提高 API 管理效率。

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

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

将插件配置存储在 Secret 中​

API7 Ingress Controller 2.2.1 可以将同一命名空间 Secret 中的敏感插件字段合并到 v1alpha1 PluginConfig、Consumer 或 L4RoutePolicy 中。APISIX Ingress Controller 2.2.0 不包含此 secretRef 字段。

每个 Secret Key 都是插件配置中以点分隔的路径。Secret Value 均为字符串，并会覆盖 config 中的相同路径，因此数值和布尔字段应继续以内联方式配置。

apiVersion: v1
kind: Secret
metadata:
  namespace: aic
  name: oidc-credentials
stringData:
  client_id: replace-with-your-client-id
  client_secret: replace-with-your-client-secret
  session.secret: replace-with-a-random-session-secret
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: oidc
spec:
  plugins:
  - name: openid-connect
    secretRef:
      name: oidc-credentials
    config:
      discovery: https://idp.example.com/.well-known/openid-configuration
      scope: openid profile

按照配置插件配置中的方式，通过 HTTPRoute ExtensionRef 引用 PluginConfig。更新 Secret 会触发 Controller 重新协调使用该 Secret 的资源。如果 Secret 缺失，Controller 不会使用不完整配置下发该插件。

配置网关访问信息​

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

配置 statusAddress：

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