使用 Annotation 配置负载均衡服务

服务（Serivce）支持通过注解（Annotation）实现更加丰富的四层负载均衡（CLB）能力。本文主要介绍使用 Annotation 配置负载均衡服务的主要场景和配置方法。

背景信息

当您在容器服务集群中配置 Service 时，允许通过配置 YAML 文件中特定的注解，新建或复用四层负载均衡实例。

新建和复用四层负载均衡实例的主要区别如下表所示。

LoadBalancer 类型的 Service 会在如下场景触发调谐：

• 创建/删除/修改 Service 时，后端的变化（例如：Pod IP 改变，新增/下线 Pod）。
• 控制器的 Pod 重启。

因此，需要注意以下事项：

• 在负载均衡控制台手动修改 CLB 实例配置时，控制器无法感知。因此，控制器无法将负载均衡控制台中的修改写入 Service 的 Annotation 中。当 Service 触发调谐时，在负载均衡控制台上修改的配置可能会被控制器根据 Annotation 中的配置刷新。
• CLB 配置项的处理逻辑如下：
  • 如果在 Annotation 中有相关配置（例如开启 ACL 访问控制），则 CLB 的配置和 Annotation 保持一致。在负载均衡控制台手动修改 CLB 的配置后，CLB 的配置直到 Service 下次调谐前，都与负载均衡控制台所做的修改保持一致。但在 Service 再次调谐时，将会被 Annotation 中的设置刷新。
  • 如果在 Annotation 中没有相关配置，CLB 的配置和负载均衡控制台上的配置一致，Service 的调谐不会修改负载均衡控制台上的设置。
  • 如果 Annotation 中有相关配置（例如开启 ACL 访问控制），接着删除了相关的 Annotation，则 CLB 的相关功能维持现状（例如 ACL 依然处于开启状态）。如果希望通过 Annotation 关闭相关功能，需要在 Annotation 中将相关功能的配置设置为关闭状态，而不是直接删除对应的 Annotation。

使用限制

• 请勿擅自在 CLB 控制台上更改通过创建负载均衡服务维护的 CLB 实例、监听器、后端服务器组和转发规则，否则将造成集群中的负载均衡服务异常，须自行承担责任。
• 请勿修改监听器和后端服务器组的名称中带有k8s_前缀的内容。
• 请勿修改转发规则描述中带有k8s_前缀的内容。
• 若在 CLB 控制台上修改负载均衡服务指定或维护的资源和配置（例如：转发规则），可能存在配置被覆盖的风险。
• 使用负载均衡（Cloud Load Balancer，CLB）产品，会产生云基础资源使用费用。详细信息，请参见 负载均衡产品计费。

创建服务

对接已有 CLB 实例

使用如下 YAML 配置，创建服务并对接已有的负载均衡实例。

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

新建 CLB 实例

使用如下 YAML 配置，创建服务并同时创建新的负载均衡实例。

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-name: "clb-demo"
    # 非必填，新创建的负载均衡实例名称
    service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id: "subnet-mizw4xqzpssg5smt1b******"
    # 必填，负载均衡实例所属的子网 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-address-type: "PUBLIC"
    # 非必填，负载均衡实例的网络类型。不设置时，默认网络类型为 PUBLIC
    service.beta.kubernetes.io/volcengine-loadbalancer-isp-type: "BGP"
    # 非必填，负载均衡实例的线路类型
    service.beta.kubernetes.io/volcengine-loadbalancer-billing-type: "2"
    # 非必填，负载均衡实例计费类型
    service.beta.kubernetes.io/volcengine-loadbalancer-eip-billing-type: "3"
    # 非必填，公网 IP（EIP）计费类型
    service.beta.kubernetes.io/volcengine-loadbalancer-bandwidth: "25" 
    # 非必填，公网类型负载均衡实例需要指定公网 IP（EIP）带宽峰值。  
    service.beta.kubernetes.io/volcengine-loadbalancer-ip-version: "ipv4"
    # 非必填，负载均衡实例的 IP 地址类型，目前仅支持 IPv4
    service.beta.kubernetes.io/volcengine-loadbalancer-spec: "small_1"
    # 非必填，负载均衡实例的规格
    service.beta.kubernetes.io/volcengine-loadbalancer-sync-fields: "spec"
    # 更新 CLB 实例规格时必填，填写该字段为 spec 时，会根据 loadbalancer-spec 字段更新 CLB 的实例规格
    service.beta.kubernetes.io/volcengine-loadbalancer-master-zone-id: "cn-beijing-a"
    # 非必填，负载均衡实例的主可用区 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-slave-zone-id: "cn-beijing-b"
    # 非必填，负载均衡实例的备可用区 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-modification-protection-status: "ConsoleProtection"
    # 非必填，负载均衡实例的删除保护功能
    service.beta.kubernetes.io/volcengine-loadbalancer-eip-BandwidthPackageId: "bwp-2d63yyj3ki4u858oz***" 
    # 非必填，共享带宽资源包 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP # 端口通信协议，支持 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

新建 CLB 实例并对接 VCI 工作负载

使用如下 YAML 配置，创建一个新的负载均衡服务并关联以弹性容器实例（VCI）方式部署的工作负载。

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-name: "clb-demo"
    # 非必填，新创建的负载均衡实例名称
    service.beta.kubernetes.io/volcengine-loadbalancer-subnet-id: "subnet-mizw4xqzpssg5smt1b******"   
    # 必填，负载均衡实例所属的子网 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-pass-through: "true"
    # 必填，开启负载均衡器直通 Pod 模式。关联 VCI 工作负载时必须开启
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP # 端口通信协议，支持 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

高级配置

配置调度策略

负载均衡服务支持通过 Annotation 配置和选择 CLB 实例的监听器，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-scheduler: "wrr"
    # 非必填，监听器的调度算法
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

配置健康检查

负载均衡服务支持通过 Annotation 配置监听器的健康检查功能，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-flag: "on" 
    # 必填，是否开启健康检查
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-connect-timeout: "2" 
    # 非必填，等待健康检查的响应时间
    service.beta.kubernetes.io/volcengine-loadbalancer-health-check-interval: "2" 
    # 非必填，健康检查的时间间隔
    service.beta.kubernetes.io/volcengine-loadbalancer-healthy-threshold: "3" 
    # 非必填，后端服务器正常的健康检查次数
    service.beta.kubernetes.io/volcengine-loadbalancer-unhealthy-threshold: "3" 
    # 非必填，后端服务器异常的健康检查次数
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

配置访问控制

负载均衡服务支持通过 Annotation 配置监听器的访问控制功能，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-status: "on"
    # 必填，是否开启监听器的访问控制
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-type: "white"
    # 必填，开启访问控制的方式（白名单、黑名单）
    service.beta.kubernetes.io/volcengine-loadbalancer-acl-id: "acl-3cj44nv0jhhxc6c6rrtet****,acl-2febxt4pu0zy85oxruw0t****"
    # 必填，监听器绑定的访问控制策略组 ID
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

配置直通 Pod 模式

负载均衡服务支持通过 Annotation 配置和选择监听器，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-pass-through: "true"
    # 必填，是否开启负载均衡器直通 Pod 模式
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

配置 Proxy Protocol 源 IP 透传

负载均衡服务支持通过 Annotation 配置监听器的 Proxy Protocol 源 IP 透传功能，示例和说明如下：

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/volcengine-loadbalancer-id: "clb-mim02n8g5kw05smt1b******"
    # 必填，已有负载均衡实例的 ID
    service.beta.kubernetes.io/volcengine-loadbalancer-proxy-protocol: "standard"
    # 必填，开启 Proxy Protocol 源 IP 透传
  name: clb-service # 服务的名称
  namespace: default # 服务所属的命名空间
spec:
  externalTrafficPolicy: Cluster
  selector:
    app: nginx # 通过标签选择器将服务与后端容器组（Pod）绑定
  ports:
  - name: test # 端口映射策略命名
    port: 80 # 服务端口
    protocol: TCP  # 端口通信协议 TCP/UDP
    targetPort: 80 # 容器端口
  type: LoadBalancer # 服务的类型

Annotation 说明如下表所示。

相关文档

• 通过 Annotation 配置四层负载均衡时出现 “lb is provisioning”事件
• 通过 Annotation 配置四层负载均衡时出现 “loadbalancer for service not found”事件
• 通过 Annotation 配置四层负载均衡时出现 “InvalidServerGroupListener.InUse”事件