Ingress Annotation 说明

最后更新时间：2025-08-14 11:34:24
Ingress Annotation 说明
最后更新时间： 2025-08-14 11:34:24
说明
查看当前集群 ingress-controller 版本：kubectl -n kube-system get cm tke-ingress-controller-config -o jsonpath='{.data.VERSION}'
列表
指定 ingress 类型
名称： kubernetes.io/ingress.class
说明： 
指定 ingress 类型。如果没有指定，则认为是 qcloud，由 TKE 识别为 CLB 类型。
类型： string
版本要求： >=v1.0.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: 'qcloud'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
负载均衡 ID
名称： kubernetes.io/ingress.qcloud-loadbalance-id
说明： 
只读注解，组件提供当前 Ingress 引用的负载均衡 LoadBalanceId。
类型： string
版本要求： >=v1.0.0
复用已有负载均衡
名称： kubernetes.io/ingress.existLbId
说明： 
使用已存在的 CLB，需注意不同使用方式对腾讯云标签的影响。
详情参考 容器服务 Ingress 使用已有 CLB。
类型： string
版本要求： >=v1.0.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.existLbId: 'lb-6swtxxxx'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
创建内网负载均衡
名称： kubernetes.io/ingress.subnetId
说明： 
在指定子网创建内网负载均衡。
类型： enum
版本要求： >=v1.0.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.subnetId: 'subnet-xxx'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
指定付费类型
名称： kubernetes.io/ingress.internetChargeType
说明： 
负载均衡的付费类型，当前仅在创建时支持配置，创建后不支持修改付费类型，创建后修改本注解无效。
指定创建负载均衡时，负载均衡的付费类型。请配合 kubernetes.io/ingress.internetMaxBandwidthOut 注解一起使用。
可选值：
BANDWIDTH_POSTPAID_BY_HOUR：按带宽按小时后计费
TRAFFIC_POSTPAID_BY_HOUR：按流量按小时后计费
类型： enum
版本要求： >=v1.0.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.internetChargeType: 'BANDWIDTH_POSTPAID_BY_HOUR'
    kubernetes.io/ingress.internetMaxBandwidthOut: '10'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
指定公网带宽上限
名称： kubernetes.io/ingress.internetMaxBandwidthOut
说明： 
CLB 带宽设置，当前仅在创建时支持配置，创建后不支持修改带宽，创建后修改本注解无效。
指定创建负载均衡时，负载均衡的最大出带宽，仅对公网属性的 LB 生效。需配合 kubernetes.io/ingress.internetChargeType 注解一起使用。
值域： [1, 2048] Mbps。
类型： int
版本要求： >=v1.0.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.internetMaxBandwidthOut: '10'
    kubernetes.io/ingress.internetChargeType: 'TRAFFIC_POSTPAID_BY_HOUR'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
负载均衡拓展参数
名称： kubernetes.io/ingress.extensiveParameters
说明： 
指定 CLB 创建时的参数，当前仅在创建时支持配置，创建后不支持修改，创建后修改本注解无效。
详情参考 创建负载均衡实例 为创建负载均衡追加自定义参数。
类型： json
版本要求： >=v1.0.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.extensiveParameters: '{"VipIsp":"CTCC"}'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
安全组默认放通
名称： ingress.cloud.tencent.com/pass-to-target
说明： 
是否启用 CLB 安全组默认放通的能力，CLB 和 CVM 之间默认放通，来自 CLB 的流量只需通过 CLB 上安全组的校验。
注意：
请查看 CLB 使用安全组的使用限制。
通常需要配合绑定安全组的能力。对应 Annotation 为：ingress.cloud.tencent.com/security-groups。
类型： bool
版本要求： >=v1.8.3
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/pass-to-target: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
绑定/解绑安全组
名称： ingress.cloud.tencent.com/security-groups
说明： 
为 CLB 绑定安全组，单个 CLB 最多可绑定5个安全组。
注意：
请查看 CLB 使用安全组的使用限制。
通常需要配合安全组默认放通的能力，CLB 和 CVM 之间默认放通，来自 CLB 的流量只需通过 CLB 上安全组的校验。对应 Annotation 为：ingress.cloud.tencent.com/pass-to-target。
对于Ingress 使用已有 CLB场景，不支持用该注解为 CLB 配置安全组。
类型： string
版本要求： >=v1.8.3
使用示例：
绑定安全组：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/security-groups: 'sg-xxxxx,sg-yyyyy,sg-zzzzz'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
解绑部分安全组：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/security-groups: 'sg-xxxxx'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
解绑全部安全组（>=v2.5.2）：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/security-groups: ''
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
修改保护
名称： ingress.cloud.tencent.com/modification-protection
说明： 
配置 CLB 修改保护，开启后将无法通过 CLB 控制台或 API 修改负载均衡实例的属性。
类型： bool
版本要求： >=v1.7.3
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/modification-protection: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
自定义监听端口
名称： ingress.cloud.tencent.com/listen-ports
说明： 
自定义 Ingress 的监听端口。
默认情况下，HTTP 为 80，HTTPS 为 443，通过该 Annotation 可以自定义 Ingress 对应的 CLB 所监听的端口，支持分别为 HTTP 和 HTTPS 协议自定义一个或多个端口。
注意:
如需使用自动重定向 (ingress.cloud.tencent.com/auto-rewrite: "true")，仅在 HTTP：80 以及 HTTPS：443 均存在时生效。
类型： json
版本要求： >=v2.4.1
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}, {"HTTP": 8080}, {"HTTPS": 8443}]'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
使用拓展配置
名称： ingress.cloud.tencent.com/tke-service-config
说明： 
通过 tke-service-config 配置负载均衡 CLB。
详情参考 容器服务 Ingress 使用 TkeServiceConfig 配置 CLB。
类型： string
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/tke-service-config: 'config-name'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
使用自动生成拓展配置
名称： ingress.cloud.tencent.com/tke-service-config-auto
说明： 
通过该注解可自动创建 TkeServiceConfig，然后可按需修改配置。
详情参考 容器服务 Ingress 使用 TkeServiceConfig 配置 CLB。
类型： bool
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/tke-service-config-auto: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
自动重定向
名称： ingress.cloud.tencent.com/auto-rewrite
说明： 
为 HTTP 端口提供自动重定向能力，所有在 HTTPS 端口声明的转发规则都会创建对应的重定向规则。
详情参考 容器服务 Ingress 重定向。
注意：
如果之前已启用重定向功能，但现在需要关闭重定向功能，请显式将该注解设置为 "false"，而不是直接删除注解。
类型： bool
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/auto-rewrite: 'true'
    ingress.cloud.tencent.com/rewrite-support: "true"
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
支持重定向
名称： ingress.cloud.tencent.com/rewrite-support
说明： 
开启重定向支持，配合 kubernetes.io/ingress.http-rules、kubernetes.io/ingress.https-rules 实现手动重定向能力。
注意：
如果之前已启用重定向功能，但现在需要关闭重定向功能，请显式将该注解设置为 "false"，而不是直接删除注解。
类型： bool
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/rewrite-support: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
混合协议
名称： kubernetes.io/ingress.rule-mix
说明： 
支持配置混合协议，支持转发路径同时在 HTTP 和 HTTPS 上进行转发。支持手动配置重定向规则。  
详情参考 Ingress 混合使用 HTTP 及 HTTPS 协议。
类型： bool
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.rule-mix: 'true'
    kubernetes.io/ingress.http-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
    kubernetes.io/ingress.https-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
配置 http 转发规则
名称： kubernetes.io/ingress.http-rules
说明： 
配置 HTTP 转发规则，支持手动配置重定向规则。
详情参考 Ingress 混合使用 HTTP 及 HTTPS 协议。
类型： json
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.http-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
    kubernetes.io/ingress.rule-mix: "true"
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
配置 https 转发规则
名称： kubernetes.io/ingress.https-rules
说明： 
配置 HTTPS 转发规则，支持手动配置重定向规则。
详情参考 Ingress 混合使用 HTTP 及 HTTPS 协议。
类型： json
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.https-rules: '[{"host":"example.com","path":"/","backend":{"serviceName":"example","servicePort":"80"}}]'
    kubernetes.io/ingress.rule-mix: "true"
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
开启直连
名称： ingress.cloud.tencent.com/direct-access
说明： 
支持七层直连用户负载均衡。需要注意在各种不同的网络下，直连接入的服务依赖。               
详情参考 使用 LoadBalancer 直连 Pod 模式 Service。
类型： bool
版本要求： >=v1.3.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
优雅停机
名称： ingress.cloud.tencent.com/enable-grace-shutdown
说明： 
支持 CLB 直连模式的优雅停机。Pod 被删除，此时 Pod 里有 DeletionTimestamp，且状态置为 Terminating。此时调整 CLB 到该 Pod 的权重为 0。
仅在直连模式下支持，需要配合使用 ingress.cloud.tencent.com/direct-access。
v2.2.0 版本开始废弃，默认开启。
详情参考 Ingress 优雅停机。
类型： bool
版本要求： >=v1.5.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/enable-grace-shutdown: 'true'
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
优雅停机 tkex
名称： ingress.cloud.tencent.com/enable-grace-shutdown-tkex
说明： 
支持 CLB 直连模式的优雅退出。Endpoint 对象中 endpoints 是否 not-ready，将 not-ready 的 CLB 后端权重置为 0。
仅在直连模式下支持，需要配合使用 ingress.cloud.tencent.com/direct-access。
v2.2.0 版本开始废弃，默认开启。
详情参考 Ingress 优雅停机。
类型： bool
版本要求： >=v1.5.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/enable-grace-shutdown-tkex: 'true'
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
优雅删除
名称： ingress.cloud.tencent.com/enable-grace-deletion
说明： 
开启后，运行时等待控制器将所有 Pod 的权重调整为 0 后，再删除后端。
仅在直连模式下支持，需要配合使用 ingress.cloud.tencent.com/direct-access。
类型： bool
版本要求： >=v2.4.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/enable-grace-deletion: 'true'
    ingress.cloud.tencent.com/direct-access: 'true'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
自定义后端权重
名称： ingress.cloud.tencent.com/lb-rs-weight
说明： 
用来支持自定义后端权重，可以设定默认权重以及有状态服务的权重。
类型： json
版本要求： >=v1.6.0
使用示例：
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.cloud.tencent.com/lb-rs-weight: '{"defaultWeight":10,"groups":[{"key":{"proto":"TCP","port":80},"statefulSets":[{"name":"ti-ai-gateway-gz-shared-st-v1","weights":[{"weight":0,"podIndexes":[0]}]},{"name":"ti-ai-gateway-gz-shared-st-v2","weights":[{"weight":10,"podIndexes":[0]}]}]}]}'
  name: example
spec:
  rules:
  - host: example.com
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
﻿
﻿
本页内容是否解决了您的问题？
您也可以联系销售或提交工单以寻求帮助。
是
否
文档反馈
tencent cloud

说明

列表

指定 ingress 类型

负载均衡 ID

复用已有负载均衡

创建内网负载均衡

指定付费类型

指定公网带宽上限

负载均衡拓展参数

安全组默认放通

绑定/解绑安全组

修改保护

自定义监听端口

使用拓展配置

使用自动生成拓展配置

自动重定向

支持重定向

混合协议

配置 http 转发规则

配置 https 转发规则

开启直连

优雅停机

优雅停机 tkex

优雅删除

自定义后端权重
