第13章 カスタムリソース API のリファレンス

13.1. 共通の設定プロパティー

共通設定プロパティーは複数のリソースに適用されます。

13.1.1. replicas

replicas プロパティーを使用してレプリカを設定します。

レプリケーションのタイプはリソースによって異なります。

  • KafkaTopic はレプリケーション係数を使用して、Kafka クラスター内で各パーティションのレプリカ数を設定します。
  • Kafka コンポーネントはレプリカを使用してデプロイメントの Pod 数を設定し、可用性とスケーラビリティーを向上します。
注記

OpenShift で Kafka コンポーネントを実行している場合、高可用性のために複数のレプリカを実行する必要がない場合があります。コンポーネントがデプロイされたノードがクラッシュすると、OpenShift によって自動的に Kafka コンポーネント Pod が別のノードに再スケジュールされます。ただし、複数のレプリカで Kafka コンポーネントを実行すると、他のノードが稼働しているため、フェイルオーバー時間が短縮されます。

13.1.2. bootstrapServers

bootstrapServers プロパティーを使用してブートストラップサーバーのリストを設定します。

ブートストラップサーバーリストは、同じ OpenShift クラスターにデプロイされていない Kafka クラスターを参照できます。AMQ Streams によってデプロイされた Kafka クラスターを参照することもできます。

同じ OpenShift クラスターである場合、各リストに CLUSTER-NAME-kafka-bootstrap という名前の Kafka クラスターブートストラップサービスとポート番号が含まれる必要があります。AMQ Streams によって異なる OpenShift クラスターにデプロイされた場合、リストの内容はクラスターを公開するために使用された方法によって異なります (route、ingress、nodeport、または loadbalancer)。

AMQ Streams によって管理されない Kafka クラスターで Kafka を使用する場合は、指定のクラスターの設定に応じてブートストラップサーバーのリストを指定できます。

13.1.3. ssl

TLSバージョンの特定のcipher suiteを使用するクライアント接続には、3つの許可されたssl設定オプションを使用します。暗号スイートは、セキュアな接続とデータ転送のためのアルゴリズムを組み合わせます。

ssl.endpoint.identification.algorithm プロパティーを設定して、ホスト名の検証を有効または無効にすることもできます。

SSL の設定例

# ...
spec:
  config:
    ssl.cipher.suites: "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" 1
    ssl.enabled.protocols: "TLSv1.2" 2
    ssl.protocol: "TLSv1.2" 3
    ssl.endpoint.identification.algorithm: HTTPS 4
# ...

1
TLS の暗号スイートは、ECDHE 鍵交換メカニズム、RSA 認証アルゴリズム、AES 一括暗号化アルゴリズム、および SHA384 MAC アルゴリズムの組み合わせを使用します。
2
SSI プロトコル TLSv1.2 は有効になります。
3
TLSv1.2 プロトコルを指定し、SSL コンテキスト生成します。許可される値は TLSv1.1 および TLSv1.2 です。
4
ホスト名の検証は、HTTPS に設定して有効化されます。空の文字列を指定すると検証が無効になります。

13.1.4. trustedCertificates

tls を設定して TLS 暗号化を設定する場合は、trustedCertificates プロパティーを使用して、証明書が X.509 形式で保存されるキー名にシークレットの一覧を提供します。

Kafka クラスターの Cluster Operator によって作成されるシークレットを使用するか、独自の TLS 証明書ファイルを作成してから、ファイルから Secret を作成できます。

oc create secret generic MY-SECRET \
--from-file=MY-TLS-CERTIFICATE-FILE.crt

TLS による暗号化の設定例

tls:
  trustedCertificates:
    - secretName: my-cluster-cluster-cert
      certificate: ca.crt
    - secretName: my-cluster-cluster-cert
      certificate: ca2.crt

複数の証明書が同じシークレットに保存されている場合は、複数回リストできます。

TLS を有効にし、Java に同梱されるデフォルトの公開認証局のセットを使用する場合は、trustedCertificates を空の配列として指定できます。

デフォルトの Java 証明書で TLS を有効にする例

tls:
  trustedCertificates: []

TLS クライアント認証の設定に関する詳細は、KafkaClientAuthenticationTls schema reference を参照してください。

13.1.5. resources

コンポーネントの CPU およびメモリーリソースを要求します。制限は、特定のコンテナーが消費できる最大リソースを指定します。

Topic Operator および User Operator のリソース要求および制限は Kafka リソースに設定されます。

reources.requests および resources.limits プロパティーを使用して、リソース要求および制限を設定します。

AMQ Streams では、デプロイされたコンテナーごとに特定のリソースを要求し、これらのリソースの最大消費を定義できます。

AMQ Streams では、以下のリソースタイプの要求および制限がサポートされます。

  • cpu
  • memory

AMQ Streams では、このようなリソースの指定に OpenShift の構文が使用されます。

OpenShift におけるコンピュートリソースの管理に関する詳細は、「Managing Compute Resources for Containers」を参照してください。

リソース要求

要求によって、指定のコンテナーに対して予約するリソースが指定されます。リソースを予約すると、リソースが常に利用できるようになります。

重要

リソース要求が OpenShift クラスターで利用可能な空きリソースを超える場合、Pod はスケジュールされません。

1 つまたは複数のサポートされるリソースに対してリクエストを設定できます。

リソース要求の設定例

# ...
resources:
  requests:
    cpu: 12
    memory: 64Gi
# ...

リソース制限

制限によって、指定のコンテナーが消費可能な最大リソースが指定されます。制限は予約されず、常に利用できるとは限りません。コンテナーは、リソースが利用できる場合のみ、制限以下のリソースを使用できます。リソース制限は、常にリソース要求よりも高くする必要があります。

1 つまたは複数のサポートされる制限に対してリソースを設定できます。

リソース制限の設定例

# ...
resources:
  limits:
    cpu: 12
    memory: 64Gi
# ...

サポートされる CPU 形式

CPU の要求および制限は以下の形式でサポートされます。

  • 整数値 (5) または少数 (2.5) の CPU コアの数。
  • 数値または ミリ CPU / ミリコア (100m)。1000 ミリコア は CPU コア 1 つと同じです。

CPU ユニットの例

# ...
resources:
  requests:
    cpu: 500m
  limits:
    cpu: 2.5
# ...

注記

1 つの CPU コアのコンピューティング能力は、OpenShift がデプロイされたプラットフォームによって異なることがあります。

CPU 仕様の詳細は、「Meaning of CPU」を参照してください。

サポートされるメモリー形式

メモリー要求および制限は、メガバイト、ギガバイト、メビバイト、およびギビバイトで指定されます。

  • メモリーをメガバイトで指定するには、M 接尾辞を使用します。たとえば、1000M のように指定します。
  • メモリーをギガバイトで指定するには、G 接尾辞を使用します。たとえば、1G のように指定します。
  • メモリーをメビバイトで指定するには、Mi 接尾辞を使用します。たとえば、1000Mi のように指定します。
  • メモリーをギビバイトで指定するには、Gi 接尾辞を使用します。たとえば、1Gi のように指定します。

異なるメモリー単位を使用するリソースの例

# ...
resources:
  requests:
    memory: 512Mi
  limits:
    memory: 2Gi
# ...

メモリーの指定およびサポートされるその他の単位に関する詳細は、「Meaning of memory」を参照してください。

13.1.6. image

image プロパティーを使用して、コンポーネントによって使用されるコンテナーイメージを設定します。

コンテナーイメージのオーバーライドは、別のコンテナーレジストリーやカスタマイズされたイメージを使用する必要がある特別な状況でのみ推奨されます。

たとえば、ネットワークで 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
  • KafkaConnectS2I.spec
  • KafkaMirrorMaker.spec
  • KafkaMirrorMaker2.spec
  • KafkaBridge.spec

Kafka、Kafka Connect、および Kafka MirrorMaker の image プロパティーの設定

Kafka、Kafka Connect (S2I サポートのある Kafka Connect を含む)、および Kafka MirrorMaker では、複数のバージョンの Kafka がサポートされます。各コンポーネントには独自のイメージが必要です。異なる Kafka バージョンのデフォルトイメージは、以下の環境変数で設定されます。

  • STRIMZI_KAFKA_IMAGES
  • STRIMZI_KAFKA_CONNECT_IMAGES
  • STRIMZI_KAFKA_CONNECT_S2I_IMAGES
  • STRIMZI_KAFKA_MIRROR_MAKER_IMAGES

これらの環境変数には、Kafka バージョンと対応するイメージ間のマッピングが含まれます。マッピングは、image および version プロパティーとともに使用されます。

  • imageversion のどちらもカスタムリソースに指定されていない場合、version は Cluster Operator のデフォルトの Kafka バージョンに設定され、環境変数のこのバージョンに対応するイメージが指定されます。
  • image が指定されていても version が指定されていない場合、指定されたイメージが使用され、Cluster Operator のデフォルトの Kafka バージョンが version であると想定されます。
  • version が指定されていても image が指定されていない場合、環境変数の指定されたバージョンに対応するイメージが使用されます。
  • versionimage の両方を指定すると、指定されたイメージが使用されます。このイメージには、指定のバージョンの Kafka イメージが含まれると想定されます。

異なるコンポーネントの image および version は、以下のプロパティーで設定できます。

  • Kafka の場合は spec.kafka.image および spec.kafka.version
  • Kafka Connect、Kafka Connect S2I、および Kafka MirrorMaker の場合は spec.image および spec.version
警告

version のみを提供し、image プロパティーを未指定のままにしておくことが推奨されます。これにより、カスタムリソースの設定時に間違いが発生する可能性が低減されます。異なるバージョンの Kafka に使用されるイメージを変更する必要がある場合は、Cluster Operator の環境変数を設定することが推奨されます。

他のリソースでの image プロパティーの設定

他のカスタムリソースの image プロパティーでは、デプロイメント中に指定の値が使用されます。image プロパティーがない場合、Cluster Operator 設定に指定された image が使用されます。image 名が Cluster Operator 設定に定義されていない場合、デフォルト値が使用されます。

  • Topic Operator の場合:

    1. Cluster Operator 設定から STRIMZI_DEFAULT_TOPIC_OPERATOR_IMAGE 環境変数に指定されたコンテナーイメージ。
    2. registry.redhat.io/amq7/amq-streams-rhel7-operator:1.8.0 コンテナーイメージ。
  • User Operator の場合:

    1. Cluster Operator 設定から STRIMZI_DEFAULT_USER_OPERATOR_IMAGE 環境変数に指定されたコンテナーイメージ。
    2. registry.redhat.io/amq7/amq-streams-rhel7-operator:1.8.0 コンテナーイメージ。
  • Entity Operator TLS サイドカーの場合:

    1. Cluster Operator 設定から STRIMZI_DEFAULT_TLS_SIDECAR_ENTITY_OPERATOR_IMAGE 環境変数に指定されたコンテナーイメージ。
    2. registry.redhat.io/amq7/amq-streams-kafka-28-rhel7:1.8.0 コンテナーイメージ。
  • Kafka Exporter の場合:

    1. Cluster Operator 設定から STRIMZI_DEFAULT_KAFKA_EXPORTER_IMAGE 環境変数に指定されたコンテナーイメージ。
    2. registry.redhat.io/amq7/amq-streams-kafka-28-rhel7:1.8.0 コンテナーイメージ。
  • Kafka Bridge の場合:

    1. Cluster Operator 設定から STRIMZI_DEFAULT_KAFKA_BRIDGE_IMAGE 環境変数に指定されたコンテナーイメージ。
    2. registry.redhat.io/amq7/amq-streams-bridge-rhel7:1.8.0 コンテナーイメージ。
  • Kafka ブローカーイニシャライザーの場合:

    1. Cluster Operator 設定から STRIMZI_DEFAULT_KAFKA_INIT_IMAGE 環境変数に指定されたコンテナーイメージ。
    2. registry.redhat.io/amq7/amq-streams-rhel7-operator:1.8.0 コンテナーイメージ。

コンテナーイメージ設定の例

apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    image: my-org/my-image:latest
    # ...
  zookeeper:
    # ...

13.1.7. livenessProbe および readinessProbe healthcheck

livenessProbe および readinessProbe プロパティーを使用して、AMQ Streams でサポートされる healthcheck プローブを設定します。

Healthcheck は、アプリケーションの健全性を検証する定期的なテストです。ヘルスチェックプローブが失敗すると、OpenShift によってアプリケーションが正常でないと見なされ、その修正が試行されます。

プローブの詳細は、「Configure Liveness and Readiness Probes」を参照してください。

livenessProbe および readinessProbe の両方で以下のオプションがサポートされます。

  • initialDelaySeconds
  • timeoutSeconds
  • periodSeconds
  • successThreshold
  • failureThreshold

Liveness および Readiness プローブの設定例

# ...
readinessProbe:
  initialDelaySeconds: 15
  timeoutSeconds: 5
livenessProbe:
  initialDelaySeconds: 15
  timeoutSeconds: 5
# ...

livenessProbe および readinessProbe のオプションに関する詳細は、「Probe スキーマ参照」を参照してください。

13.1.8. metricsConfig

metricsConfig プロパティーを使用して、Prometheus メトリクスを有効化および設定します。

metricsConfig プロパティーには、Prometheus JMX exporter の追加設定が含まれる ConfigMap への参照が含まれます。AMQ Streams では、Apache Kafka および ZooKeeper によってサポートされる JMX メトリクスを Prometheus メトリクスに変換するために、Prometheus JMX エクスポーターを使用した Prometheus メトリクスがサポートされます。

追加設定なしで Prometheus メトリクスのエクスポートを有効にするには、metricsConfig.valueFrom.configMapKeyRef.key 配下に空のファイルが含まれる ConfigMap を参照します。空のファイルを参照する場合、名前が変更されていない限り、すべてのメトリクスが公開されます。

Kafka のメトリクス設定が含まれる ConfigMap の例

kind: ConfigMap
apiVersion: v1
metadata:
  name: my-configmap
data:
  my-key: |
    lowercaseOutputName: true
    rules:
    # Special cases and very specific rules
    - pattern: kafka.server<type=(.+), name=(.+), clientId=(.+), topic=(.+), partition=(.*)><>Value
      name: kafka_server_$1_$2
      type: GAUGE
      labels:
       clientId: "$3"
       topic: "$4"
       partition: "$5"
    # further configuration

Kafka のメトリクス設定例

apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    metricsConfig:
      type: jmxPrometheusExporter
      valueFrom:
        configMapKeyRef:
          name: my-config-map
          key: my-key
    # ...
  zookeeper:
    # ...

有効になったメトリクスは、9404 番ポートで公開されます。

metricsConfig (または非推奨の metrics)プロパティーがリソースに定義されていない場合、Prometheus メトリクスは無効になります。

Prometheus および Grafana の設定およびデプロイに関する詳細は、『Deploying and Upgrading AMQ Streams on OpenShift』の「Introducing Metrics to Kafka」を参照してください。

13.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
  • KafkaConnect.spec
  • KafkaConnectS2I.spec
  • KafkaMirrorMaker.spec
  • KafkaMirrorMaker2.spec
  • KafkaBridge.spec

設定では、以下のオプションを指定できます。

-Xms
JVM の起動時に最初に割り当てられる最小ヒープサイズ。
-Xmx
最大ヒープサイズ。
-XX
JVM の高度なランタイムオプション。
javaSystemProperties
追加のシステムプロパティー。
gcLoggingEnabled
ガベッジコレクターのロギングを有効にします

jvmOptions の完全なスキーマは、JvmOptions schema referenceに記載されています。

注記

-Xmx-Xms などの JVM 設定で使用できる単位は、対応するイメージの 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 の最小メモリーは 128M に設定されます。JVM の最大メモリーは、必要に応じてメモリーを拡張するようには定義されていません。これは、テストおよび開発での単一ノード環境に適しています。

-Xmx を明示的に設定する前に、以下を考慮してください。

  • JVM のメモリー使用量の合計は、-Xmx によって設定された最大ヒープの約 4 倍になります。
  • 適切な OpenShift メモリー制限を設定せずに -Xmx が設定された場合、OpenShift ノードで、実行されている他の Pod からメモリー不足が発生するとコンテナーが強制終了される可能性があります。
  • 適切な OpenShift メモリー要求を設定せずに -Xmx が設定された場合、コンテナーはメモリー不足のノードにスケジュールされる可能性があります。この場合、-Xms-Xmx に設定されている場合、コンテナーは起動せずに即座にクラッシュし、そうでない場合は後でクラッシュします。

以下を行うことが推奨されます。

  • メモリー要求とメモリー制限を同じ値に設定します。
  • -Xmxの 4.5 倍以上のメモリー要求を使用します。
  • -Xms-Xmxと同じ値に設定することを検討してください。

この例では、JVM のヒープに 2 GiB (2,147,483,648 バイト) が使用されます。メモリー使用量の合計は約 8GiB です。

-Xmx および -Xms の設定例

# ...
jvmOptions:
  "-Xmx": "2g"
  "-Xms": "2g"
# ...

最初のヒープサイズ (-Xms) および最大ヒープサイズ (-Xmx) に同じ値を設定すると、JVM が必要以上のヒープを割り当てて起動後にメモリーを割り当てないようにすることができます。

重要

Kafka ブローカーコンテナーなど、多数のディスク I/O を実行するコンテナーには、オペレーティングシステムのページキャッシュとして使用できるメモリーが必要です。このようなコンテナーでは、要求されるメモリーは JVM によって使用されるメモリーよりもはるかに多くなります。

-XX オプション

-XX オプションは、Apache Kafka の KAFKA_JVM_PERFORMANCE_OPTS オプションの設定に使用されます。

-XX 設定

jvmOptions:
  "-XX":
    "UseG1GC": true
    "MaxGCPauseMillis": 20
    "InitiatingHeapOccupancyPercent": 35
    "ExplicitGCInvokesConcurrent": true

-XX 設定から生成される JVM オプション

-XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:+ExplicitGCInvokesConcurrent -XX:-UseParNewGC

注記

-XX オプションを指定しないと、Apache Kafka の KAFKA_JVM_PERFORMANCE_OPTS のデフォルト設定が使用されます。

javaSystemProperties

javaSystemProperties は、デバッグユーティリティーなどの追加の Java システムプロパティーの設定に使用されます。

javaSystemProperties の設定例

jvmOptions:
  javaSystemProperties:
    - name: javax.net.debug
      value: ssl

13.1.10. ガベッジコレクターのロギング

jvmOptions プロパティーでは、ガベージコレクター(GC)のロギングを有効または無効にすることもできます。GC ロギングはデフォルトで無効になっています。これを有効にするには、以下のように gcLoggingEnabled プロパティーを設定します。

GC ロギングの設定例

# ...
jvmOptions:
  gcLoggingEnabled: true
# ...