定制 ALB 路由
修改运行 Kubernetes Ingress 映像的 ALB 的缺省设置。
有时,您可以通过添加 Kubernetes NGINX 注释 (nginx.ingress.kubernetes.io/<annotation>
) 来定制 Ingress 的路由。Kubernetes
NGINX 注释始终应用于资源中的所有服务路径,并且不能在注释中指定服务名称。 不 支持定制 IBM Cloud Kubernetes Service 注释 (ingress.bluemix.net/<annotation>
)。
Kubernetes 在 2022 年 1 月 31 日或之后创建的集群上的 Ingress 控制器 (ALB) 在缺省情况下不会处理具有片段注释 (例如,nginx.ingress.kubernetes.io/configuration-snippet
) 的 Ingress 资源,因为所有新集群都使用 ALB 的 ConfigMap中的 allow-snippet-annotations: "false"
配置进行部署。
如果添加此处建议的任何配置片段,那么需要编辑 ALB 的 ConfigMap (kube-system/ibm-k8s-controller-config
) 并将 allow-snippet-annotations: "false"
更改为 allow-snippet-annotations: "true"
。
将服务器端口添加到主机头
要在将请求转发到后端应用程序之前向客户机请求添加服务器端口,请在 服务器片段注释 中或作为 ibm-k8s-controller-config
ConfigMap
字段配置外部服务的代理。
使用专用 ALB 路由入局请求
要使用专用 ALB 将入局请求路由到应用程序,请在 Ingress 资源 中指定 private-iks-k8s-nginx
类注释。 专用 ALB 配置为将资源与此类配合使用。
kubernetes.io/ingress.class: "private-iks-k8s-nginx"
使用 App ID 认证应用程序
使用 IBM Cloud App ID 配置 Ingress,以通过更改特定 Kubernetes Ingress 字段对应用程序实施认证。 请参阅 向应用程序添加 App ID 认证 以获取更多信息。
设置最大客户机请求主体大小
要设置客户机可作为请求的一部分发送的主体的最大大小,请使用以下 Kubernetes Ingress resource 注释。
nginx.ingress.kubernetes.io/proxy-body-size: 8m
启用和禁用客户机响应数据缓冲
在将数据发送到客户机时,可以在 ALB 上禁用或启用响应数据的存储。 此设置默认为禁用。 要启用,请设置以下 Ingress 资源 annotation。
nginx.ingress.kubernetes.io/proxy-buffering: "on"
定制连接和读取超时
要设置 ALB 在后端应用程序被视为不可用之前等待连接到后端应用程序并从后端应用程序读取的时间量,请使用以下 注释。
nginx.ingress.kubernetes.io/proxy-connect-timeout: 62
nginx.ingress.kubernetes.io/proxy-read-timeout: 62
定制错误操作
要指定 ALB 针对特定 HTTP 错误可以采取的自定义操作,请设置 custom-http-errors
字段。
更改默认的 HTTP 和 HTTPS 端口
要更改 HTTP (端口80)和 HTTPS (端口443)网络流量的默认端口,请使用以下 Kubernetes 入口 ibm-ingress-deploy-config
ConfigMap 字段 修改每个ALB服务。
示例字段设置。
httpPort=8080
httpsPort=8443
定制请求头
要在将请求转发到后端应用程序之前向客户机请求添加头信息,请使用以下 Kubernetes ibm-k8s-controller-config
configmap 字段
proxy-set-headers: "ingress-nginx/custom-headers"
有关 custom-headers
ConfigMap 需求,请参阅 此示例。
定制响应头
要在将头信息发送到客户机响应之前将其添加到客户机响应,请使用以下 注释。
nginx.ingress.kubernetes.io/configuration-snippet: |
more_set_headers "Request-Id: $req_id";
为外部服务添加路径定义
要向外部服务 (例如,IBM Cloud中托管的服务) 添加路径定义,请在 位置片段中配置外部服务的代理。 或者,将代理替换为 永久重定向到外部服务。
重定向不安全的请求
默认情况下,不安全的 HTTP 客户端请求将重定向到 HTTPS。 要禁用此设置,请使用以下字段和注释。
ibm-k8s-controller-config
ConfigMap 字段ssl-redirect: "false"
- 入口资源 annotation:
nginx.ingress.kubernetes.io/ssl-redirect: "false"
启用和禁用 HTTP 严格传输安全
将浏览器设置为仅使用 HTTPS 访问域。 缺省情况下,此选项已启用。
- 要添加最大时效和子域粒度,请参阅 此 NGINX 博客。
- 要禁用,请设置
ibm-k8s-controller-config
configmap 字段。hsts: false
设置最大保持活动请求数
要设置可通过一个保持活动连接提供服务的最大请求数,请使用以下 Kubernetes ibm-k8s-controller-config
configmap 字段。
keep-alive-requests: 100
Kubernetes Ingress 中 keep-alive-requests
的缺省值为 100
,这远小于 IBM Cloud Kubernetes Service Ingress 中 4096
的缺省值。 如果已将 Ingress 设置从 IBM Cloud Kubernetes Service Ingress 迁移到 Kubernetes Ingress,那么可能需要更改 keep-alive-requests
以通过现有性能测试。
设置最大保持活动请求超时
要设置保持活动连接在客户机与 ALB 代理服务器之间保持打开的最大时间,请使用以下 Kubernetes ibm-k8s-controller-config
configmap 字段。
keep-alive: 60
设置最大大型客户机头缓冲区数
要设置读取大型客户机请求头的缓冲区的最大数目和大小,请使用以下 Kubernetes ibm-k8s-controller-config
configmap 字段。
large-client-header-buffers: 4 8k
修改 ALB 与请求 URI 的匹配方式
要修改 ALB 针对应用程序路径匹配请求 URI 的方式,请使用以下 Kubernetes Ingress resource 注释。
nginx.ingress.kubernetes.io/use-regex: "true"
有关更多信息,请参阅 此博客。
添加定制位置块配置
要为服务添加定制位置块配置,请使用以下 Kubernetes Ingress 资源 注释。
nginx.ingress.kubernetes.io/configuration-snippet: |
more_set_headers "Request-Id: $req_id";
配置相互认证
要为 ALB 配置相互认证,请使用以下 Kubernetes Ingress 资源 注释。 请注意,相互认证不能应用于自定义端口,必须应用于 HTTPS 端口。
nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
配置代理缓冲区大小
要配置用于读取响应第一部分的代理缓冲区的大小,请使用以下 Kubernetes Ingress resource 注释。
nginx.ingress.kubernetes.io/proxy-buffer-size: "8k"
配置代理缓冲区号
要配置 ALB 的代理缓冲区数,请使用以下 Kubernetes Ingress resource 注释。
nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
配置繁忙代理缓冲区大小
配置 ALB 何时可以传递请求
要设置 ALB 何时可以将请求传递到下一个上游服务器,请使用以下 Kubernetes Ingress 字段。
-
全局设置:
ibm-k8s-controller-config
ConfigMap 字段:retry-non-idempotent: true proxy-next-upstream: error timeout http_500
-
按资源设置 :Ingress 资源 注释:
nginx.ingress.kubernetes.io/proxy-next-upstream: http_500 nginx.ingress.kubernetes.io/proxy-next-upstream-timeout: 50 nginx.ingress.kubernetes.io/proxy-next-upstream-tries: 3
速率限制
要限制每个定义的服务键的请求处理速率和连接数,请使用 Ingress 资源 注释来限制速率。
除去响应头
您可以在向客户端发送响应之前,从后端应用程序中移除客户端响应中包含的头信息。 在 位置片段中配置响应头除去,或者在 ibm-k8s-controller-config
ConfigMap中使用 proxy_hide_header
字段 作为 配置片段。
重写路径
要将 ALB 域路径上的入局网络流量路由到后端应用程序侦听的其他路径,请使用以下 Kubernetes Ingress resource 注释。
nginx.ingress.kubernetes.io/rewrite-target: /newpath
定制服务器块配置
要添加定制服务器块配置,请使用以下 Kubernetes Ingress 资源 注释。
nginx.ingress.kubernetes.io/server-snippet: |
location = /health {
return 200 'Healthy';
add_header Content-Type text/plain;
}
允许 SSL 服务支持对流量进行加密
为了支持SSL服务,对需要 HTTPS 的上游应用程序的流量进行加密,请使用 Kubernetes 入口资源 后端协议注释和 后端证书认证注释。
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/proxy-ssl-secret: app1-ssl-secret
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: 5
nginx.ingress.kubernetes.io/proxy-ssl-name: proxy-ssl-name=mydomain.com
nginx.ingress.kubernetes.io/proxy-ssl-verify: true
使用非标准 TCP 端口访问应用程序
要通过非标准 TCP 端口访问应用程序,请执行以下步骤。
-
创建
tcp-services
ConfigMap 以指定 TCP 端口,例如以下示例端口。 有关tcp-services
ConfigMap, 请参阅 本博客。apiVersion: v1 kind: ConfigMap metadata: name: tcp-services namespace: kube-system data: 9000: "<namespace>/<service>:8080"
-
在
kube-system
名称空间中创建 ConfigMap。kubectl apply -f tcp-services.yaml -n kube-system
-
将
tcp-services
ConfigMap 指定为ibm-ingress-deploy-config
ConfigMap 中的字段。"tcpServicesConfig":"kube-system/tcp-services"
-
修改每个 ALB 服务 以添加端口。
设置最大上游保持活动请求数
要设置可通过一个保持活动连接提供服务的最大请求数,请使用以下 Kubernetes ibm-k8s-controller-config
ConfigMap 字段。
upstream-keepalive-requests: 32
设置最大上游保持活动超时
要设置保持活动连接在 ALB 代理服务器与应用程序的上游服务器之间保持打开的最长时间,请使用以下 Kubernetes ibm-k8s-controller-config
configmap 字段。
upstream-keepalive-timeout: 32
定制 ALB 部署
通过创建 ibm-ingress-deploy-config
ConfigMap,为运行 Kubernetes Ingress 映像的 ALB 定制部署。
-
获取公开每个 ALB 的服务的名称。
-
经典集群:
kubectl get svc -n kube-system | grep alb
-
VPC 集群: 在输出中,查找格式化的服务名称,例如
public-crc204dl7w0qf6n6sp7tug
。kubectl get svc -n kube-system | grep LoadBalancer
-
创建 ConfigMap 以定制 Ingress 部署
-
为
ibm-ingress-deploy-config
ConfigMap创建 YAML 文件。 对于每个 ALB 标识,可以指定以下一个或多个可选设置。 请注意,您只能指定要配置的设置,而不需要指定所有设置。apiVersion: v1 kind: ConfigMap metadata: name: ibm-ingress-deploy-config namespace: kube-system data: <alb1-id>: '{"deepInspect":"<true|false>", "defaultBackendService":"<service_name>", "defaultCertificate":"<namespace>/<secret_name>", "defaultConfig":"<namespace>/<configmap-name>","enableSslPassthrough":"<true|false>", "httpPort":"<port>", "httpsPort":"<port>", "ingressClass":"<class>", "logLevel":<log_level>, "replicas":<number_of_replicas>, "tcpServicesConfig":"<kube-system/tcp-services>", "enableIngressValidation":"<true|false>"}' <alb2-id>: '{"deepInspect":"<true|false>", "defaultBackendService":"<service_name>", "defaultCertificate":"<namespace>/<secret_name>", "enableSslPassthrough":"<true|false>", "httpPort":"<port>", "httpsPort":"<port>", "ingressClass":"<class>","logLevel":<log_level>, "replicas":<number_of_replicas>, "tcpServicesConfig":"<kube-system/tcp-services>", "enableIngressValidation":"<true|false>"}'
deepInspect
-
- 启用或禁用 Ingress 对象安全性深度检验器。 启用后,ALB 将在处理之前检查 Ingress 资源中的配置值。 有关更多信息,请参阅 ingress-nginx 源代码。
- 此功能可用于 ALB V 1.2.0 及更高版本,并且缺省情况下已启用。
defaultBackendService
- 指定在未配置主机或找不到匹配主机时要接收请求的可选缺省服务的名称。 此服务将替换生成
404
消息的 IBM提供的缺省服务。 您可以使用此服务来配置定制错误页面或用于测试连接。 defaultCertificate
- 缺省 TLS 证书的私钥,用于应用于使用 Ingress ALB 配置的格式为
secret_namespace/secret_name
的任何子域。 要创建私钥,可以运行 ibmcloud ks ingress secret create 命令。 如果在 Ingress 资源的spec.tls
部分中指定了其他 TLS 证书的私钥,并且该私钥与 Ingress 资源存在于同一名称空间中,那么将应用该私钥而不是此缺省私钥。 defaultConfig
- 指定 ALB 的缺省配置映射。 以
namespace/configmap-name
格式输入要使用的 configmap 的位置。 例如,kube-system/ibm-k8s-controller-config
。 enableAnnotationValidation
-
- 启用或禁用 Ingress 对象注释验证。 启用后,ALB 将在处理之前验证 Ingress 资源中的注释值。 有关更多信息,请参阅 ingress-nginx 源代码。
- 此功能可用于 ALB 1.9.0 及更高版本,并且缺省情况下已启用。
enableSslPassthrough
- 对 ALB 启用 SSL 传递。 TLS 连接不会终止,也不会通过非接触方式传递。
httpPort
,httpsPort
- 通过添加要打开的 HTTP 或 HTTPS 端口,为入口 ALB 公开非默认端口。
ingressClass
- 如果在 Ingress 资源中指定了
public-iks-k8s-nginx
或private-iks-k8s-nginx
以外的类,请指定类。 logLevel
-
- 指定要使用的日志级别。 从以下数值中选择
2
: 通过使用**diff**
命令在NGINX
中显示配置中的更改来显示详细信息。3
: 以 JSON 格式显示有关服务,Ingress 规则和端点更改的详细信息。5
: 以调试方式配置NGINX
。- 有关日志记录的更多信息,请参阅 调试日志记录。
replicas
- 缺省情况下,每个 ALB 都有 2 个副本。 通过增加 ALB pod 的数量来扩展 ALB 处理功能。 有关更多信息,请参阅 增加 ALB pod 副本数。
tcpServicesConfig
- 指定 ConfigMap 以及 ConfigMap 所在的名称空间 (例如
kube-system/tcp-services
),其中包含有关通过非标准 TCP 端口访问应用程序服务的信息。 enableIngressValidation
- 为此 ALB 启用 Ingress 验证 Webhook 的部署。 在应用于集群之前,Webhook 会验证 Ingress 资源以防止配置无效。 (ALB 将仅处理属于其公开的 Ingress 类的 Ingress 资源。) 默认值:
"false"
。
-
在集群中创建
ibm-ingress-deploy-config
ConfigMap。kubectl create -f ibm-ingress-deploy-config.yaml
-
要选取更改,请更新 ALB。 请注意,可能需要最多 5 分钟才能将更改应用于 ALB。
ibmcloud ks ingress alb update -c <cluster_name_or_ID>
-
如果您指定了非标准的 HTTP、HTTPS 或TCP端口,则必须在每个ALB服务上打开这些端口。
-
对于在步骤 1 中找到的每个 ALB 服务,请编辑 YAML 文件。
kubectl edit svc -n kube-system <alb_svc_name>
-
在
spec.ports
部分中,添加要打开的端口。 缺省情况下,端口 80 和 443 已打开。 如果要使 80 和 443 保持打开状态,请不要将它们从此文件中除去。 未指定的任何端口都处于关闭状态。 请勿指定nodePort
。 添加端口并应用更改后,将自动分配nodePort
... ports: - name: port-80 nodePort: 32632 port: 80 protocol: TCP targetPort: 80 - name: port-443 nodePort: 32293 port: 443 protocol: TCP targetPort: 443 - name: <new_port> port: <port> protocol: TCP targetPort: <port> ...
-
保存并关闭该文件。 您的更改将自动应用。
-
定制 Ingress 类
Ingress 类将类名与 Ingress 控制器类型相关联。 使用 IngressClass
资源来定制 Ingress 类。
将 App ID 认证添加到应用程序
通过使用 IBM Cloud App ID配置 Ingress 来对应用程序实施认证。
-
选择现有或创建新的 App ID 实例。
App ID 实例只能在集群中的一个名称空间中使用。 如果要为多个名称空间中的 Ingress 资源配置 App ID,请重复本节中的步骤,为每个名称空间中的 Ingress 资源指定唯一的 App ID 实例。
- 要使用现有实例,请确保服务实例名称仅包含 小写 字母数字字符,并且其长度不超过 25 个字符。 要更改名称,请从服务实例详细信息页面上的“更多选项”菜单中选择 重命名服务。
- 要供应新 App ID 实例,请执行以下操作:
- 将服务名称替换为服务实例的唯一名称。 服务实例名称只能包含小写字母和数字,且不能超过25个字符。
- 选择部署了您的集群的区域。
- 单击创建。
-
添加应用程序的重定向 URL。 重定向 URL 是应用程序的回调端点。 为防止网络钓鱼攻击,IBM Cloud App ID 会根据重定向 URL 的允许列表验证请求 URL。
- 在 App ID 管理控制台中,导航至管理认证。
- 在身份提供者选项卡中,确保已选择身份提供者。 如果没有选择身份供应商,则不会对用户进行身份验证,但会向用户发放一个访问令牌,用于匿名访问应用程序。
- 在 “身份验证设置”选项卡中,为应用程序添加重定向 URL,格式为
https://<hostname>/oauth2-<App_ID_service_instance_name>/callback
。 请注意,服务实例名称中的所有字母都必须指定为小写。
如果您使用 IBM Cloud App ID 注销功能,则必须将
/sign_out
添加到您的域中,格式为https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out
,并将此 URL 添加到重定向URL列表中。 如果您想使用自定义的退出页面,必须在 ConfigMap 中设置whitelist_domains
,用于 OAuth2-Proxy。 使用rd
查询参数调用https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out
端点,或者使用定制注销页面设置X-Auth-Request-Redirect
头。 有关更多详细信息,请参阅 注销。 -
将 App ID 服务实例与集群绑定。 该命令会为服务实例创建一个服务密钥,也可以包含
--key
选项来使用现有的服务密钥凭据。 确保将服务实例绑定到 Ingress 资源所在的同一名称空间。 请注意,服务实例名称中的所有字母都必须指定为小写。ibmcloud ks cluster service bind --cluster <cluster_name_or_ID> --namespace <namespace> --service <App_ID_service_instance_name> [--key <service_instance_key>]
服务成功绑定到群集后,就会创建一个群集密钥,其中包含服务实例的凭据。 CLI 输出示例:
ibmcloud ks cluster service bind --cluster mycluster --namespace mynamespace --service appid1 Binding service instance to namespace... OK Namespace: mynamespace Secret name: binding-<service_instance_name>
-
在集群中启用 ALB OAuth 代理附加组件。 此附加组件创建并管理以下 Kubernetes 资源: 针对 App ID 服务实例的 OAuth2-Proxy 部署,包含 OAuth2-Proxy 部署配置的私钥,以及用于配置 ALB 以将入局请求路由到 App ID 实例的 OAuth2-Proxy 部署的 Ingress 资源。 其中每个资源的名称都以
oauth2-
开头。- 启用
alb-oauth-proxy
附加组件。ibmcloud ks cluster addon enable alb-oauth-proxy --cluster <cluster_name_or_ID>
- 验证 ALB OAuth 代理附加组件的状态是否为
Addon Ready
。ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>
- 启用
-
在要添加 App ID 认证的应用程序的 Ingress 资源中,确保资源名称的长度不超过 25 个字符。 然后,将以下注释添加到
metadata.annotations
部分。-
添加以下
auth-url
注释。 此注释指定了您的 App ID 实例的 OAuth2-Proxy 的 URL,该实例充当 App ID 的OIDC信赖方(RP)。 请注意,服务实例名称中的所有字母都必须指定为小写。... annotations: nginx.ingress.kubernetes.io/auth-url: https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth ...
-
有时,
OAuth2-Proxy
使用的认证 Cookie 超过 4 KB。 因此它被分成两部分。 必须添加以下片段以确保OAuth2-Proxy
可以正确更新这两个 cookie。... annotations: nginx.ingress.kubernetes.io/configuration-snippet: | auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1; access_by_lua_block { if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)") end } ...
-
选择要在
Authorization
头中向应用程序发送哪些令牌。 有关标识和访问令牌的更多信息,请参阅 App ID 文档。-
要仅发送
ID Token
,请添加以下注释:... annotations: nginx.ingress.kubernetes.io/auth-response-headers: Authorization ...
-
要仅发送
Access Token
,请将以下信息添加到configuration-snippet
注释。 (这将扩展步骤 5.2中的片段。)... annotations: nginx.ingress.kubernetes.io/configuration-snippet: | auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1; auth_request_set $access_token $upstream_http_x_auth_request_access_token; access_by_lua_block { if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)") end if ngx.var.access_token ~= "" then ngx.req.set_header("Authorization", "Bearer " .. ngx.var.access_token) end } ...
-
要发送
Access Token
和ID Token
,请将以下信息添加到configuration-snippet
注释。 (这将扩展步骤 5.2中的片段。)... annotations: nginx.ingress.kubernetes.io/configuration-snippet: | auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1; auth_request_set $access_token $upstream_http_x_auth_request_access_token; auth_request_set $id_token $upstream_http_authorization; access_by_lua_block { if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)") end if ngx.var.id_token ~= "" and ngx.var.access_token ~= "" then ngx.req.set_header("Authorization", "Bearer " .. ngx.var.access_token .. " " .. ngx.var.id_token:match("%s*Bearer%s*(.*)")) end } ...
-
-
可选: 如果应用程序除了支持或不支持 API 策略 之外,还支持 Web 应用程序策略,请添加
nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2-<App_ID_service_instance_name>/start?rd=$escaped_request_uri
注释。 请注意,服务实例名称中的所有字母都必须为小写。- 如果您指定了此注释,且客户端认证失败,客户端将被重定向到您的 App ID 实例的 OAuth2-Proxy 的 URL。 该 OAuth2-Proxy 作为 App ID 的 OIDC 信赖方(RP),将客户重定向到您的 App ID 登录页面进行身份验证。
- 如果未指定此注释,那么客户机必须使用有效的不记名令牌进行认证。 如果客户机认证失败,那么将拒绝客户机的请求,并显示
401 Unauthorized
错误消息。
-
-
重新应用 Ingress 资源以实施 App ID 认证。 重新应用具有相应注释的 Ingress 资源后,ALB OAuth 代理附加组件将部署 OAuth2-Proxy 部署,为部署创建服务,并创建单独的 Ingress 资源以配置 OAuth2-Proxy 部署消息的路由。 请勿删除这些附加组件资源。
kubectl apply -f <app_ingress_resource>.yaml -n namespace
-
验证是否对应用程序实施了 App ID 认证。
-
可选项:如果在群集上使用网络策略或其他防火墙解决方案来限制出站流量,则必须确保允许从群集访问 AppID's 公共服务。 要获取此服务的 IP 地址范围,请通过 客户支持 提交申请。
-
可选: 您可以通过创建 Kubernetes ConfigMap来定制 OAuth2-Proxy 的缺省行为。
- 创建 ConfigMap YAML 文件,该文件指定要更改的 OAuth2-Proxy 设置的值。
apiVersion: v1 kind: ConfigMap metadata: name: oauth2-<App_ID_service_instance_name> namespace: <ingress_resource_namespace> data: auth_logging: <true|false> # Log all authentication attempts. auth_logging_format: # Format for authentication logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#logging-configuration cookie_csrf_expire: "15m" # Expiration time for CSRF cookie. Default is "15m". cookie_csrf_per_request: <true|false> # Enable multiple CSRF cookies per request, making it possible to have parallel requests. Default is "false". cookie_domains: # A list of optional domains to force cookies to. The longest domain that matches the request’s host is used. If there is no match for the request’s host, the shortest domain is used. Example: sub.domain.com,example.com cookie_expire: "168h0m0s" # Expiration time for cookies. Default: "168h0m0s". cookie_samesite: "" # SameSite attribute for cookies. Supported values: "lax", "strict", "none", or "". email_domains: "" # Authenticate IDs that use the specified email domain. To authenticate IDs that use any email domain, use "*". Default: "". Example: example.com,example2.com pass_access_token: <true|false> # Pass the OAuth access token to the backend app via the X-Forwarded-Access-Token header. request_logging: <true|false> # Log all requests to the backend app. request_logging_format: # Format for request logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#request-log-format scope: # Scope of the OAuth authentication. For more info, see https://oauth.net/2/scope/ set_authorization_header: <true|false> # Set the Authorization Bearer response header when the app responds to the Ingress ALB, such when using the NGINX auth_request mode. set_xauthrequest: <true|false> # Set X-Auth-Request-User, X-Auth-Request-Email, and X-Auth-Request-Preferred-Username response headers when the app responds to the Ingress ALB, such as when using the NGINX auth_request mode. standard_logging: <true|false> # Log standard runtime information. standard_logging_format: # Format for standard logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#standard-log-format tls_secret_name: # The name of a secret that contains the server-side TLS certificate and key to enable TLS between the OAuth2-Proxy and the Ingress ALB. By default, the TLS secret defined in your Ingress resources is used. whitelist_domains: # Allowed domains for redirection after authentication. Default: "". Example: example.com,*.example2.com For more info, see: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#command-line-options oidc_extra_audiences: # Additional audiences which are allowed to pass verification. cookie_refresh: # Refresh the cookie after this duration. Example: "15m". To use this feature, you must enable "Refresh token" for the AppID instance. For more info, see: /docs/appid?topic=appid-managing-idp&interface=ui#idp-token-lifetime
- 将 ConfigMap 资源应用于附加组件。 您的更改将自动应用。
kubectl apply -f oauth2-<App_ID_service_instance_name>.yaml
- 创建 ConfigMap YAML 文件,该文件指定要更改的 OAuth2-Proxy 设置的值。
有关每个 ALB OAuth 代理附加组件版本的更改列表,请参阅 IBM Cloud ALB OAuth 代理附加组件更改日志。
升级 ALB OAuth 代理附加组件
要升级 ALB OAuth Proxy 附加组件,必须先禁用该附加组件,然后重新启用该附加组件并指定版本。
升级过程是非中断性的,因为即使在禁用附加组件时,受监督的 OAuth2 代理实例仍保留在集群上。
- 禁用附加组件。
ibmcloud ks cluster addon disable alb-oauth-proxy --cluster <cluster_name_or_ID>
- 列出可用的附加组件版本,并决定要使用的版本。
ibmcloud ks cluster addon versions --addon alb-oauth-proxy
- 启用附加组件并指定
--version
选项。 如果未指定版本,那么将启用缺省版本。ibmcloud ks cluster addon enable alb-oauth-proxy --cluster <cluster_name_or_ID> [--version <version>]
保留源 IP 地址
缺省情况下,Ingress ALB 不会保留客户机请求的源 IP 地址。 要保留源 IP 地址,可以启用 VPC 集群中的 PROXY 协议 或 更改经典集群中的 externalTrafficPolicy
。
在 VPC 集群中启用 PROXY 协议
要在 VPC 集群中保留客户机请求的源 IP 地址,可以对集群中公开 Ingress ALB 的所有负载均衡器启用 NGINX PROXY 协议。
-
可选如果使用 Cloud Internet Services (CIS),请完成以下步骤。
- 在 CIS 控制台中启用 True client IP header 设置,方法是单击 Security(安全 )> Advanced(高级 )> True client IP header。
- 编辑
kube-system/ibm-k8s-controller-config configmap
并设置allow-snippet-annotations: "true"
。 - 添加注释
nginx.ingress.kubernetes.io/server-snippet: real_ip_header CF-Connecting-IP;
。
-
启用 PROXY 协议。 有关此命令的参数的更多信息,请参阅 CLI 参考。 运行此命令后,将使用更新的 PROXY 协议配置创建新的负载均衡器。 在重新创建负载平衡器时,每个子网中必须有两个未使用的 IP 地址。 创建这些负载均衡器后,将删除现有 ALB 负载均衡器。 此负载均衡器重新创建过程可能会导致服务中断。
ibmcloud ks ingress lb proxy-protocol enable --cluster <cluster_name_or_ID> --cidr <subnet_CIDR> --header-timeout <timeout>
-
确认对在集群中公开 ALB 的负载均衡器启用了 PROXY 协议。
ibmcloud ks ingress lb get --cluster <cluster_name_or_ID>
-
以后要禁用 PROXY 协议,可以运行以下命令:
ibmcloud ks ingress lb proxy-protocol disable --cluster <cluster_name_or_ID>
更改经典集群中的 externalTrafficPolicy
保留经典集群中客户机请求的源 IP 地址。
在经典集群中,"将 ALB 复制数量增加到 2 个以上 会增加副本数量,但当 "externalTrafficPolicy
配置为 "Local
时,超过 2 个的副本将不会被使用。 群集上只有 2 个负载平衡器 pod(主动-被动设置),由于采用了这种流量策略,所以只将传入流量转发到同一节点上的
ALB pod。
缺省情况下,不会保留客户机请求的源 IP 地址。 对应用程序的客户机请求发送到集群时,该请求会路由到用于公开 ALB 的 LoadBalancer 服务的 pod。 如果在 LoadBalancer 服务 pod 所在的工作程序节点上不存在应用程序 pod,那么负载均衡器会将该请求转发到其他工作程序节点上的应用程序 pod。 软件包的源 IP 地址将更改为运行应用程序 pod 的工作程序节点的公共 IP 地址。
要保留客户端请求的原始源 IP 地址,可以启用 源 IP 保留。 例如,在应用程序服务器必须应用安全性和访问控制策略的情况下,保留客户机的 IP 非常有用。
启用源 IP 保护后,负载平衡器会将流量从转发到不同工作节点上的 ALB pod 转移到同一工作节点上的 ALB pod。 在此轮班期间,您的应用程序可能会迂到停机时间。 如果禁用 ALB,那么对用于公开 ALB 的 LoadBalancer 服务进行的任何源 IP 更改都将丢失。 重新启用 ALB 时,必须重新启用源 IP。
要启用源 IP 保留,请编辑用于公开 Ingress ALB 的 LoadBalancer 服务:
-
为单个 ALB 或集群中的所有 ALB 启用源 IP 保留。
-
为单个 ALB 设置源 IP 保留:
-
获取要为其启用源 IP 的 ALB 的标识。 ALB 服务的格式类似于
public-cr18e61e63c6e94b658596ca93d087eed9-alb1
(对于公共 ALB)或private-cr18e61e63c6e94b658596ca93d087eed9-alb1
(对于专用 ALB)。kubectl get svc -n kube-system | grep alb
-
打开用于公开 ALB 的 LoadBalancer 服务的 YAML。
kubectl edit svc <ALB_ID> -n kube-system
-
在
spec
下,将externalTrafficPolicy
的值从Cluster
更改为Local
。 -
保存并关闭配置文件。 输出将类似于以下内容:
service "public-cr18e61e63c6e94b658596ca93d087eed9-alb1" edited
-
-
要为集群中的所有公共 ALB 设置源 IP 保留,请运行以下命令:
kubectl get svc -n kube-system | grep alb | awk '{print $1}' | grep "^public" | while read alb; do kubectl patch svc $alb -n kube-system -p '{"spec":{"externalTrafficPolicy":"Local"}}'; done
示例输出
"public-cr18e61e63c6e94b658596ca93d087eed9-alb1", "public-cr17e61e63c6e94b658596ca92d087eed9-alb2" patched
-
要为集群中的所有专用 ALB 设置源 IP 保留,请运行以下命令:
kubectl get svc -n kube-system | grep alb | awk '{print $1}' | grep "^private" | while read alb; do kubectl patch svc $alb -n kube-system -p '{"spec":{"externalTrafficPolicy":"Local"}}'; done
示例输出
"private-cr18e61e63c6e94b658596ca93d087eed9-alb1", "private-cr17e61e63c6e94b658596ca92d087eed9-alb2" patched
-
-
在 ALB pod 日志中验证源 IP 是否得到保留。
- 获取修改的 ALB 的 pod 的标识。
kubectl get pods -n kube-system | grep alb
- 打开该 ALB pod 的日志。 验证
client
字段的 IP 地址是否为客户机请求 IP 地址,而不是 LoadBalancer 服务 IP 地址。kubectl logs <ALB_pod_ID> nginx-ingress -n kube-system
- 获取修改的 ALB 的 pod 的标识。
-
现在,查找发送到后端应用程序的请求的头时,可以在
x-forwarded-for
头中看到客户机 IP 地址。 -
如果您不再希望保留源 IP,那么可以还原对服务进行的更改。
- 要还原公共 ALB 的源 IP 保留,请运行以下命令:
kubectl get svc -n kube-system | grep alb | awk '{print $1}' | grep "^public" | while read alb; do kubectl patch svc $alb -n kube-system -p '{"spec":{"externalTrafficPolicy":"Cluster"}}'; done
- 要还原专用 ALB 的源 IP 保留,请运行以下命令:
kubectl get svc -n kube-system | grep alb | awk '{print $1}' | grep "^private" | while read alb; do kubectl patch svc $alb -n kube-system -p '{"spec":{"externalTrafficPolicy":"Cluster"}}'; done
- 要还原公共 ALB 的源 IP 保留,请运行以下命令:
在 HTTP 级别配置 SSL 协议和 SSL 密码
通过编辑 ibm-k8s-controller-config
ConfigMap,在全局 HTTP 级别启用 SSL 协议和密码。
例如,如果仍有需要 TLS 1.0 或 1.1 支持的旧客户机,那么必须手动启用这些 TLS 版本以仅覆盖 TLS 1.2 和 TLS 1.3 的缺省设置。
如果指定启用的协议用于所有主机,那么仅当使用 OpenSSL 1.0.1 或更高版本时,TLSv1.1 和 TLSv1.2 参数(1.1.13 和 1.0.12)才有效。 仅当使用通过 TLSv1.3 支持构建的 OpenSSL 1.1.1 时,TLSv1.3 参数 (1.13.0) 才有效。
要编辑配置映射以启用 SSL 协议和密码,请执行以下操作:
-
编辑
ibm-k8s-controller-config
ConfigMap 资源的配置文件。kubectl edit cm ibm-k8s-controller-config -n kube-system
-
添加 SSL 协议和密码。 根据 OpenSSL 库密码列表格式对密码进行格式化。
apiVersion: v1 data: ssl-protocols: "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3" ssl-ciphers: "HIGH:!aNULL:!MD5:!CAMELLIA:!AESCCM:!ECDH+CHACHA20" kind: ConfigMap metadata: name: ibm-k8s-controller-config namespace: kube-system
-
保存配置文件。
-
验证是否已应用配置映射更改。 更改会自动应用于 ALB。
kubectl get cm ibm-k8s-controller-config -n kube-system -o yaml
向旧客户机发送定制证书
如果您拥有不支持服务器名称指示 (SNI) 的旧设备,并且您 在 Ingress 资源中使用自定义 TLS 证书,则必须编辑 ALB 的服务器设置以使用您的自定义 TLS 证书和自定义 TLS 密钥。
创建经典集群时,将为 IBM 提供的缺省 Ingress 私钥生成 Let's Encrypt 证书。 如果在集群中创建定制私钥,并在 Ingress 资源中为 TLS 终止指定此定制私钥,那么 Ingress ALB 将向客户机发送定制私钥的证书,而不发送缺省 Let's Encrypt 证书。 但是,如果客户机不支持 SNI,那么 Ingress ALB 缺省为使用 Let's Encrypt 证书,因为缺省私钥会在 ALB 的缺省服务器设置中列出。 要向不支持 SNI 的设备发送自定义证书,请完成以下步骤,将 ALB 的默认服务器设置更改为自定义密文。
缺省情况下生成的 Let 's Encrypt 证书并非用于生产用途。 对于生产工作负载,请自带定制证书。
-
编辑
alb-default-server
Ingress 资源。kubectl edit ingress alb-default-server -n kube-system
-
在
spec.tls
部分中,将hosts.secretName
设置的值更改为包含定制证书的定制私钥的名称。 示例:spec: rules: ... tls: - hosts: - invalid.mycluster-<hash>-0000.us-south.containers.appdomain.cloud secretName: <custom_secret_name>
-
保存资源文件。
-
验证资源现在是否指向定制私钥名称。 更改会自动应用于 ALB。
kubectl get ingress alb-default-server -n kube-system -o yaml
微调连接处理
client-header-timeout
、client-body-timeout
和 keep-alive
设置是关键配置,决定了客户端、Ingress 控制器和后端服务器之间保持活动连接的时间。 这些超时在优化请求处理方面发挥着重要作用,尤其是在处理长时间客户端连接、后端服务器延迟响应以及保护宝贵资源不被不必要占用时。
client-header-timeout
定义了服务器等待完整客户端标头的最长时间。 同样,client-body-timeout
表示服务器等待客户端发送请求正文的持续时间。 这两个超时都必须与 keep-alive
参数保持一致,后者规定了服务器在等待进一步请求时保持连接打开的时间。 如果这些超时与 keep-alive 设置不匹配,NGINX 将终止连接,这可能会导致意想不到的客户端行为或请求失败。
您可以在 kube-system
命名空间的 ibm-k8s-controller-config
ConfigMap 中设置上述参数。
apiVersion: v1
kind: ConfigMap
metadata:
name: ibm-k8s-controller-config
namespace: kube-system
data:
...
client-body-timeout: "100"
client-header-timeout: "100"
keep-alive: "100"
更多信息,请参阅 client-header-timeout
, client-body-timeout
和 keep-alive
Nginx 选项。
调整超时
如果您的群集通过 IBM Cloud Cloud Internet Services (CIS) / Cloudflare 公开,并使用 Web 应用程序防火墙 (WAF) 或全局负载平衡,则应将位于 kube-system
命名空间内的 ibm-k8s-controller-config
资源中的 client-header-timeout
、client-body-timeout
和 keep-alive
参数设置为超过 900 秒的值,以防止连接过早终止。 有关详细信息,请参阅 Cloudflare 文档。
-
更新
kube-system
命名空间内ibm-k8s-controller-config
ConfigMap 中的client-header-timeout
、client-body-timeout
和keep-alive
参数。 将每个参数设置为 905 秒的命令示例如下:kubectl patch cm --patch '{"data": {"client-header-timeout": "905", "client-body-timeout": "905", "keep-alive": "905"}}' --type=merge -n kube-system ibm-k8s-controller-config
-
仅 VPC 群集:还需要修改 VPC 负载平衡器的空闲连接超时。 调整
public-cr<clusterid>
LoadBalancer 服务的超时。 将其设置为 910 秒的命令示例如下:kubectl annotate svc -n kube-system public-cr<clusterid> service.kubernetes.io/ibm-load-balancer-cloud-provider-vpc-idle-connection-timeout="910"
调整 ALB 性能
要优化 Ingress ALB 的性能,可以根据需要更改缺省设置。
启用日志缓冲和清空超时
缺省情况下,Ingress ALB 记录到达的每个请求。 如果环境使用频繁,那么记录到达的每个请求可能会大幅提升磁盘 I/O 利用率。 为避免连续磁盘 I/O,可通过编辑 ibm-k8s-controller-config
Ingress ConfigMap 为 ALB 启用日志缓冲和刷新超时。 在启用缓冲时,不用针对每个日志条目执行单独的写操作,ALB 会缓冲一系列条目并在单个操作中将它们一起写入到文件。
-
编辑
ibm-k8s-controller-config
ConfigMap。kubectl edit cm ibm-k8s-controller-config -n kube-system
-
设置 ALB 向日志写入缓冲内容的阈值。
- 缓冲区大小:添加
buffer
字段,并将其设置为在 ALB 将缓冲区内容写入日志文件之前,缓冲区可容纳的日志内存大小。 例如,如果使用100KB
的默认值,则每当缓冲区的日志内容达到 100KB 时,ALB 就会将缓冲区内容写入日志文件。 - 时间间隔:添加
flush
字段,并将其设置为 ALB 向日志文件写入的频率。 例如,如果使用默认值5m
,ALB 将每 5 分钟向日志文件写入一次缓冲区内容。 - 时间间隔或缓冲区大小:同时设置
flush
和buffer
时,ALB 会根据最先满足的阈值参数将缓冲区内容写入日志文件。
apiVersion: v1 kind: ConfigMap data: access-log-params: "buffer=100KB, flush=5m" metadata: name: ibm-k8s-controller-config ...
- 缓冲区大小:添加
-
保存并关闭配置文件。 更改会自动应用于 ALB。
-
验证 ALB 的日志现在是否包含根据您设置的内存大小或时间间隔编写的缓冲内容。
kubectl logs -n kube-system <ALB_ID> -c nginx-ingress
更改保持活动连接的数量或持续时间
保持活动连接通过减少打开和关闭连接所需的 CPU 和网络使用量,会对性能产生重大影响。 要优化 ALB 的性能,您可以更改 ALB 和客户机之间保持活动连接的最大数量以及保持活动连接可持续的时间。
-
编辑
ibm-k8s-controller-config
ConfigMap。kubectl edit cm ibm-k8s-controller-config -n kube-system
-
更改
keep-alive-requests
和keep-alive
的值。keep-alive-requests
:可保持向 Ingress ALB 打开的保持活动客户机连接的数量。 缺省值为100
。keep-alive
:超时(以秒为单位),在此期间保持活动客户机连接将保持向 Ingress ALB 打开。 缺省值为75
。
apiVersion: v1 data: keep-alive-requests: 100 keep-alive: 75 kind: ConfigMap metadata: name: ibm-k8s-controller-config ...
-
保存并关闭配置文件。 更改会自动应用于 ALB。
-
验证是否已应用配置映射更改。
kubectl get cm ibm-k8s-controller-config -n kube-system -o yaml
更改同时连接数或工作程序进程数
更改一个 ALB 的 NGINX 工作程序进程可以处理的同时连接数或一个 ALB 可以发生的工作程序进程数的缺省设置。
每个 ALB 都有 NGINX 工作程序进程,用于处理客户机连接并与 ALB 公开的应用程序的上游服务器进行通信。 通过更改每个 ALB 的工作程序进程数或工作程序进程可以处理的连接数,可以管理 ALB 可以处理的最大客户机数。 使用以下公式计算最大客户机连接数: maximum clients = worker_processes * worker_connections
。
max-worker-connections
字段设置一个 ALB 的 NGINX 工作程序进程可处理的最大并发连接数。 默认值为16384
。 请注意,max-worker-connections
参数包含 ALB 代理的所有连接,而不仅仅是与客户机的连接。 此外,实际同时连接数不能超过 最大打开文件数限制(由max-worker-open-files
参数设置)。 如果将max-worker-connections
的值设置为0
,那么将改为使用max-worker-open-files
的值。worker-processes
字段设置一个 ALB 的 NGINX 工作程序进程的最大数目。 缺省值为"auto"
,指示工作程序进程数与部署 ALB 的工作程序节点上的核心数相匹配。 如果工作程序进程必须执行高级别 I/0 操作,那么可以将此值更改为数字。
-
编辑
ibm-k8s-controller-config
ConfigMap。kubectl edit cm ibm-k8s-controller-config -n kube-system
-
更改
max-worker-connections
或worker-processes
的值。apiVersion: v1 data: max-worker-connections: 16384 worker-processes: "auto" kind: ConfigMap metadata: name: ibm-k8s-controller-config ...
-
保存配置文件。 更改会自动应用于 ALB。
-
验证是否已应用配置映射更改。
kubectl get cm ibm-k8s-controller-config -n kube-system -o yaml
更改工作程序进程的打开文件数
更改 ALB 的每个工作程序节点进程可打开的文件数的缺省最大值。
每个 ALB 都有 NGINX 工作程序进程,用于处理客户机连接并与 ALB 公开的应用程序的上游服务器进行通信。 如果工作程序进程达到可打开的最大文件数,那么您可能会在 NGINX 日志中看到 Too many open files
错误。 缺省情况下,max-worker-open-files
参数设置为 0
,这指示将使用以下公式中的值: system limit of maximum open files / worker-processes - 1024
。
如果将值更改为另一个整数,那么公式不再适用。
-
编辑
ibm-k8s-controller-config
ConfigMap。kubectl edit cm ibm-k8s-controller-config -n kube-system
-
更改
max-worker-open-files
的值。apiVersion: v1 data: max-worker-open-files: 0 kind: ConfigMap metadata: name: ibm-k8s-controller-config ...
-
保存配置文件。 更改会自动应用于 ALB。
-
验证是否已应用配置映射更改。
kubectl get cm ibm-k8s-controller-config -n kube-system -o yaml
调整内核性能
要优化 Ingress ALB 的性能,您还可以更改工作程序节点上的 Linux 内核 sysctl
参数。 工作程序节点会根据优化的内核调整自动进行供应,因此仅在具有特定性能优化需求时才更改这些设置。