动态与公告

产品动态

公告

产品发布记录

产品简介

产品概述

产品优势

产品架构

应用场景

产品功能

基本概念

原生 Kubernetes 名词对照

容器服务高危操作

地域和可用区

开源组件

购买指南

购买指引

购买 TKE 标准集群

购买原生节点

购买超级节点

快速入门

新手指引

快速创建一个标准集群

入门示例

容器应用部署 Check List

集群配置

标准集群概述

集群管理

网络管理

存储管理

节点管理

GPU 资源管理

远程终端

应用配置

工作负载管理

服务和配置管理

组件和应用管理

弹性伸缩

容器登录方式

可观测配置

运维可观测性

成本洞察和优化

调度配置

调度组件概述

资源利用率优化调度

业务优先级保障调度

Qos 感知调度

安全和稳定性

容器服务安全组设置

身份验证和授权

应用安全

多集群管理

计划升级

备份中心

云原生服务指南

云原生 etcd

Prometheus 监控服务

TKE Serverless 集群指南

TKE 注册集群指南

实践教程

集群

Serverless 集群

调度

安全

服务部署

网络

发布

日志

监控

运维

Terraform

DevOps

弹性伸缩

容器化

微服务

成本管理

混合云

故障处理

节点磁盘爆满排障处理

节点高负载排障处理

节点内存碎片化排障处理

集群 DNS 解析异常排障处理

集群 Kube-Proxy 异常排障处理

集群 API Server 网络无法访问排障处理

Service&Ingress 网络无法访问排障处理

Service&Ingress 常见报错和处理

Nginx Ingress 偶现 Connection Refused

CLB Ingress 创建报错排障处理

Pod 网络无法访问排查处理

Pod 状态异常与处理措施

授权腾讯云售后运维排障

CLB 回环问题

API 文档

History

Introduction

API Category

Making API Requests

Elastic Cluster APIs

Resource Reserved Coupon APIs

Cluster APIs

Third-party Node APIs

Relevant APIs for Addon

Network APIs

Node APIs

Node Pool APIs

TKE Edge Cluster APIs

Cloud Native Monitoring APIs

Scaling group APIs

Super Node APIs

Other APIs

Data Types

Error Codes

TKE API 2022-05-01

常见问题

TKE 标准集群

TKE Serverless 集群

运维类

隐患处理

服务类

镜像仓库类

远程终端类

事件类

资源管理类

服务协议

TKE Service Level Agreement

TKE Serverless Service Level Agreement

联系我们

词汇表

Ingress Annotation 说明

PDF

聚焦模式

字号

最后更新时间： 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 Annotation 说明

说明

列表

指定 ingress 类型

负载均衡 ID

复用已有负载均衡

创建内网负载均衡

指定付费类型

指定公网带宽上限

负载均衡拓展参数

安全组默认放通

绑定/解绑安全组

修改保护

自定义监听端口

使用拓展配置

使用自动生成拓展配置

自动重定向

支持重定向

混合协议

配置 http 转发规则

配置 https 转发规则

开启直连

优雅停机

优雅停机 tkex

优雅删除

自定义后端权重

帮助和支持