7.3. Ingress Controller 配置参数

ingresscontrollers.operator.openshift.io 资源提供了以下配置参数。

参数描述

domain

domain 是 Ingress Controller 服务的一个 DNS 名称，用于配置多个功能：

  • 对于 LoadBalancerService 端点发布策略，domain 被用来配置 DNS 记录。请参阅 endpointPublishingStrategy。
  • 当使用生成的默认证书时，该证书对域及其子域有效。请参阅 defaultCertificate。
  • 该值会发布到独立的 Route 状态，以便用户了解目标外部 DNS 记录的位置。

domain 值在所有 Ingress 控制器中需要是唯一的，且不能更新。

如果为空，默认值为 ingress.config.openshift.io/cluster .spec.domain。

replicas

replicas 是 Ingress 控制器副本数量。如果没有设置，则默认值为 2。

endpointPublishingStrategy

endpointPublishingStrategy 用于向其他网络发布 Ingress Controller 端点，以启用负载均衡器集成，并提供对其他系统的访问。

在 GCP、AWS 和 Azure 上，您可以配置以下 endpointPublishingStrategy 字段：

  • loadBalancer.scope
  • loadBalancer.allowedSourceRanges

如果没有设置，则默认值基于 infrastructure.config.openshift.io/cluster .status.platform：

  • Amazon Web Services (AWS): LoadBalancerService (带有外部范围)
  • Azure: LoadBalancerService （具有外部范围）
  • Google Cloud Platform(GCP)： LoadBalancerService （具有外部范围）
  • 裸机: NodePortService

  • 其它: HostNetwork

    注意

    HostNetwork 有一个 hostNetwork 字段，它有以下用于可选绑定端口的默认值：httpPort: 80,httpsPort: 443, 和 statsPort: 1936。使用绑定端口，您可以为 HostNetwork 策略在同一节点上部署多个 Ingress Controller。

    Example

    apiVersion: operator.openshift.io/v1
kind: IngressController
metadata:
  name: internal
  namespace: openshift-ingress-operator
spec:
  domain: example.com
  endpointPublishingStrategy:
    type: HostNetwork
    hostNetwork:
      httpPort: 80
      httpsPort: 443
      statsPort: 1936

    注意

    在 Red Hat OpenStack Platform (RHOSP) 上，只有云供应商配置为创建运行状况监视器时，才会支持 LoadBalancerService 端点发布策略。对于 RHOSP 16.2，只有在您使用 Amphora Octavia 供应商时，才能使用此策略。

    如需更多信息，请参阅 RHOSP 安装文档中的"设置云供应商选项"部分。

对于大多数平台，可以更新 endpointPublishingStrategy 值。在 GCP 上，您可以配置以下 endpointPublishingStrategy 字段：

  • loadBalancer.scope
  • loadbalancer.providerParameters.gcp.clientAccess
  • hostNetwork.protocol
  • nodePort.protocol

defaultCertificate

defaultCertificate 的值是一个到包括由 Ingress controller 提供的默认证书的 secret 的指代。当 Routes 没有指定其自身证书时，使用 defaultCertificate。

secret 必须包含以下密钥和数据：* tls.crt：证书文件内容 * tls.key：密钥文件内容

如果没有设置，则自动生成和使用通配符证书。该证书对 Ingress Controller 的域 和子域有效，所生成的证书的 CA 会自动与集群的信任存储集成。

内部证书（无论是生成的证书还是用户指定的证书）自动与 OpenShift Container Platform 内置的 OAuth 服务器集成。

namespaceSelector

namespaceSelector 用来过滤由 Ingress 控制器提供服务的一组命名空间。这对实现分片（shard）非常有用。

routeSelector

routeSelector 用于由 Ingress Controller 提供服务的一组 Routes。这对实现分片（shard）非常有用。

nodePlacement

NodePlacement 启用对 Ingress Controller 调度的显式控制。

如果没有设置，则使用默认值。

注意

nodePlacement 参数包括两个部分: nodeSelector 和 tolerations。例如： 

nodePlacement:
 nodeSelector:
   matchLabels:
     kubernetes.io/os: linux
 tolerations:
 - effect: NoSchedule
   operator: Exists

tlsSecurityProfile

tlsSecurityProfile 指定 Ingress Controller 的 TLS 连接的设置。

如果没有设置，则默认值基于 apiservers.config.openshift.io/cluster 资源。

当使用 Old、Intermediate 和 Modern配置集类型时，有效的配置集可能会在不同发行版本间有所改变。例如：使用在版本 X.Y.Z 中部署的 Intermediate 配置集，升级到版本 X.Y.Z+1 可能会导致新的配置集配置应用到 Ingress Controller，从而导致一个 rollout 操作。

Ingress Controller 的最低 TLS 版本是 1.1，最高 TLS 版本为 1.3。

注意

加密器和配置的安全配置集的最小 TLS 版本反映在 TLSProfile 状态中。

重要

Ingress Operator 将 Old 或 Custom 配置集的 TLS 1.0 转换为 1.1。

clientTLS

clientTLS 验证客户端对集群和服务的访问；因此，启用了 mutual TLS 身份验证。如果没有设置，则不启用客户端 TLS。

clientTLS 具有所需的子字段 spec.clientTLS.clientCertificatePolicy 和 spec.clientTLS.ClientCA。

ClientCertificatePolicy 子字段接受以下两个值之一：Required 或 Optional。ClientCA 子字段指定 openshift-config 命名空间中的配置映射。配置映射应包含 CA 证书捆绑包。

AllowedSubjectPatterns 是一个可选值，用于指定正则表达式列表，该列表与有效客户端证书上的可分辨名称匹配以过滤请求。正则表达式必须使用 PCRE 语法。至少一种模式必须与客户端证书的可分辨名称匹配；否则，入口控制器拒绝证书，并拒绝连接。如果没有指定，ingress 控制器不会根据可分辨的名称拒绝证书。

routeAdmission

routeAdmission 定义了处理新路由声明的策略，如允许或拒绝命名空间间的声明。

namespaceOwnership 描述了如何处理跨命名空间的主机名声明。默认为 Strict。

  • Strict：不允许路由在命名空间间声明相同的主机名。
  • InterNamespaceAllowed ：允许路由在命名空间间声明相同主机名的不同路径。

wildcardPolicy 描述了 Ingress Controller 如何处理采用通配符策略的路由。

  • WildcardsAllowed：表示 Ingress Controller 允许采用任何通配符策略的路由。
  • WildcardsDisallowed：表示 Ingress Controller 只接受采用 None 通配符策略的路由。将 wildcardPolicy 从 WildcardsAllowed 更新为 WildcardsDisallowed，会导致采用 Subdomain 通配符策略的已接受路由停止工作。这些路由必须重新创建为采用 None 通配符策略，让 Ingress Controller 重新接受。WildcardsDisallowed 是默认设置。

IngressControllerLogging

logging 定义了有关在哪里记录什么内容的参数。如果此字段为空，则会启用运行日志，但禁用访问日志。

  • access 描述了客户端请求的日志记录方式。如果此字段为空，则禁用访问日志。

    • destination 描述日志消息的目的地。

      • type 是日志的目的地类型：

        • Container 指定日志应该进入 sidecar 容器。Ingress Operator 在 Ingress Controller pod 上配置名为 logs 的容器，并配置 Ingress Controller 以将日志写入容器。管理员应该配置一个自定义日志记录解决方案，从该容器读取日志。使用容器日志意味着，如果日志速率超过容器运行时或自定义日志解决方案的容量，则可能会出现日志丢失的问题。
        • Syslog 指定日志发送到 Syslog 端点。管理员必须指定可以接收 Syslog 消息的端点。管理员应该已经配置了一个自定义 Syslog 实例。
      • container 描述了 Container 日志记录目的地类型的参数。目前没有容器日志记录参数，因此此字段必须为空。

      • syslog 描述了 Syslog 日志记录目的地类型的参数：

        • address 是接收日志消息的 syslog 端点的 IP 地址。
        • port 是接收日志消息的 syslog 端点的 UDP 端口号。
        • MaxLength 是 syslog 消息的最大长度。它必须介于 480 到 4096 字节之间。如果此字段为空，则最大长度设置为默认值 1024 字节。
        • facility 指定日志消息的 syslog 工具。如果该字段为空，则工具为 local1。否则,它必须指定一个有效的 syslog 工具： kern、user、mail、daemon、auth、 syslog, lpr, news, uucp, cron, auth2, ftp, ntp, audit, alert, cron2, local0, local1、local2、local3。local4、local5、local6 或 local7。
    • httpLogFormat 指定 HTTP 请求的日志消息格式。如果此字段为空，日志消息将使用实现中的默认 HTTP 日志格式。有关 HAProxy 的默认 HTTP 日志格式，请参阅 HAProxy 文档。

httpHeaders

httpHeaders 为 HTTP 标头定义策略。

通过为 IngressControllerHTTPHeaders 设置 forwardHeaderPolicy，您可以指定 Ingress 控制器何时和如何设置 Forwarded、X-Forwarded-For、X-Forwarded-Host、X-Forwarded-Port、X-Forwarded-Proto 和 X-Forwarded-Proto-Version HTTP 标头。

默认情况下，策略设置为 Append。

  • Append 指定 Ingress Controller 会附加标头，并保留任何现有的标头。
  • Replace 指定 Ingress Controller 设置标头，删除任何现有的标头。
  • IfNone 指定 Ingress Controller 在尚未设置标头时设置它们。
  • Never 指定 Ingress Controller 不会设置标头，并保留任何现有的标头。

通过设置 headerNameCaseAdjustments，您可以指定 HTTP 标头名对大小写的调整。每个调整都指定一个 HTTP 标头名称需要进行相关的大小写调整。例如，指定 X-Forwarded-For 表示 x-forwarded-for HTTP 标头应调整相应的大写。

这些调整仅应用于明文、边缘终止和重新加密路由，且仅在使用 HTTP/1 时有效。

对于请求标头，这些调整仅适用于具有 haproxy.router.openshift.io/h1-adjust-case=true 注解的路由。对于响应标头，这些调整适用于所有 HTTP 响应。如果此字段为空，则不会调整任何请求标头。

httpCompression

httpCompression 定义 HTTP 流量压缩的策略。

  • mimeTypes 定义应该将压缩应用到的 MIME 类型列表。例如，text/css; charset=utf-8, text/html, text/*, image/svg+xml, application/octet-stream, X-custom/customsub，格式为 type/subtype; [;attribute=value]。types 是：application, image, message, multipart, text, video, 或一个自定义类型（前面带有一个 X-；如需更详细的 MIME 类型和子类型的信息，请参阅 RFC1341

httpErrorCodePages

httpErrorCodePages 指定自定义 HTTP 错误代码响应页面。默认情况下，IngressController 使用 IngressController 镜像内构建的错误页面。

httpCaptureCookies

httpCaptureCookies 指定您要在访问日志中捕获的 HTTP cookie。如果 httpCaptureCookies 字段为空，则访问日志不会捕获 Cookie。

对于您要捕获的任何 Cookie，以下参数必须位于 IngressController 配置中：

  • name 指定 Cookie 的名称。
  • MaxLength 指定 Cookie 的最大长度。
  • matchType 指定 Cookie 的 name 字段是否与捕获 Cookie 设置完全匹配，或者是捕获 Cookie 设置的前缀。matchType 字段使用 Exact 和 Prefix 参数。

例如： 

  httpCaptureCookies:
  - matchType: Exact
    maxLength: 128
    name: MYCOOKIE

httpCaptureHeaders

httpCaptureHeaders 指定要在访问日志中捕获的 HTTP 标头。如果 httpCaptureHeaders 字段为空，则访问日志不会捕获标头。

httpCaptureHeaders 包含两个要在访问日志中捕获的标头列表。这两个标题字段列表是 request 和 response。在这两个列表中，name 字段必须指定标头名称和 maxlength 字段，必须指定标头的最大长度。例如： 

  httpCaptureHeaders:
    request:
    - maxLength: 256
      name: Connection
    - maxLength: 128
      name: User-Agent
    response:
    - maxLength: 256
      name: Content-Type
    - maxLength: 256
      name: Content-Length

tuningOptions

tuningOptions 指定用于调整 Ingress Controller pod 性能的选项。

  • clientFinTimeout 指定连接在等待客户端响应关闭连接时保持打开的时长。默认超时为 1s。
  • clientTimeout 指定连接在等待客户端响应时保持打开的时长。默认超时为 30s。
  • headerBufferBytes 为 Ingress Controller 连接会话指定保留多少内存（以字节为单位）。如果为 Ingress Controller 启用了 HTTP/2，则必须至少为 16384。如果没有设置，则默认值为 32768 字节。不建议设置此字段，因为 headerBufferBytes 值太小可能会破坏 Ingress Controller，而 headerBufferBytes 值过大可能会导致 Ingress Controller 使用比必要多的内存。
  • headerBufferMaxRewriteBytes 指定从 headerBufferBytes 为 Ingress Controller 连接会话保留多少内存（以字节为单位），用于 HTTP 标头重写和附加。headerBufferMaxRewriteBytes 的最小值是 4096。headerBufferBytes 必须大于 headerBufferMaxRewriteBytes，用于传入的 HTTP 请求。如果没有设置，则默认值为 8192 字节。不建议设置此字段，因为 headerBufferMaxRewriteBytes 值可能会破坏 Ingress Controller，headerBufferMaxRewriteBytes 值太大可能会导致 Ingress Controller 使用比必要大得多的内存。
  • healthCheckInterval 指定路由器在健康检查之间等待的时间。默认值为 5s。
  • serverFinTimeout 指定连接在等待服务器响应关闭连接时保持打开的时长。默认超时为 1s。
  • serverTimeout 指定连接在等待服务器响应时保持打开的时长。默认超时为 30s。
  • threadCount 指定每个 HAProxy 进程创建的线程数量。创建更多线程可让每个 Ingress Controller pod 处理更多连接，而代价会增加所使用的系统资源。HAProxy 支持多达 64 个线程。如果此字段为空，Ingress Controller 将使用默认值 4 个线程。默认值可能会在以后的版本中改变。不建议设置此字段，因为增加 HAProxy 线程数量可让 Ingress Controller pod 在负载下使用更多 CPU 时间，并阻止其他 pod 收到需要执行的 CPU 资源。减少线程数量可能会导致 Ingress Controller 执行不佳。
  • tlsInspectDelay 指定路由器可以保存数据以查找匹配的路由的时长。如果把这个值设置得太短，对于 edge-terminated, reencrypted, 或 passthrough 的路由，则可能会导致路由器回退到使用默认证书，即使正在使用一个更加匹配的证书时也是如此。默认检查延迟为 5s。
  • tunnelTimeout 指定隧道连接在隧道闲置期间保持打开的时长，包括 websockets。默认超时为 1h。

  • maxConnections 指定每个 HAProxy 进程可建立的最大同时连接数。增加这个值可让每个入口控制器 pod 以额外的系统资源成本处理更多连接。允许的值是 0、-1、以及范围为 2000 和 2000000 内的任何值，或者字段可以留空。

    • 如果此字段留空，或者值为 0，Ingress Controller 将使用默认值 50000。这个值可能在以后的版本中有所改变。
    • 如果字段的值为 -1，则 HAProxy 将根据运行中容器中的可用 ulimits 动态计算最大值。与当前默认值 50000 相比，此进程会产生很大的内存用量。
    • 如果字段的值大于当前操作系统的限制，则 HAProxy 进程将不会启动。
    • 如果您选择了一个离散值，并且路由器 pod 迁移到新节点，则新节点可能没有配置相同的 ulimit。在这种情况下，pod 无法启动。
    • 如果您配置了不同的 ulimits 的节点，并且您选择离散值，则建议为该字段使用 -1 的值，以便在运行时计算连接的最大数量。

logEmptyRequests

logEmptyRequests 指定没有接收和记录请求的连接。这些空请求来自负载均衡器健康探测或 Web 浏览器规范连接(preconnect)，并记录这些请求。但是，这些请求可能是由网络错误导致的，在这种情况下，记录空请求可用于诊断错误。这些请求可能是由端口扫描导致的，记录空请求有助于检测入侵尝试。此字段允许的值有 Log 和 Ignore。默认值为 Log。

LoggingPolicy 类型接受以下两个值之一：

  • log ：将此值设置为 Log 表示应记录某一事件。
  • ignore ：将此值设置为 Ignore 会在 HAproxy 配置中设置 dontlognull 选项。

HTTPEmptyRequestsPolicy

HTTPEmptyRequestsPolicy 描述了在收到请求前发生超时时，如何处理 HTTP 连接。此字段允许的值是 Respond 和 Ignore。默认值为 Respond。

HTTPEmptyRequestsPolicy 类型接受以下两个值之一：

  • Respond：如果字段设置为 Respond，Ingress Controller 会发送 HTTP 400 或 408 响应，在启用了访问日志时记录连接，并在适当的指标中计数连接。
  • ignore：将这个选项设置为 Ignore 会在 HAproxy 配置中添加 http-ignore-probes 参数。如果字段设置为 Ignore，Ingnore 会在不发送响应的情况下关闭连接，然后记录连接或递增指标。

这些连接来自负载均衡器健康探测或 Web 浏览器规范连接（预连接），可以安全地忽略。但是，这些请求可能是由网络错误造成的，因此将此字段设置为 Ignore 可能会妨碍对问题的检测和诊断。这些请求可能是由端口扫描导致的，在这种情况下，记录空请求有助于检测入侵尝试。

注意

所有参数都是可选的。

7.3.1. Ingress Controller TLS 安全配置集

TLS 安全配置文件为服务器提供了一种方式，以规范连接的客户端在连接服务器时可以使用哪些密码。

7.3.1.1. 了解 TLS 安全配置集

您可以使用 TLS（Transport Layer Security）安全配置集来定义各种 OpenShift Container Platform 组件需要哪些 TLS 密码。OpenShift Container Platform TLS 安全配置集基于 Mozilla 推荐的配置。

您可以为每个组件指定以下 TLS 安全配置集之一：

表 7.1. TLS 安全配置集

profile描述

Old

此配置集用于旧的客户端或库。该配置集基于旧的向后兼容性建议配置。

Old 配置集要求最低 TLS 版本 1.0。

注意

对于 Ingress Controller，最小 TLS 版本从 1.0 转换为 1.1。

Intermediate

这个配置集是大多数客户端的建议配置。它是 Ingress Controller、kubelet 和 control plane 的默认 TLS 安全配置集。该配置集基于 Intermediate 兼容性推荐的配置。

Intermediate 配置集需要最小 TLS 版本 1.2。

Modern

此配置集主要用于不需要向后兼容的现代客户端。这个配置集基于 Modern 兼容性推荐的配置。

Modern 配置集需要最低 TLS 版本 1.3。

Custom

此配置集允许您定义要使用的 TLS 版本和密码。

警告

使用 Custom 配置集时要谨慎，因为无效的配置可能会导致问题。

注意

当使用预定义的配置集类型时，有效的配置集配置可能会在发行版本之间有所改变。例如，使用在版本 X.Y.Z 中部署的 Intermediate 配置集指定了一个规格，升级到版本 X.Y.Z+1 可能会导致应用新的配置集配置，从而导致推出部署。

7.3.1.2. 为 Ingress Controller 配置 TLS 安全配置集

要为 Ingress Controller 配置 TLS 安全配置集，请编辑 IngressController 自定义资源（CR）来指定预定义或自定义 TLS 安全配置集。如果没有配置 TLS 安全配置集，则默认值基于为 API 服务器设置的 TLS 安全配置集。

配置 Old TLS 安全配置集的 IngressController CR 示例

apiVersion: operator.openshift.io/v1
kind: IngressController
 ...
spec:
  tlsSecurityProfile:
    old: {}
    type: Old
 ...

TLS 安全配置集定义 Ingress Controller 的 TLS 连接的最低 TLS 版本和 TLS 密码。

您可以在 Status.Tls Profile 和 Spec.Tls Security Profile 下看到 IngressController 自定义资源（CR）中配置的 TLS 安全配置集的密码和最小 TLS 版本。对于 Custom TLS 安全配置集，这两个参数下列出了特定的密码和最低 TLS 版本。

注意

HAProxy Ingress Controller 镜像支持 TLS 1.3 和 Modern 配置集。

Ingress Operator 还会将 Old 或 Custom 配置集的 TLS 1.0 转换为 1.1。

先决条件

  • 您可以使用具有 cluster-admin 角色的用户访问集群。

流程

  1. 编辑 openshift-ingress-operator 项目中的 IngressController CR，以配置 TLS 安全配置集： 

    $ oc edit IngressController default -n openshift-ingress-operator

  2. 添加 spec.tlsSecurityProfile 字段：

    Custom 配置集的 IngressController CR 示例

    apiVersion: operator.openshift.io/v1
kind: IngressController
 ...
spec:
  tlsSecurityProfile:
    type: Custom 1
    custom: 2
      ciphers: 3
      - ECDHE-ECDSA-CHACHA20-POLY1305
      - ECDHE-RSA-CHACHA20-POLY1305
      - ECDHE-RSA-AES128-GCM-SHA256
      - ECDHE-ECDSA-AES128-GCM-SHA256
      minTLSVersion: VersionTLS11
 ...

    1
    指定 TLS 安全配置集类型（Old、Intermediate 或 Custom）。默认值为 Intermediate。
    2
    为所选类型指定适当的字段：
    • old: {}
    • intermediate: {}
    • custom:
    3
    对于 custom 类型，请指定 TLS 密码列表和最低接受的 TLS 版本。
  3. 保存文件以使改变生效。

验证

  • 验证 IngressController CR 中是否设置了配置集： 

    $ oc describe IngressController default -n openshift-ingress-operator

    输出示例

    Name:         default
Namespace:    openshift-ingress-operator
Labels:       <none>
Annotations:  <none>
API Version:  operator.openshift.io/v1
Kind:         IngressController
 ...
Spec:
 ...
  Tls Security Profile:
    Custom:
      Ciphers:
        ECDHE-ECDSA-CHACHA20-POLY1305
        ECDHE-RSA-CHACHA20-POLY1305
        ECDHE-RSA-AES128-GCM-SHA256
        ECDHE-ECDSA-AES128-GCM-SHA256
      Min TLS Version:  VersionTLS11
    Type:               Custom
 ...

7.3.1.3. 配置 mutual TLS 身份验证

您可以通过设置 spec.clientTLS 值，将 Ingress Controller 配置为启用 mutual TLS (mTLS) 身份验证。clientTLS 值将 Ingress Controller 配置为验证客户端证书。此配置包括设置 clientCA 值，这是对配置映射的引用。配置映射包含 PEM 编码的 CA 证书捆绑包，用于验证客户端的证书。另外，您还可以配置证书主题过滤器列表。

如果 clientCA 值指定了 X509v3 证书撤销列表 (CRL) 分发点，Ingress Operator 会下载并管理基于每个提供的证书中指定的 HTTP URI X509v3 CRL 分发点的 CRL 配置映射。Ingress Controller 在 mTLS/TLS 协商过程中使用此配置映射。不提供有效证书的请求将被拒绝。

先决条件

  • 您可以使用具有 cluster-admin 角色的用户访问集群。
  • 您有一个 PEM 编码的 CA 证书捆绑包。

  • 如果您的 CA 捆绑包引用 CRL 发布点，还必须将最终用户或叶证书包含在客户端 CA 捆绑包中。此证书必须在 CRL 分发点下包含 HTTP URI，如 RFC 5280 所述。例如： 

     Issuer: C=US, O=Example Inc, CN=Example Global G2 TLS RSA SHA256 2020 CA1
         Subject: SOME SIGNED CERT            X509v3 CRL Distribution Points:
                Full Name:
                  URI:http://crl.example.com/example.crl

流程

  1. 在 openshift-config 命名空间中，从 CA 捆绑包创建配置映射： 

    $ oc create configmap \
   router-ca-certs-default \
   --from-file=ca-bundle.pem=client-ca.crt \1
   -n openshift-config
    1
    配置映射数据键必须是 ca-bundle.pem，数据值必须是 PEM 格式的 CA 证书。

  2. 编辑 openshift-ingress-operator 项目中的 IngressController 资源： 

    $ oc edit IngressController default -n openshift-ingress-operator

  3. 添加 spec.clientTLS 字段和子字段来配置 mutual TLS：

    指定过滤模式的 clientTLS 配置集的 IngressController CR 示例

      apiVersion: operator.openshift.io/v1
  kind: IngressController
  metadata:
    name: default
    namespace: openshift-ingress-operator
  spec:
    clientTLS:
      clientCertificatePolicy: Required
      clientCA:
        name: router-ca-certs-default
      allowedSubjectPatterns:
      - "^/CN=example.com/ST=NC/C=US/O=Security/OU=OpenShift$"