BLB Ingress Annotation说明

在使用CCE提供的BLB类型的Ingress资源时，可以通过在Annotation中添加注解的方式来使用Ingress的一些高级配置。

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

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/cce.ingress.blb-cert-id: cert-5bqpykggjzmi
    kubernetes.io/cce.ingress.blb-id: lb-13ddfb9e
    kubernetes.io/cce.ingress.eip: 106.13.169.172
    kubernetes.io/ingress.class: cce
……

Ingress可以使用以下高级配置项：

指定当前Ingress由CCE托管

取值说明

若值为cce，表示当前Ingress由CCE负责实现；

若缺失，或值不是cce，则CCE不会处理该Ingress。

注意事项

• 通过CCE控制台创建的BLB类型Ingress会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行添加该Annotation。

示例

kubernetes.io/ingress.class: cce

删除Ingress时保留应用型BLB/EIP资源

取值说明

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

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

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 如果在创建时忘记添加该Annotation，可以在删除前补上这一条，在删除前添加依然有效。

示例

kubernetes.io/cce.ingress.keep-iaas-resource: "true"

设置Ingress关联的BLB名称

取值说明

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

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

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 不要和已有BLB的名称相同，否则容易混淆，导致误用BLB的情况发生。

示例

kubernetes.io/cce.ingress.blb-name: cce-test-name

为Ingress分配IPv6地址

取值说明

若值为true时，会为关联的应用型BLB分配IPv6地址；

若值是false，CCE不会为其分配IPv6地址，并且会摘除应用型BLB上绑定的IPv6地址。

注意事项

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

示例

kubernetes.io/cce.ingress.enable-ipv6: "true"

指定Ingress使用的应用型BLB

取值说明

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

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

注意事项

• 只支持应用型BLB；
• 需要自行先创建好应用型BLB，BLB应在集群所在的VPC内；
• 通过CCE控制台创建的BLB类型Ingress，如果选择了某个已有应用型BLB，会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation；
• 修改或删除可能会导致BLB泄露，修改Ingress资源对象时不要覆盖或丢失该Annotation。

示例

kubernetes.io/cce.ingress.blb-id: lb-12345678

设置Ingress仅供VPC内网访问

取值说明

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

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

注意事项

• 通过CCE控制台创建的BLB类型Ingress，当选择内网访问类型时，会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation；
• 如果应用型BLB上已经绑定了EIP，在添加该Annotation后，EIP不会被后台解绑，用户需要自行解绑。

示例

kubernetes.io/cce.ingress.internal: "true"

新建Ingress指定新建BLB所在子网

取值说明

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

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

注意事项

• 通过CCE控制台创建的BLB类型Ingress会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation。

示例

kubernetes.io/cce.ingress.vpc-subnet-id: sbn-adfEsDzs

新建Ingress指定使用EIP

取值说明

若值为某EIP的地址，CCE将会把该EIP绑定在Ingress对应的应用型BLB上；

若缺失，CCE会默认新建一个EIP，并自动设置该Annotation。

注意事项

• 通过CCE控制台创建的BLB类型Ingress，在指定公网IP后会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation；
• 修改或删除可能会导致EIP泄漏，修改Ingress资源对象时不要覆盖或丢失该Annotation；
• 如果Ingress上已经使用了某个EIP，更改该Annotation不会更换应用型BLB上绑定的EIP地址，需要用户自行换绑。

示例

kubernetes.io/cce.ingress.eip: 1.2.3.4

新建Ingress指定新建EIP带宽

取值说明

设置新建的Ingress使用的EIP带宽；

若该Annotation缺失，则默认新建EIP带宽为100Mbps;

取值范围为[1, 5000]。

示例

kubernetes.io/cce.ingress.eip-bandwidth-in-mbps: "99"

• 指定计费方式：

支持ByTraffic（按流量计费）和ByBandwidth（按带宽计费）。对应的Annotation为kubernetes.io/cce.ingress.eip-billing-method。

• 指定线路类型：

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

示例

# 增强型 BGP
kubernetes.io/cce.ingress.eip-route-type:'BGP_S' 

注意事项

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

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

新建Ingress指定新建EIP计费方式

取值说明

若值为ByBandwidth，在新建EIP时按带宽计费；

若值为ByTraffic，在新建EIP时按流量计费；

若缺失，默认采用 ByBandwidth 计费方式。

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 仅在新建EIP时有效，不会修改已有EIP的计费方式。

示例

kubernetes.io/cce.ingress.eip-billing-method: ByBandwidth

新建Ingress指定访问超时时间

取值说明

在新建Ingress时配置HTTP和HTTPS请求的超时时间。

注意事项

• 取值范围：[1, 3600]；
• 通过CCE控制台创建的BLB类型Ingress，在设置超时时间后会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation。

示例

kubernetes.io/cce.ingress.timeout-in-seconds: "20"

限制BLB默认挂载的后端数

取值说明

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

注意事项

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

示例

kubernetes.io/cce.ingress.max-backend-count: 50

是否支持HTTPS

取值说明

若该Annotation值为true，CCE会为其创建HTTPS相关配置；

若缺失，或值为false，CCE不会管理关联应用型BLB上的HTTPS配置。

注意事项

• 通过CCE控制台创建的BLB类型Ingress，在开启HTTPS后会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation；
• 若缺失，或值为false，CCE不会管理关联应用BLB上的HTTPS配置，也就是说，如果应用型BLB上已经有HTTPS监听器和转发规则，此时控制器不会删除这些HTTPS配置，需要用户手动处理。

示例

kubernetes.io/cce.ingress.https: "true"

新建Ingress支持HTTP重定向

取值说明

若值为true，CCE会配置将访问HTTP端口的流量转发到HTTPS端口上去。

注意事项

• 通过CCE控制台创建的BLB类型Ingress，在开启HTTP重定向后会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation。

示例

kubernetes.io/cce.ingress.http-redirect: "true"

新建Ingress指定HTTPS证书

取值说明

若在新建Ingress时希望使用HTTPS，则同时需要设定HTTPS证书；

该Annotation的值应为百度云上已经申请到的证书ID。

注意事项

• 通过CCE控制台创建的BLB类型Ingress，在选择HTTPS证书后会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation。

示例

kubernetes.io/cce.ingress.blb-cert-id: xs-asdfDESz

设置HTTP、HTTPS规则

取值说明

对于Ingress Spec中的规则，CCE默认将其创建为HTTP转发规则，而不是HTTPS转发规则。

使用kubernetes.io/cce.ingress.http-rules和kubernetes.io/cce.ingress.https-rules这两条Annotation可以显式指明某条规则是HTTP还是HTTPS规则。

注意事项

• 通过CCE控制台创建的BLB类型Ingress，会自带该Annotation；
• 如果在集群中使用YAML自行创建BLB类型Ingress，需要自行按需添加该Annotation。

示例

kubernetes.io/cce.ingress.http-rules: >-
      [
          { "host":"ad.com",
            "http":{
                "paths":[
                    {"path":"/*","backend":{"serviceName":"service-example","servicePort":80}}
                ]
             }
          }
      ]

kubernetes.io/cce.ingress.https-rules: >-
      [
          { "host":"ad.com",
            "http":{
                "paths":[
                    {"path":"/*","backend":{"serviceName":"service-example","servicePort":80}}
                ]
             }
          }
      ]

使用专属BLB集群

取值说明

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

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

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

使用该Annotationkubernetes.io/no-use-blb-cluster-l4: "true"之后，应用型BLB将建在L4共享集群上；

使用该Annotationkubernetes.io/no-use-blb-cluster-l7: "true"之后，应用型BLB将建在L7共享集群上。

• 指定创建在专属集群上

使用该Annotationkubernetes.io/blb-cluster-l4-id: "test"之后，应用型BLB将创建在指定的专属L4 BLB集群上；

使用该Annotationkubernetes.io/blb-cluster-l7-id: "test"之后，应用型BLB将创建在指定的专属L7 BLB集群上。

注意事项

• 有了专属集群之后，如果没有显式添加Annotation，将由后台自动选择创建在哪个专属BLB集群上。

示例

# 仅为 Ingress 指定 4 层 BLB 专属集群
kubernetes.io/blb-cluster-l4-id: blb-cluster-l4-id
kubernetes.io/no-use-blb-cluster-l7: true

# 仅为 Ingress 指定 7 层 BLB 专属集群
kubernetes.io/no-use-blb-cluster-l4: true
kubernetes.io/blb-cluster-l7-id: blb-cluster-l7-id

# 为 Ingress 指定 4 层和 7 层 BLB 专属集群
kubernetes.io/blb-cluster-l4-id: blb-cluster-l4-id
kubernetes.io/blb-cluster-l7-id: blb-cluster-l7-id

# 显式声明 Ingress 不使用任何专属集群
kubernetes.io/no-use-blb-cluster-l4: true
kubernetes.io/no-use-blb-cluster-l7: true

设置请求调度方法

取值说明

若值为RoundRobin，则使用加权轮询法调度请求；

若值为LeastConnection，则使用最小连接数法法调度请求；

若缺失，默认采用RoundRobin调度方法。

设置HTTP调度方法使用kubernetes.io/cce.ingress.blb.listener.http.scheduler，设置HTTPS调度方法使用kubernetes.io/cce.ingress.blb.listener.https.scheduler。

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 仅在新建应用型BLB监听器时有效。

示例

# HTTP
kubernetes.io/cce.ingress.blb.listener.http.scheduler: "LeastConnection"
 
# HTTPS
kubernetes.io/cce.ingress.blb.listener.https.scheduler: "LeastConnection"

取消添加X-Forwarded-For(XFF)头

取值说明

若值为true，应用型BLB自动在请求头中添加X-Forwarded-For请求头；

若值为false，应用型BLB不会自动在请求头中添加X-Forwarded-For请求头；

若缺失，行为和true一致，应用型BLB自动在请求头中添加X-Forwarded-For请求头。

设置HTTP请求使用kubernetes.io/cce.ingress.blb.listener.http.enable-x-forwarded-for-header，设置HTTPS请求使用kubernetes.io/cce.ingress.blb.listener.https.enable-x-forwarded-for-header。

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 仅在新建应用型BLB监听器时有效。

示例

kubernetes.io/cce.ingress.blb.listener.http.enable-x-forwarded-for-header: "false",
kubernetes.io/cce.ingress.blb.listener.https.enable-x-forwarded-for-header: "false"

配置实时更新

取值说明

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

注意事项

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

示例

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

使用 Pod直连模式

取值说明

开启直连模式需要进行以下两步：

1. 修改 cce-ingress-controller Deployment，添加以下环境变量，如果已经有了该环境变量，就不必再添加了

设置HTTP请求使用kubernetes.io/cce.ingress.blb.listener.http.enable-x-forwarded-for-header，设置HTTPS请求使用kubernetes.io/cce.ingress.blb.listener.https.enable-x-forwarded-for-header。

2. 为新建 Ingress 添加以下 Annotation

kubernetes.io/cce.ingress.network-mode: direct-access

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 仅在新建 Ingress 时有效；
• 使用 Pod 直连时，BLB 的后端地址出现在 IP 组中，IP组在服务器组标签页的右边。如果看不到，说明还没有开启IP组白名单，需要联系BLB负责同学处理。

示例

1.环境变量

2.添加 Annotation

kubernetes.io/cce.ingress.network-mode: direct-access

控制台添加 Annotation 的方式如下图所示

自定义监听器配置

取值说明

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

扩展协议内容在kubernetes.io/cce.ingress.listener.customized-listenerAnnotation 下。每种协议能配置的参数如下：

# 对于 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                     非必填。HTTPS服务端超时时间。默认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，需要自行按需添加；
• 只支持针对 80 端口自定义 HTTP 监听器配置，以及针对 443 端口自定义 HTTPS 监听器配置；

示例

kubernetes.io/cce.ingress.listener.customized-listener: |-
      {
         "80":{
            "protocol":"HTTP",
            "redirectPort":"443",
            "timeout":"31",
            "scheduler":"LeastConnection",
            "enableKeepSession":"true",
            "keepSessionType":"rewrite",
            "disableXForwardedForHeader": "true",
            "enableXForwardedProtoHeader": "true",
            "extendedAttributes": {
                "proxy_set_header": ["X-Real-IP $cip"]
            }
         },
         "443":{
            "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",
            "extendedAttributes": {
                "proxy_set_header": ["X-Real-IP $cip"]
            }
         }
      }

自定义健康检查规则

取值说明

扩展健康检查协议配置用于用户自定义 BLB Service 关联的 BLB 的服务器或 IP 组的健康检查配置。

在默认情况下，端口后端的服务器或 IP 组均使用 TCP 健康检查。

如果需要修改健康检查方式，或是健康检查相关的参数，可以使用此 Annotation。

扩展健康检查协议内容在kubernetes.io/cce.ingress.backend.customized-health-checkAnnotation 下，支持 TCP、HTTP 2 种健康检查协议。每种健康检查可配置的参数如下：

# TCP 健康检查
healthCheck                 必填，固定为TCP。
healthCheckTimeoutInSecond  非必填。健康检查超时时间。默认为3，需为1-60间的整数。
healthCheckIntervalInSecond 非必填。健康检查间隔时间。默认为3，需为1-60间的整数。
healthCheckDownRetry        非必填。不健康阈值，即连续多少次健康检查失败后，屏蔽该后端服务器。默认为3，需为2-5间的整数。
healthCheckUpRetry          非必填。健康阈值，即连续多少次健康检查成功后，重新将该后端服务器置为可用。默认为3，需为2-5间的整数。

# HTTP 健康检查
healthCheck                 必填，固定为HTTP。
healthCheckTimeoutInSecond  非必填。健康检查超时时间。默认为3，需为1-60间的整数。
healthCheckIntervalInSecond 非必填。健康检查间隔时间。默认为3，需为1-60间的整数。
healthCheckDownRetry        非必填。不健康阈值，即连续多少次健康检查失败后，屏蔽该后端服务器。默认为3，需为2-5间的整数。
healthCheckUpRetry          非必填。健康阈值，即连续多少次健康检查成功后，重新将该后端服务器置为可用。默认为3，需为2-5间的整数。
healthCheckUrlPath          非必填。健康检查URI，默认/。
healthCheckNormalStatus        非必填。健康检查正常时的HTTP状态码，支持5类状态码的组合，例如"http_1xx|http_2xx"，默认为"http_2xx|http_3xx"         
healthCheckHost             非必填。7层健康检查请求的头部域会带指定的host字段，例如"localhost"，默认""。

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 只可以使用 TCP 或 HTTP 健康检查；

示例 以下是一个使用 HTTP 健康检查的 BLB Ingress 示例：

kubernetes.io/cce.ingress.backend.customized-health-check: |-
    {
            "healthCheck":"HTTP",
            "healthCheckUrlPath":"/",
            "healthCheckTimeoutInSecond":"2",
            "healthCheckIntervalInSecond":"2",
            "healthCheckDownRetry":"2",
            "healthCheckUpRetry": "2",
            "healthCheckNormalStatus": "http_2xx",
            "healthCheckHost": "baidu.com"
    }

配置会话保持

取值说明 会话保持功能涉及多条Annotation，解释如下：

• 打开或关闭会话保持

值为true为打开会话保持。默认值为false。

开关HTTP会话保持使用kubernetes.io/cce.ingress.blb.listener.http.keep-session.enable，开关HTTPS会话保持使用kubernetes.io/cce.ingress.blb.listener.https.keep-session.enable。

在打开会话保持后，后面的Annotation才会生效。

• 设置会话保持类型

值为insert表示植入Cookie，值为rewrite表示重写Cookie。默认值为insert。

设置HTTP会话保持类型使用kubernetes.io/cce.ingress.blb.listener.http.keep-session.type，设置HTTPS会话保持类型使用kubernetes.io/cce.ingress.blb.listener.https.keep-session.type。

• 设置会话超时时间（仅对insert类型有效）

取值为 [1,15552000]，默认值为3600，单位是秒。

设置HTTP会话保持超时时间用kubernetes.io/cce.ingress.blb.listener.http.keep-session.timeout，设置HTTPS会话保持超时时间使用kubernetes.io/cce.ingress.blb.listener.https.keep-session.timeout。

• 设置Cookie名称（仅对rewrite类型有效）

设置HTTP会话保持Cookie名称使用kubernetes.io/cce.ingress.blb.listener.http.keep-session.cookie-name，设置HTTP会话保持Cookie名称使用kubernetes.io/cce.ingress.blb.listener.https.keep-session.cookie-name。

注意事项

• CCE不会自动添加该Annotation，需要自行按需添加；
• 仅在新建应用型BLB监听器时有效。

示例

# HTTP
kubernetes.io/cce.ingress.blb.listener.http.keep-session.enable: "true",
kubernetes.io/cce.ingress.blb.listener.http.keep-session.type: "insert"
kubernetes.io/cce.ingress.blb.listener.http.keep-session.timeout: 999

# HTTPS
kubernetes.io/cce.ingress.blb.listener.https.keep-session.enable: "true",
kubernetes.io/cce.ingress.blb.listener.https.keep-session.type: "rewrite",
kubernetes.io/cce.ingress.blb.listener.https.keep-session.cookie-name: "cce-test"