LoadBalancer Service Annotation说明

更新时间：2024-07-09

LoadBalancer Service Annotation说明

在使用CCE提供的LoadBalancer类型的Service资源时（下文简称LB Service），可以通过在Annotation中添加注解的方式来使用一些高级配置。

Annotation位于Service完整YAML的以下位置：

apiVersion: v1
kind: Service
metadata:
  name: service-example
  annotations:
    prometheus.io/scrape: "true"
    service.beta.kubernetes.io/cce-load-balancer-internal-vpc: "true" # LB Service 不分配 EIP
……

LoadBalancer Service可以使用以下高级配置项：

指定使用的应用型BLB

取值说明

若设置，CCE将在指定的应用型BLB上配置LB Service规则；

若缺失，CCE会新建一个应用型BLB，并自动设置该Annotation为新建应用型BLB的ID。

注意事项

只支持应用型BLB；
需要自行先创建好应用型BLB，BLB应在集群所在的VPC内；
修改或删除可能会导致BLB泄露，修改LB Service资源对象时不要覆盖或丢失该Annotation。

示例

service.beta.kubernetes.io/cce-load-balancer-id: lb-12345678

LB Service 根据 Label 选择挂载目标节点

取值说明

Service 可以通过注解 service.beta.kubernetes.io/cce-load-balancer-backend-label: "k1=v1, k2=v2 ..." ，选择 Label 匹配的节点进行绑定；

若未添加标签，Service 后端会排空，相应的 Service 描述中会上报事件。

注意事项

多个 Label 以逗号分隔，例如 "k1=v1,k2=v2" ，多个Label之间是 And 关系；
当注解为 service.beta.kubernetes.io/cce-load-balancer-backend-label: "k1=v1, k2=v2 ..." 的选择器没有选取到任何节点的时候，服务的后端将会被排空，会使得服务中断。使用此功能时，需要对集群节点的 Label 有一定的管理；
添加符合要求的节点或变更存量节点也会触发更新；
Service Local 模式本身就具有节点选择能力，所以请不要在 Service Local 模式下，使用指定接入层后端的能力。

示例

apiVersion: v1
kind: Service
metadata:
  name: service-example
  annotations:
    service.beta.kubernetes.io/cce-load-balancer-backend-label: k1=v1, k2=v2 # 多个Label之间是 And 关系
......

指定EIP地址/在删除时保留EIP资源

取值说明

该配置在Spec字段中，不在Annotation中。

在spec.loadBalancerIP配置一个EIP地址，CCE将会把该EIP绑定在LB Service对应的应用型BLB上；并且在删除LB Service资源时，也不会删除该EIP资源；

若缺失，CCE会默认新建一个EIP，但不会设置这里的字段，该字段将始终保持为空。

注意事项

可以指定预付费EIP资源；
修改或删除可能会导致EIP泄漏，修改LB Service资源对象时不要覆盖或丢失该配置；
如果在创建时忘记添加，可以在删除前补上这一条，在删除前添加依然有效；
如果LB Service上已经使用了某个EIP，更改该Annotation不会更换应用型BLB上绑定的EIP地址，需要用户自行换绑。

示例

kind: Service
apiVersion: v1
metadata:
    name: test
spec:
    type: LoadBalancer
    loadBalancerIP: 8.8.8.8
......

设置LB Service关联的BLB名称

取值说明

用于设置该LB Service关联的BLB的名称，否则使用默认生成的名称格式（集群ID/svc/命名空间/Service名称）来创建BLB。

有时，默认名称会超出最长限制（64个字符），此时需要手动设置该Annotation的值来指定BLB的名称。

注意事项

不要和已有BLB的名称相同，否则可能发生混淆，导致误用BLB的情况发生。

示例

service.beta.kubernetes.io/cce-load-balancer-lb-name: cce-test-name

在删除时保留应用型BLB资源

取值说明

若值为true，则在该LB Service资源对象被删除时，关联的应用型BLB资源不会被删除；

若缺失，或值是false，则在该LB Service资源对象被删除时，关联的应用型BLB将会被删除。

注意事项

如果在创建时忘记添加该Annotation，可以在删除前补上这一条，在删除前添加依然有效。

示例

service.beta.kubernetes.io/cce-load-balancer-reserve-lb: "true"

指定新建BLB所在子网

取值说明

若值为集群所在VPC的有效子网ID，则CCE会在需要新建应用型BLB时，将应用型BLB创建在该子网中；

若缺失，CCE将会自行选择创建应用型BLB的子网。

注意事项

只针对新建应用型BLB有效。

示例

service.beta.kubernetes.io/cce-load-balancer-subnet-id: "sbn-12345678"

设置LB Service仅供VPC内网访问

取值说明

若值为true，CCE不会为其创建和设置EIP地址；

若缺失，或值是false，CCE会为应用型BLB分配和绑定EIP。

注意事项

如果应用型BLB上已经绑定了EIP，在添加该Annotation后，EIP不会被后台解绑，用户需要自行解绑。

示例

service.beta.kubernetes.io/cce-load-balancer-internal-vpc: "true"

自定义EIP配置

取值说明

LB Service在未指定EIP时且未配置仅供VPC内网访问时，会创建EIP资源。

可以在Annotation中设置新建EIP的配置：

指定计费方式：

支持ByTraffic（按流量计费）和ByBandwidth（按带宽计费）。

对应的Annotation为service.beta.kubernetes.io/cce-elastic-ip-billing-method。

指定线路类型：

支持增强型 BGP 与标准型 BGP 两种线路类型，CCE 默认支持对应的Annotation为service.beta.kubernetes.io/cce-elastic-ip-route-type，其中 BGP_S 代表增强型 BGP，BGP 代表标准型 BGP，ChinaTelcom 代表电信单线，ChinaUnicom 代表联通单线，ChinaMobile 代表移动单线，使用示例如下：

示例

# 增强型 BGP
service.beta.kubernetes.io/cce-elastic-ip-route-type:'BGP_S'

指定带宽：

取值范围为[1, 5000]。

对应的Annotation为service.beta.kubernetes.io/cce-elastic-ip-bandwidth-in-mbps。

注意事项

新建EIP都是后付费类型，暂不支持使用Annotation指定创建预付费EIP；
只针对新建EIP有效；
当带宽额度大小不为合法数字时，会上报警告事件；
当您没有添加带宽额度注解时，CCE 会为您默认创建并绑定带宽额度大小为100，计费方式为按流量计费的标准型 EIP；
境外部分区域暂不支持增强型 BGP 创建，详情请见；
带宽额度在不同线路类型和计费类型组合下，取值范围不同，如下表所示：

线路类型	标准型 BGP	增强型 BGP
流量计费	[1, 200]	[100, 1000]
带宽计费	[1, 500]	[100, 5000]

在不满足以下四种条件的情况下，会导致创建 EIP 失败：

线路类型	标准型 BGP 使用说明	增强型 BGP 使用说明
流量计费	需要添加如下带宽范围注解，且注解取值范围是[1, 200] `service.beta.kubernetes.io/cce-elastic-ip-bandwidth-in-mbps: "99"` `service.beta.kubernetes.io/cce-elastic-ip-billing-method: ByTraffic` `service.beta.kubernetes.io/cce-elastic-ip-route-type: BGP`	需同时添加如下带宽范围和线路类型注解，且注解取值范围是[100, 1000] `service.beta.kubernetes.io/cce-elastic-ip-bandwidth-in-mbps: "200"` `service.beta.kubernetes.io/cce-elastic-ip-billing-method: ByTraffic` `service.beta.kubernetes.io/cce-elastic-ip-route-type: BGP_S`
带宽计费	需同时添加如下带宽范围和计费类型注解，且注解取值范围是[1, 500] `service.beta.kubernetes.io/cce-elastic-ip-bandwidth-in-mbps: "99"` `service.beta.kubernetes.io/cce-elastic-ip-billing-method: ByBandwidth` `service.beta.kubernetes.io/cce-elastic-ip-route-type: BGP`	需同时添加如下带宽范围、线路类型和计费类型注解，且注解取值范围是[100, 5000] `service.beta.kubernetes.io/cce-elastic-ip-bandwidth-in-mbps: "5000"` `service.beta.kubernetes.io/cce-elastic-ip-billing-method: ByBandwidth` `service.beta.kubernetes.io/cce-elastic-ip-route-type: BGP_S`

隐藏应用型BLB内网IP地址

取值说明

若值为true，即可在Service的Status中不再展示应用型BLB内网IP字段；

若缺失，或值是false，则Service的Status中正常展示应用型BLB内网IP字段。

示例

service.beta.kubernetes.io/cce-load-balancer-external: "true"

设置BLB默认挂载的最大后端数

取值说明

该Annotation用于限制LB Service挂载的后端数目。

默认是200。

注意事项

如果Service的Spec.ExternalTrafficPolicy值为Local，或使用Pod直连模式，请设置该值确保比集群节点数大。否则未挂载到BLB后端的节点或Pod将无法接收到流量。

示例

service.beta.kubernetes.io/cce-load-balancer-rs-max-num: 500

使用Pod直连模式

取值说明

添加Annotationservice.beta.kubernetes.io/cce-load-balancer-backend-type: "eni"，将会使用Pod直连模式配置应用型BLB，即流量直接从应用型BLB到达后端Pod。

注意事项

不可以在已有的Annotation上添加该Annotation来将其切换成Pod直连模式，如果有需要，请新建一个LB Service；反之亦然。

示例

service.beta.kubernetes.io/cce-load-balancer-backend-type: "eni"

配置实时更新

取值说明

若值为true，CCE会在修改监听器配置、健康检查规则、EIP 带宽配置之后，立即更新 BLB 和 EIP 相关配置。

注意事项

CCE不会自动添加该Annotation，需要自行按需添加；

示例

service.kubernetes.io/cce-update-in-time: "true"

使用专属BLB集群

取值说明

当用户存在BLB专属集群时，后端会优先将应用型BLB创建在BLB专属集群上。

使用以下Annotation可以指定是否使用专属集群，以及使用的专属集群ID：

使用共享集群创建应用型BLB

使用该Annotationservice.beta.kubernetes.io/no-use-blb-cluster-l4: "true"之后，应用型BLB将创建在共享集群上。

指定创建在L4专属集群上

使用该Annotationservice.beta.kubernetes.io/no-use-blb-cluster-l4: "test"之后，应用型BLB将创建在指定的专属BLB集群上。

注意事项

有了专属集群之后，如果没有显式添加Annotation，将由后台自动选择所在的专属BLB集群。

示例

service.beta.kubernetes.io/no-use-blb-cluster-l4: "true"

扩展Service端口协议

取值说明

扩展协议配置用于补充Spec中规定的端口的协议配置，这些扩展配置将作用于应用型BLB的监听器上。

扩展协议中配置的端口，应首先存在于Spec配置中，否则扩展协议配置不会生效。

扩展协议内容在service.beta.kubernetes.io/cce.listener.customized-listener Annotation下，完整配置内容请参考示例。每种协议能配置的参数如下：

扩展TCP协议

参数名称	描述
protocol	TCP
timeout	非必填。TCP会话超时时间。
scheduler	负载均衡方法。支持"RoundRobin"、"LeastConnection"、"Hash"，默认"RoundRobin"。

扩展UDP协议

参数名称	描述
protocol	UDP
timeout	非必填。UDP会话超时时间。
scheduler	负载均衡方法。支持"RoundRobin"、"LeastConnection"、"Hash"，默认"RoundRobin"。

扩展TCP-SSL协议

参数名称	描述
protocol	TCP-SSL
timeout	非必填。TCP-SSL服务端超时时间。默认"30"。
scheduler	非必填。负载均衡方法。支持"RoundRobin"、"LeastConnection"、"Hash"，默认"RoundRobin"。
serverCertIDs	必填。服务端证书ID链，逗号分隔。
encryptionType	非必填。加密选项，默认tls_cipher_policy_default。支持：tls_cipher_policy_default/tls_cipher_policy_1_1/tls_cipher_policy_1_2/tls_cipher_policy_1_2_secure/userDefind。
encryptionProtocols	非必填。加密协议，当encryptionType值为userDefind时协议类型列表，是以"tlsv10"、"tlsv11"、"tlsv12"三种协议组合形成的字符串列表。
appliedCiphers	非必填。加密套件。不同加密套件用冒号":"隔开。
dualAuth	非必填。是否开启双向认证。默认"false"。
clientCertIDs	非必填。开启双向认证的客户端证书链。

扩展HTTP协议

参数名称	描述
protocol	HTTP
scheduler	非必填。负载均衡方法。支持"RoundRobin"、"LeastConnection"，默认"RoundRobin"。
timeout	非必填。HTTP服务端超时时间。默认"30"。
redirectPort	非必填。HTTPS重定向端口。
disableXForwardedForHeader	非必填。是否关闭XForwardedFor头。默认"false"。
enableXForwardedProtoHeader	非必填。是否开启XForwardedProto头。默认"false"。
enableKeepSession	非必填。是否开启会话保持。默认"false"。
keepSessionType	非必填。会话保持的Cookie处理方式，当且仅当开启会话保持时有效，支持"insert"/"rewrite"，默认"insert"。
keepSessionTimeout	非必填。会话保持超时时间。
KeepSessionCookieName	非必填。会话保持类型为"rewrite"时Cookie的名称。

扩展HTTPS协议

参数名称	描述
protocol	HTTPS
scheduler	非必填。负载均衡方法。支持"RoundRobin"、"LeastConnection"，默认 "RoundRobin"。
timeout	非必填。HTTP服务端超时时间。默认"30"。
serverCertIDs	必填。服务端证书ID链，逗号分隔。
encryptionType	非必填。加密选项，默认tls_cipher_policy_default。支持：tls_cipher_policy_default/tls_cipher_policy_1_1/tls_cipher_policy_1_2/tls_cipher_policy_1_2_secure/userDefind。
encryptionProtocols	非必填。加密协议，当encryptionType值为userDefind时协议类型列表，是以"tlsv10"、"tlsv11"、"tlsv12"三种协议组合形成的字符串列表。
appliedCiphers	非必填。加密套件。不同加密套件用冒号":"隔开。
dualAuth	非必填。是否开启双向认证。默认"false"。
clientCertIDs	非必填。开启双向认证的客户端证书链。
disableXForwardedForHeader	非必填。是否关闭XForwardedFor头。默认"false"。
enableXForwardedProtoHeader	非必填。是否开启XForwardedProto头。默认"false"。
enableKeepSession	非必填。是否开启会话保持。默认"false"。
keepSessionType	非必填。会话保持的Cookie处理方式，当且仅当开启会话保持时有效，支持"insert"/"rewrite"，默认"insert"。
keepSessionTimeout	非必填。会话保持超时时间。
KeepSessionCookieName	非必填。会话保持类型为"rewrite"时Cookie的名称。

注意事项

CCE不会自动添加该Annotation，需要自行按需添加；
只有Spec中的端口协议为TCP时，才可以在为其添加TCP、TCP-SSL、HTTP、HTTPS扩展协议配置；如果端口在Spec中为UDP协议，则只能为其添加UDP扩展协议配置；
修改扩展协议类型，或是删除某个端口的扩展协议配置，将会导致应用型BLB对应端口的监听器重建，请谨慎操作。

示例

service.beta.kubernetes.io/cce.listener.customized-listener: |-
      {
         "81":{
            "protocol":"TCP",
            "timeout":"31",
            "scheduler":"Hash"
         },
         "82":{
            "protocol":"UDP",
            "timeout":"31",
            "scheduler":"Hash"
         },
         "83":{
            "protocol":"HTTP",
            "redirectPort":"84",
            "timeout":"31",
            "scheduler":"LeastConnection",
            "enableKeepSession":"true",
            "keepSessionType":"rewrite",
            "disableXForwardedForHeader": "true",
            "enableXForwardedProtoHeader": "true"
         },
         "84":{
            "protocol":"HTTPS",
            "serverCertIDs":"cert-5bqpykggjzmi",
            "timeout":"31",
            "scheduler":"LeastConnection",
            "enableKeepSession":"true",
            "keepSessionType":"rewrite",
            "encryptionType": "userDefind",
            "encryptionProtocols": "tlsv10, tlsv11, tlsv12",
            "appliedCiphers": "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA"
         },
         "85":{
            "protocol":"TCP-SSL",
            "serverCertIDs":"cert-5bqpykggjzmi",
            "timeout":"31",
            "scheduler":"LeastConnection",
            "encryptionType": "userDefind",
            "encryptionProtocols": "tlsv10, tlsv11, tlsv12",
            "appliedCiphers": "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA"
         }
      }

示例 LoadBalancer Service

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/cce.listener.customized-listener: |-
      {
         "81":{
            "protocol":"TCP",
            "timeout":"31",
            "scheduler":"Hash"
         },
         "82":{
            "protocol":"UDP",
            "timeout":"31",
            "scheduler":"Hash"
         },
         "83":{
            "protocol":"HTTP",
            "redirectPort":"84",
            "timeout":"31",
            "scheduler":"LeastConnection",
            "enableKeepSession":"true",
            "keepSessionType":"rewrite",
            "disableXForwardedForHeader": "true",
            "enableXForwardedProtoHeader": "true"
         },
         "84":{
            "protocol":"HTTPS",
            "serverCertIDs":"cert-5bqpykggjzmi",
            "timeout":"31",
            "scheduler":"LeastConnection",
            "enableKeepSession":"true",
            "keepSessionType":"rewrite",
            "encryptionType": "userDefind",
            "encryptionProtocols": "tlsv10, tlsv11, tlsv12",
            "appliedCiphers": "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA"
         },
         "85":{
            "protocol":"TCP-SSL",
            "serverCertIDs":"cert-5bqpykggjzmi",
            "timeout":"31",
            "scheduler":"LeastConnection"
         }
      }
  name: service-example
  namespace: default
spec:
  clusterIP: 172.16.27.138
  externalTrafficPolicy: Cluster
  ports:
    - name: nginx-1
      nodePort: 30710
      port: 81
      protocol: TCP
      targetPort: 80
    - name: nginx-2
      nodePort: 30792
      port: 82
      protocol: UDP
      targetPort: 80
    - name: nginx-3
      nodePort: 31906
      port: 83
      protocol: TCP
      targetPort: 80
    - name: nginx-4
      nodePort: 32514
      port: 84
      protocol: TCP
      targetPort: 80
    - name: nginx-5
      nodePort: 31749
      port: 85
      protocol: TCP
      targetPort: 80
    - name: nginx-6
      nodePort: 31569
      port: 86
      protocol: TCP
      targetPort: 80
  selector:
    app: nginx
  sessionAffinity: None
  type: LoadBalancer

设置服务器组动态权重

取值说明

添加该Annotation后，在LoadBalancer Service的ExternalTrafficPolicy为Local模式且未开启Pod直连时，CCE根据节点上的Pod数量来为BLB的后端服务器设置权重；否则，CCE为每个后端节点设置均等权重。

这可以避免在ExternalTrafficPolicy为Local模式下产生Pod负载不均衡问题。

注意事项

CCE不会自动添加该Annotation，用户需要按需自行添加。
在总体Pod数较少时且平均负载较高时，滚动更新Pod时可能会导致某些Pod负载短时过高；请避免在这种情况下使用该配置项。

示例

service.beta.kubernetes.io/cce-dynamic-backend-server-weight: 'true'

设置服务器组健康检查

取值说明

若设置，CCE将会给BLB对应的服务器组设置对应配置的健康检查；

若缺失，CCE将会给BLB对应的服务器组设置默认配置的健康检查。

注意事项

默认健康检查配置可能会导致检查失败，建议自定义健康检查配置，更多信息可参考负载均衡BLB健康检查介绍。

示例

# LB Service 的各个端口可能使用不同协议，因此需要单独对每个端口来设置健康检查

## 1、Service 监听端口为 80，健康检查协议为 TCP
service.beta.kubernetes.io/cce.listener.customized-health-check:  |-
      {
         "80":{
            "healthCheck":"TCP", #健康检查协议
            "healthCheckTimeoutInSecond":"3", #响应超时时间
            "healthCheckIntervalInSecond":"3", #健康检查间隔
            "healthCheckDownRetry":"3", #不健康阈值
            "healthCheckUpRetry": "3" #健康阈值
         }
      }
      
## 2、Service 监听端口为 80，健康检查协议为 UDP
 service.beta.kubernetes.io/cce.listener.customized-health-check:  |-
      {
         "80":{
            "healthCheck":"UDP",
            "udpHealthCheckString":"\00\01\01\00\00\01\00\00\00\00\00\00\05baidu\03com\00\00\01\00\01", #检查字符串
            "healthCheckTimeoutInSecond":"3",
            "healthCheckIntervalInSecond":"3",
            "healthCheckDownRetry":"3",
            "healthCheckUpRetry": "3"
         }
      }
      
## 3、Service 监听端口为 80，健康检查协议为 ICMP
 service.beta.kubernetes.io/cce.listener.customized-health-check:  |-
      {
         "80":{
            "healthCheck":"ICMP",
            "healthCheckTimeoutInSecond":"3",
            "healthCheckIntervalInSecond":"3",
            "healthCheckDownRetry":"3",
            "healthCheckUpRetry": "3"
         }
      }
      
## 4、Service 监听端口为 80，健康检查协议为 HTTP
service.beta.kubernetes.io/cce.listener.customized-health-check:  |-
      {
         "80":{
            "healthCheck":"HTTP",
            "healthCheckHost": "baidu.com", #Host头域
            "healthCheckPort":"80", #检查端口
            "healthCheckUrlPath":"/", #检查路径
            "healthCheckTimeoutInSecond":"2",
            "healthCheckIntervalInSecond":"2",
            "healthCheckDownRetry":"3",
            "healthCheckUpRetry": "2",
            "healthCheckNormalStatus": "http_2xx|http_3xx" #正常状态码，可选项有“http_2xx”、“http_3xx”、“http_4xx”、“http_5xx”，支持多选
         }
      }

使用直连 Pod 模式 LoadBalancer Service

通过 CCE 使用 K8S Ingress

百度智能云

容器引擎 CCE

容器引擎 CCE

LoadBalancer Service Annotation说明

LoadBalancer Service Annotation说明

指定使用的应用型BLB

LB Service 根据 Label 选择挂载目标节点

指定EIP地址/在删除时保留EIP资源

设置LB Service关联的BLB名称

在删除时保留应用型BLB资源

指定新建BLB所在子网

设置LB Service仅供VPC内网访问

自定义EIP配置

隐藏应用型BLB内网IP地址

设置BLB默认挂载的最大后端数

使用Pod直连模式

配置实时更新

使用专属BLB集群

扩展Service端口协议

设置服务器组动态权重

设置服务器组健康检查