版本：3.9.x

注解 (Annotations)

注解（Annotations）是键值对，允许控制器配置无法通过标准 Kubernetes 资源字段实现的功能。在 API7 Ingress Controller 中，注解通常用于配置网关行为、路由规则、上游设置、插件和其他功能。或者，你可以使用 APISIX CRD 来配置这些功能，以获得更好的体验。

本文档描述了所有可用的注解及其用途。

Ingress 注解

注解
`kubernetes.io/ingress.class`
`k8s.apisix.apache.org/use-regex`
`k8s.apisix.apache.org/enable-websocket`
`k8s.apisix.apache.org/plugin-config-name`
`k8s.apisix.apache.org/upstream-scheme`
`k8s.apisix.apache.org/upstream-retries`
`k8s.apisix.apache.org/upstream-connect-timeout`
`k8s.apisix.apache.org/upstream-read-timeout`
`k8s.apisix.apache.org/upstream-send-timeout`
`k8s.apisix.apache.org/enable-cors`
`k8s.apisix.apache.org/cors-allow-origin`
`k8s.apisix.apache.org/cors-allow-headers`
`k8s.apisix.apache.org/cors-allow-methods`
`k8s.apisix.apache.org/enable-csrf`
`k8s.apisix.apache.org/csrf-key`
`k8s.apisix.apache.org/http-to-https`
`k8s.apisix.apache.org/http-redirect`
`k8s.apisix.apache.org/http-redirect-code`
`k8s.apisix.apache.org/rewrite-target`
`k8s.apisix.apache.org/rewrite-target-regex`
`k8s.apisix.apache.org/rewrite-target-regex-template`
`k8s.apisix.apache.org/enable-response-rewrite`
`k8s.apisix.apache.org/response-rewrite-status-code`
`k8s.apisix.apache.org/response-rewrite-body`
`k8s.apisix.apache.org/response-rewrite-body-base64`
`k8s.apisix.apache.org/response-rewrite-add-header`
`k8s.apisix.apache.org/response-rewrite-set-header`
`k8s.apisix.apache.org/response-rewrite-remove-header`
`k8s.apisix.apache.org/auth-uri`
`k8s.apisix.apache.org/auth-ssl-verify`
`k8s.apisix.apache.org/auth-request-headers`
`k8s.apisix.apache.org/auth-upstream-headers`
`k8s.apisix.apache.org/auth-client-headers`
`k8s.apisix.apache.org/allowlist-source-range`
`k8s.apisix.apache.org/blocklist-source-range`
`k8s.apisix.apache.org/http-allow-methods`
`k8s.apisix.apache.org/http-block-methods`
`k8s.apisix.apache.org/auth-type`
`k8s.apisix.apache.org/svc-namespace`

IngressClass 注解

注解
`apisix.apache.org/parameters-namespace`

注解详情

请注意，注解的键和值只能是字符串。

Ingress Class

kubernetes.io/ingress.class 注解指定哪个 Ingress Controller 应处理给定的 Ingress 资源。当在同一个集群中部署了多个 Ingress Controller 时，这非常有用。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: httpbin
  annotations:
    kubernetes.io/ingress.class: "apisix"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

响应重写 (Response Rewrite)

这些注解使你能够在将上游服务的响应发送到客户端之前修改该响应。它们对应于 APISIX 中 response-rewrite 插件的功能。

注解	描述
`k8s.apisix.apache.org/enable-response-rewrite`	启用响应重写功能。设置为 `true` 以便为此资源启用响应重写。
`k8s.apisix.apache.org/response-rewrite-status-code`	为响应指定一个新的 HTTP 状态码。
`k8s.apisix.apache.org/response-rewrite-body`	使用指定的纯文本内容替换响应体。
`k8s.apisix.apache.org/response-rewrite-body-base64`	使用 Base64 编码的内容替换响应体。
`k8s.apisix.apache.org/response-rewrite-add-header`	向响应中添加新的请求头。你可以将多个请求头指定为逗号分隔的列表。
`k8s.apisix.apache.org/response-rewrite-set-header`	设置或覆盖响应中的现有请求头。你可以将多个请求头指定为逗号分隔的列表。
`k8s.apisix.apache.org/response-rewrite-remove-header`	从响应中删除指定的请求头。你可以将多个请求头指定为逗号分隔的列表。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: httpbin-response-rewrite
  annotations:
    k8s.apisix.apache.org/enable-response-rewrite: "true"
    k8s.apisix.apache.org/response-rewrite-status-code: "403"
    k8s.apisix.apache.org/response-rewrite-body: "Access denied"
    k8s.apisix.apache.org/response-rewrite-add-header: "X-Reason:Forbidden,X-Env:Test"
    k8s.apisix.apache.org/response-rewrite-remove-header: "header1,header2"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

IP 限制 (IP Restriction)

这些注解控制基于 IP 地址范围的客户端访问。它们对应于 APISIX 中 ip-restriction 插件的功能。

注解	描述
`k8s.apisix.apache.org/allowlist-source-range`	允许访问资源的 CIDR 范围的逗号分隔列表。所有其他 IP 均被拒绝。
`k8s.apisix.apache.org/blocklist-source-range`	被阻止访问资源的 CIDR 范围的逗号分隔列表。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ip-restriction
  annotations:
    k8s.apisix.apache.org/allowlist-source-range: "10.0.0.0/24,192.168.1.0/24"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

转发认证 (Forward Auth)

这些注解配置外部认证端点，在请求到达后端服务之前对其进行验证。它们对应于 APISIX 中 forward-auth 插件的功能。

注解	描述
`k8s.apisix.apache.org/auth-uri`	外部认证服务器的 URI。请求将被转发到此 URI 进行验证。
`k8s.apisix.apache.org/auth-ssl-verify`	启用或禁用与认证服务器通信时的 SSL 证书验证。设置为 `true` 或 `false`。
`k8s.apisix.apache.org/auth-request-headers`	要转发到认证服务器的请求头的逗号分隔列表。
`k8s.apisix.apache.org/auth-upstream-headers`	从认证响应中要转发到上游服务的请求头的逗号分隔列表。
`k8s.apisix.apache.org/auth-client-headers`	从认证响应中要返回给客户端的请求头的逗号分隔列表。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-forward-auth
  annotations:
    k8s.apisix.apache.org/auth-uri: "https://auth.example.com/verify"
    k8s.apisix.apache.org/auth-ssl-verify: "true"
    k8s.apisix.apache.org/auth-request-headers: "Authorization"
    k8s.apisix.apache.org/auth-upstream-headers: "X-User-ID,X-User-Role"
    k8s.apisix.apache.org/auth-client-headers: "X-Auth-Status"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

正则表达式路由匹配 (RegEx Route Matching)

k8s.apisix.apache.org/use-regex 注解允许 Ingress 使用正则表达式定义路由以进行高级路径匹配。设置为 true 可将 path 字段解释为 RegEx 模式。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-regex
  annotations:
    k8s.apisix.apache.org/use-regex: "true"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: "/users/[0-9]+"
        pathType: ImplementationSpecific
        backend:
          service:
            name: user-service
            port:
              number: 80

认证 (Authentication)

k8s.apisix.apache.org/auth-type 注解指定要应用于 Ingress 资源的认证类型。支持 keyAuth 和 basicAuth。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-key-auth
  annotations:
    k8s.apisix.apache.org/auth-type: "keyAuth"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  name: john
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: john-key

跨命名空间服务访问 (Cross Namespace Service Access)

k8s.apisix.apache.org/svc-namespace 注解允许 Ingress 将流量路由到与 Ingress 资源位于不同命名空间中的服务。默认情况下，Ingress 只能引用同一命名空间内的服务。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cross-namespace-ingress
  namespace: aic # Ingress 在 aic 命名空间
  annotations:
    k8s.apisix.apache.org/svc-namespace: "other-namespace"  # 服务在 other-namespace
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 80

代理重写 (Proxy Rewrite)

这些注解允许你在将请求转发到上游服务之前重写请求路径。它们对应于 APISIX 中 proxy-rewrite 插件的功能。

注解	描述
`k8s.apisix.apache.org/rewrite-target`	将请求路径重写为指定的目标路径。
`k8s.apisix.apache.org/rewrite-target-regex`	指定要在原始请求路径中匹配的正则表达式模式。
`k8s.apisix.apache.org/rewrite-target-regex-template`	使用 `rewrite-target-regex` 时重写请求路径的模板。支持捕获正则表达式模式中的分组。

例如，以下配置重写请求，使向 /api 的请求转发到 /new-path：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-rewrite
  annotations:
    k8s.apisix.apache.org/rewrite-target: "/new-path"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

例如，以下配置重写请求，使向 /api/test 的请求转发到 /backend/test：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-regex-rewrite
  annotations:
    k8s.apisix.apache.org/rewrite-target-regex: "^/api/(.*)"
    k8s.apisix.apache.org/rewrite-target-regex-template: "/backend/$1"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

插件配置 (Plugin Config)

k8s.apisix.apache.org/plugin-config-name 注解允许你将预定义的 APISIX 插件配置附加到 Ingress 资源。它对应于 APISIX 中的 PluginConfig 资源，从而支持跨多个路由或服务重用插件设置。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-plugin-config
  annotations:
    k8s.apisix.apache.org/plugin-config-name: "rate-limit-config"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80
---
apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
  name: rate-limit-config
spec:
  ingressClassName: apisix
  plugins:
  - name: limit-count
    enable: true
    config:
      count: 2
      time_window: 10
      rejected_code: 429

CSRF

这些注解为 Ingress 启用 CSRF（跨站请求伪造）保护。它们对应于 APISIX 中的 csrf 插件。

注解	描述
`k8s.apisix.apache.org/enable-csrf`	启用或禁用 CSRF 保护。设置为 `true` 以启用该插件。
`k8s.apisix.apache.org/csrf-key`	指定用于签名和验证 CSRF 令牌的密钥。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-csrf
  annotations:
    k8s.apisix.apache.org/enable-csrf: "true"
    k8s.apisix.apache.org/csrf-key: "my-secret-csrf-key"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

允许/阻止 HTTP 方法 (Allow/Block HTTP Methods)

这些注解控制允许或阻止 Ingress 的哪些 HTTP 方法。如果同时指定了允许和阻止方法，则只有允许列表生效。

注解	描述
`k8s.apisix.apache.org/http-allow-methods`	显式允许的 HTTP 方法的逗号分隔列表。使用其他方法的请求将被拒绝。
`k8s.apisix.apache.org/http-block-methods`	显式阻止的 HTTP 方法的逗号分隔列表。使用这些方法的请求将被拒绝。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-http-methods
  annotations:
    k8s.apisix.apache.org/http-allow-methods: "GET,POST"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

启用 Websocket

当设置为 true 时，k8s.apisix.apache.org/enable-websocket 注解为 Ingress 启用 WebSocket 支持。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-websocket
  annotations:
    k8s.apisix.apache.org/enable-websocket: "true"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /ws
        pathType: Exact
        backend:
          service:
            name: websocket-service
            port:
              number: 8080

重定向 (Redirect)

这些注解为 Ingress 配置 HTTP 到 HTTPS 重定向或自定义 HTTP 重定向。它们对应于 APISIX 中的 redirect 插件。

注解	描述
`k8s.apisix.apache.org/http-to-https`	设置为 `true` 以自动将 HTTP 请求重定向到 HTTPS。
`k8s.apisix.apache.org/http-redirect`	指定将请求重定向到的自定义 URL。
`k8s.apisix.apache.org/http-redirect-code`	用于重定向的 HTTP 状态码。

例如，以下配置使用 301 状态码将 HTTP 请求重定向到 HTTPS：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-https-redirect
  annotations:
    k8s.apisix.apache.org/http-to-https: "true"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

例如，以下配置将 HTTP 请求重定向到具有自定义 HTTP 重定向状态码的新 URI：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-custom-redirect
  annotations:
    k8s.apisix.apache.org/http-redirect: "https://example.com/new-path"
    k8s.apisix.apache.org/http-redirect-code: "302"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

CORS

这些注解为 Ingress 配置跨域资源共享（CORS）。它们对应于 APISIX 中的 cors 插件。

注解	描述
`k8s.apisix.apache.org/enable-cors`	设置为 `true` 以启用 CORS。
`k8s.apisix.apache.org/cors-allow-origin`	指定允许的来源，例如 `*` 或 `https://example.com`。
`k8s.apisix.apache.org/cors-allow-headers`	跨域请求中允许的请求头的逗号分隔列表。
`k8s.apisix.apache.org/cors-allow-methods`	允许的 HTTP 方法的逗号分隔列表。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-cors
  annotations:
    k8s.apisix.apache.org/enable-cors: "true"
    k8s.apisix.apache.org/cors-allow-origin: "https://example.com"
    k8s.apisix.apache.org/cors-allow-headers: "Content-Type,Authorization"
    k8s.apisix.apache.org/cors-allow-methods: "GET,POST,PUT"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

上游 (Upstream)

这些注解允许你在 APISIX 中为 Ingress 配置上游行为，包括方案（scheme）、重试和超时。它们对应于 Apache APISIX 中的上游设置。

注解	描述
`k8s.apisix.apache.org/upstream-scheme`	指定用于与上游服务通信的协议。默认为 `http`。支持 `http`、`https`、`grpc` 和 `grpcs`。
`k8s.apisix.apache.org/upstream-retries`	失败时上游请求的重试次数。
`k8s.apisix.apache.org/upstream-connect-timeout`	建立到上游服务的连接的超时时间。默认为 `60s`。
`k8s.apisix.apache.org/upstream-read-timeout`	从上游服务读取响应的超时时间。默认为 `60s`。
`k8s.apisix.apache.org/upstream-send-timeout`	向上游服务发送请求的超时时间。默认为 `60s`。

例如：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-upstream
  annotations:
    k8s.apisix.apache.org/upstream-scheme: "https"
    k8s.apisix.apache.org/upstream-retries: "3"
    k8s.apisix.apache.org/upstream-connect-timeout: "5s"
    k8s.apisix.apache.org/upstream-read-timeout: "5s"
    k8s.apisix.apache.org/upstream-send-timeout: "5s"
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: httpbin
            port:
              number: 80

GatewayProxy 命名空间规范

apisix.apache.org/parameters-namespace 注解能够为 IngressClass 引用的 GatewayProxy 资源指定自定义命名空间。当 GatewayProxy 资源驻留在特定命名空间时使用此功能，因为 IngressClass 是集群范围的，需要命名空间来定位资源。

该注解优先于 IngressClass 规范中的 parameters.namespace 字段。如果均未指定，则默认为 default 命名空间。

例如：

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apisix
  annotations:
    apisix.apache.org/parameters-namespace: "apisix-system"
spec:
  controller: apisix.apache.org/ingress-controller
  parameters:
    apiGroup: apisix.apache.org
    kind: GatewayProxy
    name: apisix-config

Ingress 注解​

IngressClass 注解​

注解详情​

Ingress Class​

响应重写 (Response Rewrite)​

IP 限制 (IP Restriction)​

转发认证 (Forward Auth)​

正则表达式路由匹配 (RegEx Route Matching)​

认证 (Authentication)​

跨命名空间服务访问 (Cross Namespace Service Access)​

代理重写 (Proxy Rewrite)​

插件配置 (Plugin Config)​

CSRF​

允许/阻止 HTTP 方法 (Allow/Block HTTP Methods)​

启用 Websocket​

重定向 (Redirect)​

CORS​

上游 (Upstream)​

GatewayProxy 命名空间规范​