Service Annotation 说明

最近更新时间:2025-05-26 17:00:01

我的收藏

说明

查看当前集群 service-controller 版本:kubectl -n kube-system get cm tke-service-controller-config -o jsonpath='{.data.VERSION}'

列表

负载均衡 ID

名称: service.kubernetes.io/loadbalance-id
说明:
只读注解,提供当前 Service 引用的负载均衡 LoadBalanceId。您可以在腾讯云 CLB 控制台查看与集群在同一 VPC 下的 CLB 实例 ID。
类型: string
版本要求: >=v1.0.0

复用已有负载均衡

名称: service.kubernetes.io/tke-existed-lbid
说明:
使用已存在的 CLB,需注意不同使用方式对腾讯云标签的影响。
详情参考 Service 使用已有 CLB
类型: string
版本要求: >=v1.0.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.kubernetes.io/tke-existed-lbid: 'lb-6swtxxxx'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


创建内网负载均衡

名称: service.kubernetes.io/qcloud-loadbalancer-internal-subnetid
说明:
在指定子网创建内网负载均衡。
类型: string
版本要求: >=v1.0.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.kubernetes.io/qcloud-loadbalancer-internal-subnetid: 'subnet-xxx'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


指定付费类型

名称: service.kubernetes.io/qcloud-loadbalancer-internet-charge-type
说明:
负载均衡的付费类型,当前仅在创建时支持配置,创建后不支持修改付费类型,创建后修改本注解无效。
指定创建负载均衡时,负载均衡的付费类型。请配合 service.kubernetes.io/qcloud-loadbalancer-internet-max-bandwidth-out 注解一起使用。
可选值:
BANDWIDTH_POSTPAID_BY_HOUR:按带宽按小时后计费
TRAFFIC_POSTPAID_BY_HOUR:按流量按小时后计费
类型: enum
版本要求: >=v1.0.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.kubernetes.io/qcloud-loadbalancer-internet-charge-type: 'BANDWIDTH_POSTPAID_BY_HOUR'
service.kubernetes.io/qcloud-loadbalancer-internet-max-bandwidth-out: '10'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


指定公网带宽上限

名称: service.kubernetes.io/qcloud-loadbalancer-internet-max-bandwidth-out
说明:
CLB 带宽设置,当前仅在创建时支持配置,创建后不支持修改带宽,创建后修改本注解无效。
指定创建负载均衡时,负载均衡的最大出带宽,仅对公网属性的 LB 生效。需配合 service.kubernetes.io/qcloud-loadbalancer-internet-charge-type 注解一起使用。
值域: [1, 2048] Mbps。
类型: int
版本要求: >=v1.0.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.kubernetes.io/qcloud-loadbalancer-internet-max-bandwidth-out: '10'
service.kubernetes.io/qcloud-loadbalancer-internet-charge-type: 'TRAFFIC_POSTPAID_BY_HOUR'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


负载均衡拓展参数

名称: service.kubernetes.io/service.extensiveParameters
说明:
指定 CLB 创建时的参数,当前仅在创建时支持配置,创建后不支持修改,创建后修改本注解无效。
详情参考 创建负载均衡实例 为创建负载均衡追加自定义参数。
类型: json
版本要求: >=v1.0.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.kubernetes.io/service.extensiveParameters: '{"AddressIPVersion":"IPV4","InternetAccessible":{"InternetChargeType":"TRAFFIC_POSTPAID_BY_HOUR","InternetMaxBandwidthOut":10}}'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


安全组默认放通

名称: service.cloud.tencent.com/pass-to-target
说明:
是否启用 CLB 安全组默认放通的能力,CLB 和 CVM 之间默认放通,来自 CLB 的流量只需通过 CLB 上安全组的校验。
注意:
请查看 CLB 使用安全组的使用限制
通常需要配合绑定安全组的能力。对应 Annotation 为:service.cloud.tencent.com/security-groups。
对于 Service 使用已有 CLB 的场景,若多个 Service 声明了不同的放通配置,会有逻辑冲突的问题。
类型: bool
版本要求: >=v1.8.3
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/pass-to-target: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


绑定/解绑安全组

名称: service.cloud.tencent.com/security-groups
说明:
为 CLB 绑定安全组,单个 CLB 最多可绑定5个安全组。
注意:
请查看 CLB 使用安全组的使用限制
通常需要配合安全组默认放通的能力,CLB 和 CVM 之间默认放通,来自 CLB 的流量只需通过 CLB 上安全组的校验。对应 Annotation 为:service.cloud.tencent.com/pass-to-target。
对于 Service 使用已有 CLB 的场景,若多个 Service 声明了不同的安全组,会有逻辑冲突的问题。
类型: string
版本要求: >=v1.8.3
使用示例:
绑定安全组
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/security-groups: 'sg-xxxxx,sg-yyyyy,sg-zzzzz'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer
解绑部分安全组
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/security-groups: 'sg-xxxxx'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer
解绑全部安全组
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/security-groups: ''
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer

修改保护

名称: service.cloud.tencent.com/modification-protection
说明:
配置 CLB 修改保护,开启后将无法通过 CLB 控制台或 API 修改负载均衡实例的属性。
类型: bool
版本要求: >=v1.7.3
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/modification-protection: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


监听器拓展参数

名称: service.kubernetes.io/service.listenerParameters
说明:
指定 CLB 创建监听器时的参数,当前仅在创建时支持配置,创建后不支持修改,创建后修改本注解无效。
类型: json
版本要求: >=v1.1.0

使用拓展配置

名称: service.cloud.tencent.com/tke-service-config
说明:
通过 tke-service-config 配置负载均衡 CLB。
类型: string
版本要求: >=v1.3.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/tke-service-config: 'config-name'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


使用自动生成拓展配置

名称: service.cloud.tencent.com/tke-service-config-auto
说明:
通过该注解可自动创建 TkeServiceConfig,然后可按需修改配置。
类型: bool
版本要求: >=v1.3.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/tke-service-config-auto: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


使用拓展协议

名称: service.cloud.tencent.com/specify-protocol
说明:
支持通过注解为指定的监听端口配置 TCP、UDP、TCP SSL、HTTP、HTTPS。
详情参考 Service 扩展协议
类型: json
版本要求: >=v1.5.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/specify-protocol: '{"80":{"protocol":["HTTPS"],"hosts":{"a.tencent.com":{"tls":"cert-secret-a"},"b.tencent.com":{"tls":"cert-secret-b"}}}}'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


开启防止回环

名称: service.cloud.tencent.com/prevent-loopback
说明:
是否开启防止回环,开启后将修改健康探测源模式,采用100.64.0.0/10网段作为探测源。
详情参考 健康检查探测标识
类型: bool
版本要求: >=v1.7.3
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/prevent-loopback: 'false'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


开启直连

名称: service.cloud.tencent.com/direct-access
说明:
是否开启直连,负载均衡绑定 pod IP。
类型: bool
版本要求: >=v1.3.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/direct-access: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


指定后端标签

名称: service.kubernetes.io/qcloud-loadbalancer-backends-label
说明:
指定标签设置负载均衡后端绑定的节点。
详情参考 指定接入层后端
类型: string
版本要求: >=v1.0.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.kubernetes.io/qcloud-loadbalancer-backends-label: 'group=access-layer'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


自定义后端权重

名称: service.cloud.tencent.com/lb-rs-weight
说明:
用来支持自定义后端权重,可以设定默认权重以及有状态服务的权重。
类型: json
版本要求: >=v1.6.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.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:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


跳过 readiness-gate

名称: service.cloud.tencent.com/readiness-gate-skip
说明:
开启后,控制器健康检查时,将跳过 readiness-gate 的检查。
类型: bool
版本要求: >=v1.8.1
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/readiness-gate-skip: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


优雅停机

名称: service.cloud.tencent.com/enable-grace-shutdown
说明:
支持 CLB 直连模式的优雅停机。Pod 被删除,此时 Pod 里有 DeletionTimestamp,且状态置为 Terminating。此时调整 CLB 到该 Pod 的权重为 0。
仅在直连模式下支持,需要配合使用 service.cloud.tencent.com/direct-access。
v2.2.0 版本开始废弃,默认开启。
详情参考 Service 优雅停机
类型: bool
版本要求: >=v1.5.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/enable-grace-shutdown: 'true'
service.cloud.tencent.com/direct-access: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


优雅停机 tkex

名称: service.cloud.tencent.com/enable-grace-shutdown-tkex
说明:
支持 CLB 直连模式的优雅退出。Endpoint 对象中 endpoints 是否 not-ready,将 not-ready 的 CLB 后端权重置为 0。
仅在直连模式下支持,需要配合使用 service.cloud.tencent.com/direct-access。
v2.2.0 版本开始废弃,默认开启。
详情参考 Service 优雅停机
类型: bool
版本要求: >=v1.5.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/enable-grace-shutdown-tkex: 'true'
service.cloud.tencent.com/direct-access: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer


优雅删除

名称: service.cloud.tencent.com/enable-grace-deletion
说明:
开启后,运行时等待控制器将所有 Pod 的权重调整为 0 后,再删除后端。
仅在直连模式下支持,需要配合使用 service.cloud.tencent.com/direct-access。
类型: bool
版本要求: >=v2.4.0
使用示例:
apiVersion: v1
kind: Service
metadata:
annotations:
service.cloud.tencent.com/enable-grace-deletion: 'true'
service.cloud.tencent.com/direct-access: 'true'
name: example
spec:
ports:
- name: http
port: 80
protocol: TCP
targetPort: 80
selector:
app: example
type: LoadBalancer