注解

注解是键值对，允许控制器配置标准 Kubernetes 资源字段无法提供的功能。在 APISIX 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 类

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

响应重写

这些注解允许你在将上游服务的响应发送给客户端之前对其进行修改。它们对应于 APISIX 中 response-rewrite 插件的功能。

注解 (Annotation)	描述
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 地址范围控制客户端访问。它们对应于 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

转发认证

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

注解 (Annotation)	描述
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

正则表达式路由匹配

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

例如：

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

认证

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

跨命名空间服务访问

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

例如：

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"  # Service 位于 other-namespace
spec:
  ingressClassName: apisix
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 80

代理重写

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

注解 (Annotation)	描述
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

插件配置

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 插件。

注解 (Annotation)	描述
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 方法

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

注解 (Annotation)	描述
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

重定向

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

注解 (Annotation)	描述
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 状态码。

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

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 请求重定向到新的 URI，并使用自定义的 HTTP 重定向状态码：

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 插件。

注解 (Annotation)	描述
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

上游

这些注解允许你在 APISIX 中为 Ingress 配置上游行为，包括协议、重试次数和超时。它们对应于 Apache APISIX 中的上游设置。

注解 (Annotation)	描述
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