第 12 章 自定义资源 API 参考
12.1. 常见配置属性 复制链接链接已复制到粘贴板!
常见配置属性适用于多个资源。
12.1.1. replicas 复制链接链接已复制到粘贴板!
使用 replicas
属性配置副本。
复制的类型取决于资源。
-
KafkaTopic
使用复制因素来配置 Kafka 集群中每个分区的副本数。 - Kafka 组件使用副本来配置部署中的 pod 数量,以提供更好的可用性和可扩展性。
在 OpenShift 上运行 Kafka 组件时,可能不需要运行多个副本以实现高可用性。部署组件的节点崩溃时,OpenShift 会自动将 Kafka 组件 pod 重新调度到不同的节点。但是,使用多个副本运行 Kafka 组件可更快地出现故障转移时间,因为其他节点将启动并运行。
12.1.2. bootstrapServers 复制链接链接已复制到粘贴板!
使用 bootstrapServers
属性配置 bootstrap 服务器列表。
bootstrap 服务器列表可以引用没有在同一 OpenShift 集群中部署的 Kafka 集群。它们也可以引用 AMQ Streams 未部署的 Kafka 集群。
如果在同一 OpenShift 集群中,每个列表必须最好包含名为 CLUSTER-NAME-kafka-bootstrap 和端口号的 Kafka 集群 bootstrap
服务。如果 AMQ Streams 但在不同的 OpenShift 集群上部署,列表内容取决于用来公开集群的方法(路由、入口、节点端口或负载均衡器)。
当将 Kafka 与 AMQ Streams 管理的 Kafka 集群一起使用时,您可以根据给定集群的配置指定 bootstrap 服务器列表。
12.1.3. ssl 复制链接链接已复制到粘贴板!
使用特定 密码套件 作为 TLS 版本,为客户端连接使用三个允许的 ssl
配置选项。密码套件结合了用于安全连接和数据传输的算法。
您还可以配置 ssl.endpoint.identification.algorithm
属性来启用或禁用主机名验证。
SSL 配置示例
12.1.4. trustedCertificates 复制链接链接已复制到粘贴板!
将 tls
设置为配置 TLS 加密后,使用 trustedCertificates
属性提供一个 secret 列表,并在其中提供存储为 X.509 格式的密钥名称。
您可以使用 Cluster Operator 为 Kafka 集群创建的 secret,或者您可以使用自己的 TLS 证书文件,然后从文件创建 Secret
:
oc create secret generic MY-SECRET \ --from-file=MY-TLS-CERTIFICATE-FILE.crt
oc create secret generic MY-SECRET \
--from-file=MY-TLS-CERTIFICATE-FILE.crt
TLS 加密配置示例
如果证书存储在同一 secret 中,可以多次列出它。
如果要启用 TLS 加密,但使用 Java 附带的默认公共证书颁发机构集合,您可以指定 trustedCertificates
作为空数组:
使用默认 Java 证书启用 TLS 的示例
tls: trustedCertificates: []
tls:
trustedCertificates: []
有关配置 mTLS 验证的详情,请参考 KafkaClientAuthenticationTls
schema 引用。
12.1.5. 资源 复制链接链接已复制到粘贴板!
配置 资源的 requests 和 limits,以控制 AMQ Streams 容器的资源。您可以为 memory
和 cpu
资源指定 requests 和 limits。请求应该足以确保 Kafka 的稳定性能。
如何在生产环境中配置资源取决于多个因素。例如,应用可能会在 OpenShift 集群中共享资源。
对于 Kafka,部署的以下方面可能会影响您需要的资源:
- 消息吞吐量和大小
- 处理消息的网络线程数量
- 制作者和消费者的数量
- 主题和分区的数量
为资源请求指定的值会被保留,并始终可供容器使用。资源限值指定给定容器可以消耗的最大资源。请求和限制之间的数量不是保留的,可能并不总是可用。容器仅可在有限制时才使用最多的资源。资源限值是临时的,可重新分配。
资源请求和限值
如果您在设置限制时没有设置请求,或反之,OpenShift 会将相同的值用于限制和请求。为资源保证服务质量设置相等的请求和限值,因为 OpenShift 不会终止容器,除非容器超过其限值。
您可以为一个或多个支持的资源配置资源请求和限值。
资源配置示例
Topic Operator 和 User Operator 的资源请求和限值在 Kafka
资源中设置。
如果资源请求超过 OpenShift 集群中的可用可用资源,则 pod 不会被调度。
AMQ Streams 使用 OpenShift 语法来指定 内存
和 cpu
资源。有关在 OpenShift 中管理计算资源的更多信息,请参阅管理容器的计算资源。
- 内存资源
在配置内存资源时,请考虑组件的总要求。
Kafka 在 JVM 中运行,并使用操作系统页面缓存在写入磁盘前存储消息数据。Kafka 的内存请求应该适合 JVM 堆和页面缓存。您可以配置
jvmOptions
属性 来控制最小和最大堆大小。其他组件不依赖于页面缓存。您可以在不配置
jvmOptions
的情况下,控制堆大小的情况下配置内存资源。内存请求和限值以兆字节、千兆字节和千兆字节为单位指定。在规格中使用以下后缀:
-
M
表示 MB -
g
代表千兆字节 -
Mi
代表兆字节 -
Gi
代表千兆字节
使用不同内存单元的资源示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 有关内存规格和其他支持的单元的详情,请参考。
-
- CPU 资源
CPU 请求应该足以随时提供可靠的性能。CPU 请求和限制指定为 cores 或 millicpus/millicores。
CPU 内核指定为整数(
5
个 CPU 内核)或十进制(2.5
CPU 内核)。1000 毫秒 与1
个 CPU 内核相同。CPU 单元示例
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 1 个 CPU 内核的计算功能可能因部署 OpenShift 的平台而异。
有关 CPU 规格的更多信息,请参阅 CPU 机制。
12.1.6. image 复制链接链接已复制到粘贴板!
使用 image
属性配置组件使用的容器镜像。
只有在需要使用不同容器 registry 或自定义镜像的特殊情况下,才建议覆盖容器镜像。
例如,如果您的网络不允许访问 AMQ Streams 使用的容器存储库,您可以复制 AMQ Streams 镜像或从源进行构建。但是,如果配置的镜像与 AMQ Streams 镜像不兼容,它可能无法正常工作。
容器镜像的副本也可以进行自定义并可用于调试。
您可以使用以下资源中的 image
属性指定要用于组件的容器镜像:
-
Kafka.spec.kafka
-
Kafka.spec.zookeeper
-
Kafka.spec.entityOperator.topicOperator
-
Kafka.spec.entityOperator.userOperator
-
Kafka.spec.entityOperator.tlsSidecar
-
KafkaConnect.spec
-
KafkaMirrorMaker.spec
-
KafkaMirrorMaker2.spec
-
KafkaBridge.spec
为 Kafka、Kafka Connect 和 Kafka MirrorMaker 配置 镜像属性
Kafka、Kafka Connect 和 Kafka MirrorMaker 支持多个 Kafka 版本。每个组件都需要自己的镜像。不同 Kafka 版本的默认镜像在以下环境变量中配置:
-
STRIMZI_KAFKA_IMAGES
-
STRIMZI_KAFKA_CONNECT_IMAGES
-
STRIMZI_KAFKA_MIRROR_MAKER_IMAGES
这些环境变量包含 Kafka 版本及其对应镜像之间的映射。映射与 镜像和
版本
属性一起使用:
-
如果自定义资源中未给出
image
和version
,则版本
将默认为 Cluster Operator 的默认 Kafka 版本,且镜像将是环境变量中与此版本对应的镜像。 -
如果给定
镜像
但不提供版本
,则使用给定镜像,并且假定
版本为 Cluster Operator 的默认 Kafka 版本。 -
如果给出了
版本
,但镜像
不是,则使用环境变量中与给定版本对应的镜像。 -
如果同时指定了
version
和镜像
,则使用给定的镜像。镜像假定为包含带有给定版本的 Kafka 镜像。
不同组件的 image
和 version
可在以下属性中配置:
-
对于
spec.kafka.image
和spec.kafka.version
中的 Kafka。 -
对于
spec.image
和spec.version
中的 Kafka Connect 和 Kafka MirrorMaker。
建议您仅提供 version
,并不指定 image
属性。这可减少配置自定义资源时出错的机会。如果您需要更改用于不同版本的 Kafka 的镜像,最好配置 Cluster Operator 的环境变量。
在其他资源中配置 image
属性
对于其他自定义资源中的 image
属性,在部署期间将使用给定值。如果缺少 image
属性,则会使用 Cluster Operator 配置中指定 的镜像
。如果 Cluster Operator 配置中没有定义镜像
名称,则使用默认值。
对于主题 Operator:
-
在
STRIMZI_DEFAULT_TOPIC_OPERATOR_IMAGE
环境变量中指定的容器镜像。 -
registry.redhat.io/amq7/amq-streams-rhel8-operator:2.3.0
容器镜像。
-
在
对于 User Operator:
-
在
STRIMZI_DEFAULT_USER_OPERATOR_IMAGE
环境变量中指定的容器镜像。 -
registry.redhat.io/amq7/amq-streams-rhel8-operator:2.3.0
容器镜像。
-
在
对于实体 Operator TLS sidecar:
-
在
STRIMZI_DEFAULT_TLS_SIDECAR_ENTITY_OPERATOR_IMAGE
环境变量中指定的容器镜像。 -
registry.redhat.io/amq7/amq-streams-kafka-33-rhel8:2.3.0
container image.
-
在
对于 Kafka 导出器:
-
在 Cluster Operator 配置中的
STRIMZI_DEFAULT_KAFKA_EXPORTER_IMAGE
环境变量中指定的容器镜像。 -
registry.redhat.io/amq7/amq-streams-kafka-33-rhel8:2.3.0
container image.
-
在 Cluster Operator 配置中的
对于 Kafka Bridge:
-
在 Cluster Operator 配置中的
STRIMZI_DEFAULT_KAFKA_BRIDGE_IMAGE
环境变量中指定的容器镜像。 -
registry.redhat.io/amq7/amq-streams-bridge-rhel8:2.3.0
container image.
-
在 Cluster Operator 配置中的
对于 Kafka 代理初始化器:
-
在 Cluster Operator 配置中的
STRIMZI_DEFAULT_KAFKA_INIT_IMAGE
环境变量中指定的容器镜像。 -
registry.redhat.io/amq7/amq-streams-rhel8-operator:2.3.0
容器镜像。
-
在 Cluster Operator 配置中的
容器镜像配置示例
12.1.7. livenessProbe 和 readinessProbe 状况检查 复制链接链接已复制到粘贴板!
使用 livenessProbe
和 readinessProbe
属性配置 AMQ Streams 中支持的健康检查探测。
状况检查是定期测试,验证应用程序的健康状态。当 Healthcheck 探测失败时,OpenShift 会假定应用处于健康状态,并尝试修复它。
有关探测的详情,请参阅配置存活度和就绪度探测。
livenessProbe
和 readinessProbe
支持以下选项:
-
initialDelaySeconds
-
timeoutSeconds
-
periodSeconds
-
successThreshold
-
failureThreshold
存活度和就绪度探测配置示例
有关 livenessProbe
和 readinessProbe
选项的更多信息,请参阅 探测模式参考。
12.1.8. metricsConfig 复制链接链接已复制到粘贴板!
使用 metricsConfig
属性来启用和配置 Prometheus 指标。
metricsConfig
属性包含对 ConfigMap 的引用,该 ConfigMap 具有 Prometheus JMX Exporter 的额外配置。AMQ Streams 支持使用 Prometheus JMX exporter 的 Prometheus 指标,将 Apache Kafka 和 ZooKeeper 支持的 JMX 指标转换为 Prometheus 指标。
要在不进一步配置的情况下启用 Prometheus metrics 导出,您可以在 metricsConfig.valueFrom.configMapKeyRef.key
下引用包含空文件的 ConfigMap。当引用空文件时,所有指标都会公开,只要它们尚未重命名。
带有 Kafka 指标配置的 ConfigMap 示例
Kafka 的指标配置示例
启用指标后,它们会在端口 9404 上公开。
当资源中没有定义 metricsConfig
(或已弃用 指标
)属性时,会禁用 Prometheus 指标。
有关设置和部署 Prometheus 和 Grafana 的更多信息,请参阅在 OpenShift 指南中的部署和升级 AMQ Streams 中将 指标引入到 Kafka。
12.1.9. jvmOptions 复制链接链接已复制到粘贴板!
以下 AMQ Streams 组件在 Java 虚拟机(JVM)中运行:
- Apache Kafka
- Apache ZooKeeper
- Apache Kafka Connect
- Apache Kafka MirrorMaker
- AMQ Streams Kafka Bridge
要在不同平台和构架中优化其性能,您可以在以下资源中配置 jvmOptions
属性:
-
Kafka.spec.kafka
-
Kafka.spec.zookeeper
-
Kafka.spec.entityOperator.userOperator
-
Kafka.spec.entityOperator.topicOperator
-
Kafka.spec.cruiseControl
-
KafkaConnect.spec
-
KafkaMirrorMaker.spec
-
KafkaMirrorMaker2.spec
-
KafkaBridge.spec
您可以在配置中指定以下选项:
-Xms
- JVM 启动后最少初始分配堆大小
-Xmx
- 最大堆大小
-XX
- JVM 的高级运行时选项
javaSystemProperties
- 其他系统属性
gcLoggingEnabled
- 启用垃圾收集器日志记录
JVM 设置(如 -Xmx
和 -Xms
)接受的单元与对应镜像中 JDK java
二进制文件接受的单元相同。因此,1g
或 1G
表示 1、073、741、824 字节,Gi
不是有效的单元后缀。这与用于 内存请求和限制的单元不同,它遵循 OpenShift 约 1G
表示 1,000,000,000 字节,1Gi
表示 1,073,741,824 字节。
-Xms
和 -Xmx
选项
除了为容器设置内存请求和限制值外,您还可以使用 -Xms
和 -Xmx
JVM 选项为您的 JVM 设置特定的堆大小。使用 -Xms
选项设置初始堆大小和 -Xmx
选项,以设置最大堆大小。
指定堆大小,以便对分配给 JVM 的内存拥有更多控制权。堆大小应该最好地使用容器 的内存限值(和请求), 而不超过它。堆大小和任何其他内存要求需要在指定的内存限值内容纳。如果您没有在配置中指定堆大小,但配置内存资源限制(和请求),Cluster Operator 会自动实施默认堆大小。Cluster Operator 根据内存资源配置百分比设置默认的最大值和最小堆值。
下表显示了默认的堆值。
组件 | 分配给堆的可用内存百分比 | 最大限制 |
---|---|---|
Kafka | 50% | 5 GB |
ZooKeeper | 75% | 2 GB |
Kafka Connect | 75% | None |
MirrorMaker 2.0 | 75% | None |
MirrorMaker | 75% | None |
Sything Control | 75% | None |
Kafka Bridge | 50% | 31 Gi |
如果没有指定内存限制(和请求),则 JVM 的最小堆大小设为 128M
。JVM 的最大堆大小没有被定义,以允许内存根据需要增加。这是测试和开发中单一节点环境的理想选择。
设置适当的内存请求可能会阻止以下内容:
- 如果节点上运行的其他容器集的内存压力,OpenShift 会终止容器。
-
OpenShift 将容器调度到内存不足的节点。如果
-Xms
设为-Xmx
,则容器将立即崩溃;如果没有,则容器将在以后崩溃。
在本例中,JVM 将 2 GiB (=2,147,483,648 字节)用于其堆。JVM 内存用量总量可能比最大堆大小大。
示例 -Xmx
和 -Xms
配置
# ... jvmOptions: "-Xmx": "2g" "-Xms": "2g" # ...
# ...
jvmOptions:
"-Xmx": "2g"
"-Xms": "2g"
# ...
为初始(-Xms
)和最大值(-Xmx
)堆大小设置相同的值可以避免 JVM 必须在启动时分配内存,因为可能分配比真正需要的堆多。
容器执行大量磁盘 I/O,如 Kafka 代理容器,需要可用内存用作操作系统页面缓存。对于这些容器,请求的内存应显著大于 JVM 使用的内存。
-XX 选项
-XX
选项用于配置 Apache Kafka 的 KAFKA_JVM_PERFORMANCE_OPTS
选项。
示例 -XX
配置
由 -XX
配置生成的 JVM 选项
-XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:+ExplicitGCInvokesConcurrent -XX:-UseParNewGC
-XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:+ExplicitGCInvokesConcurrent -XX:-UseParNewGC
如果没有指定 -XX
选项,则使用 KAFKA_JVM_PERFORMANCE_OPTS
的默认 Apache Kafka 配置。
javaSystemProperties
javaSystemProperties
用于配置其他 Java 系统属性,如调试实用程序。
javaSystemProperties
配置示例
jvmOptions: javaSystemProperties: - name: javax.net.debug value: ssl
jvmOptions:
javaSystemProperties:
- name: javax.net.debug
value: ssl
有关 jvmOptions
的更多信息,请参见 JvmOptions
模式参考。
12.1.10. 垃圾收集器日志记录 复制链接链接已复制到粘贴板!
jvmOptions
属性还允许您启用和禁用垃圾回收器(GC)日志记录。GC 日志记录默认为禁用。要启用它,请按如下所示设置 gcLoggingEnabled
属性:
GC 日志记录配置示例
# ... jvmOptions: gcLoggingEnabled: true # ...
# ...
jvmOptions:
gcLoggingEnabled: true
# ...