第1章 デプロイメントの概要
Streams for Apache Kafka は、OpenShift クラスターで Apache Kafka を実行するプロセスを簡素化します。
このガイドでは、Streams for Apache Kafka のデプロイと管理の手順について説明します。デプロイメントオプションと手順については、Streams for Apache Kafka に付属するサンプルインストールファイルを使用して説明します。このガイドでは設定に関する重要な考慮事項を強調していますが、利用可能なすべてのオプションを網羅しているわけではありません。Kafka コンポーネントの設定オプションの詳細は、Streams for Apache Kafka カスタムリソース API リファレンス を参照してください。
このガイドでは、デプロイメント手順に加えて、デプロイメント前およびデプロイメント後のガイダンスも提供されます。Kafka クラスターへのクライアントアクセスのセットアップとセキュリティー保護について説明します。さらに、メトリクス統合、分散トレーシング、クラスター管理ツール (Cruise Control や Streams for Apache Kafka Drain Cleaner など) といった追加のデプロイメントオプションについても説明します。また、Streams for Apache Kafka の管理と、最適なパフォーマンスを実現するための Kafka 設定の微調整に関する推奨事項も紹介します。
デプロイメントを最新の状態に保てるように、Streams for Apache Kafka と Kafka の両方のアップグレード手順を記載しています。
Streams for Apache Kafka は、ディストリビューションに関係なく、すべてのタイプの OpenShift クラスターと互換性があるように設計されています。デプロイメントにパブリッククラウドまたはプライベートクラウドが含まれるかどうか、ローカル開発環境をセットアップしている場合、このガイドの手順はすべての場合に当てはまります。
1.1. Streams for Apache Kafka カスタムリソース
Streams for Apache Kafka を使用した OpenShift クラスターへの Kafka コンポーネントのデプロイは、カスタムリソースを使用することで詳細に設定できます。これらのリソースは、OpenShift リソースを拡張するカスタムリソース定義 (CRD) によって導入される API のインスタンスとして作成されます。
CRD は、OpenShift クラスターでカスタムリソースを記述するための設定手順として機能し、デプロイメントで使用する Kafka コンポーネントごとに Streams for Apache Kafka で、ユーザーおよびトピックと共に提供されます。CRD およびカスタムリソースは YAML ファイルとして定義されます。YAML ファイルのサンプルは、Streams for Apache Kafka ディストリビューションで提供されます。
CRD を使用すると、Streams for Apache Kafka リソースは、CLI アクセシビリティーや設定検証などのネイティブ OpenShift 機能の恩恵を受けることができます。
1.1.1. Streams for Apache Kafka カスタマムリソースの例
Streams for Apache Kafka 固有リソースのインスタンス化および管理に使用されるスキーマを定義するため、CRD をクラスターに一度インストールする必要があります。
CRD をインストールして新規カスタムリソースタイプをクラスターに追加した後に、その仕様に基づいてリソースのインスタンスを作成できます。
クラスターの設定によりますが、インストールには通常、クラスター管理者権限が必要です。
カスタムリソースの管理は、Streams for Apache Kafka 管理者に限定されます。詳細は、「Streams for Apache Kafka 管理者の指定」 を参照してください。
kind:Kafka
などの新しい kind
リソースは、OpenShift クラスター内で CRD によって定義されます。
Kubernetes API サーバーを使用すると、kind
を基にしたカスタムリソースの作成が可能になり、カスタムリソースが OpenShift クラスターに追加されたときにカスタムリソースの検証および格納方法を CRD から判断します。
Streams for Apache Kafka 固有のカスタムリソースはそれぞれ、リソースの kind
の CRD によって定義されるスキーマに準拠します。Streams for Apache Kafka コンポーネントのカスタムリソースには、spec
で定義される共通の設定プロパティーがあります。
CRD とカスタムリソースの関係を理解するため、Kafka トピックの CRD の例を見てみましょう。
Kafka トピックの CRD
apiVersion: kafka.strimzi.io/v1beta2 kind: CustomResourceDefinition metadata: 1 name: kafkatopics.kafka.strimzi.io labels: app: strimzi spec: 2 group: kafka.strimzi.io versions: v1beta2 scope: Namespaced names: # ... singular: kafkatopic plural: kafkatopics shortNames: - kt 3 additionalPrinterColumns: 4 # ... subresources: status: {} 5 validation: 6 openAPIV3Schema: properties: spec: type: object properties: partitions: type: integer minimum: 1 replicas: type: integer minimum: 1 maximum: 32767 # ...
- 1
- CRD を識別するためのトピック CRD、その名前および名前のメタデータ。
- 2
- グループ (ドメイン) 名、複数名、サポート対象のスキーマバージョンなど、この CRD の仕様。トピックの API にアクセスするために URL で使用されます。他の名前は、CLI のインスタンスリソースを識別するために使用されます。たとえば、
oc get kafkatopic my-topic
やoc get kafkatopics
です。 - 3
- CLI コマンドでは短縮名を使用できます。たとえば、
oc get kafkatopic
の代わりにoc get kt
を略名として使用できます。 - 4
- カスタムリソースで
get
コマンドを使用する場合に示される情報。 - 5
- リソースの スキーマリファレンス に記載されている CRD の現在のステータス。
- 6
- openAPIV3Schema 検証によって、トピックカスタムリソースの作成が検証されます。たとえば、トピックには 1 つ以上のパーティションと 1 つのレプリカが必要です。
Streams for Apache Kafka インストールファイルと提供される CRD YAML ファイルを識別できます。ファイル名には、インデックス番号とそれに続く Crd が含まれるからです。
KafkaTopic
カスタムリソースに該当する例は次のとおりです。
Kafka トピックカスタムリソース
apiVersion: kafka.strimzi.io/v1beta2 kind: KafkaTopic 1 metadata: name: my-topic labels: strimzi.io/cluster: my-cluster 2 spec: 3 partitions: 1 replicas: 1 config: retention.ms: 7200000 segment.bytes: 1073741824 status: conditions: 4 lastTransitionTime: "2019-08-20T11:37:00.706Z" status: "True" type: Ready observedGeneration: 1 / ...
- 1
kind
およびapiVersion
によって、インスタンスであるカスタムリソースの CRD が特定されます。- 2
- トピックまたはユーザーが属する Kafka クラスターの名前 (
Kafka
リソースの名前と同じ) を定義する、KafkaTopic
およびKafkaUser
リソースのみに適用可能なラベル。 - 3
- 指定内容には、トピックのパーティション数およびレプリカ数や、トピック自体の設定パラメーターが示されています。この例では、メッセージがトピックに保持される期間や、ログのセグメントファイルサイズが指定されています。
- 4
KafkaTopic
リソースのステータス条件。lastTransitionTime
でtype
条件がReady
に変更されています。
プラットフォーム CLI からカスタムリソースをクラスターに適用できます。カスタムリソースが作成されると、Kubernetes API の組み込みリソースと同じ検証が使用されます。
KafkaTopic
カスタムリソースの作成後、Topic Operator は通知を受け取り、対応する Kafka トピックが Streams for Apache Kafka に作成されます。
1.1.2. カスタムリソースでの oc
操作の実施
oc
コマンドを使用して、Streams for Apache Kafka カスタムリソースの情報を取得するなどの操作を実行できます。リソースタイプに対して操作を行うには、get
、describe
、edit
、delete
などの oc
コマンドを使用します。たとえば、oc get kafkatopics
はすべての Kafka トピックのリストを取得し、oc get kafkas
はデプロイされたすべての Kafka クラスターを取得します。
リソースタイプを参照する際には、単数形と複数形の両方の名前を使うことができます。oc get kafkas
は oc get kafka
と同じ結果になります。
リソースの 短縮名 を使用することもできます。短縮名を覚えておくと、Streams for Apache Kafka を管理するときに時間を節約できます。Kafka
の短縮名は k
であるため、oc get k
を実行してすべての Kafka クラスターをリスト表示することもできます。
Kafka クラスターのリスト表示
oc get k NAME DESIRED KAFKA REPLICAS DESIRED ZK REPLICAS my-cluster 3 3
Streams for Apache Kafka リソース | 正式名 | 短縮名 |
---|---|---|
Kafka | kafka | k |
Kafka Node Pool | kafkanodepool | knp |
Kafka Topic | kafkatopic | kt |
Kafka User | kafkauser | ku |
Kafka Connect | kafkaconnect | kc |
Kafka Connector | kafkaconnector | kctr |
Kafka Mirror Maker | kafkamirrormaker | kmm |
Kafka Mirror Maker 2 | kafkamirrormaker2 | kmm2 |
Kafka Bridge | kafkabridge | kb |
Kafka Rebalance | kafkarebalance | kr |
1.1.2.1. リソースカテゴリー
oc
コマンドでは、カスタムリソースのカテゴリーも使用できます。
Streams for Apache Kafka カスタムリソースは、すべて strimzi
カテゴリーに属しています。そのため、strimzi
を使用すると、1 つのコマンドですべての Streams for Apache Kafka リソースを取得できます。
たとえば、oc get strimzi
を実行すると、指定した namespace 内の Streams for Apache Kafka がリスト表示されます。
すべてのカスタムリソースのリスト表示
oc get strimzi NAME DESIRED KAFKA REPLICAS DESIRED ZK REPLICAS kafka.kafka.strimzi.io/my-cluster 3 3 NAME PARTITIONS REPLICATION FACTOR kafkatopic.kafka.strimzi.io/kafka-apps 3 3 NAME AUTHENTICATION AUTHORIZATION kafkauser.kafka.strimzi.io/my-user tls simple
oc get strimzi -o name
コマンドは、すべてのリソースタイプとリソース名を返します。-o name
オプションは type/name 形式で出力を取得します。
すべてのリソースタイプとリソース名のリスト表示
oc get strimzi -o name kafka.kafka.strimzi.io/my-cluster kafkatopic.kafka.strimzi.io/kafka-apps kafkauser.kafka.strimzi.io/my-user
この strimzi
コマンドを他のコマンドと組み合わせることができます。たとえば、これを oc delete
コマンドに渡して、単一のコマンドですべてのリソースを削除できます。
すべてのカスタムリソースの削除
oc delete $(oc get strimzi -o name) kafka.kafka.strimzi.io "my-cluster" deleted kafkatopic.kafka.strimzi.io "kafka-apps" deleted kafkauser.kafka.strimzi.io "my-user" deleted
1 つの操作ですべてのリソースを削除することは、Streams for Apache Kafka の新機能をテストする場合などに役立ちます。
1.1.2.2. サブリソースのステータスのクエリー
-o
オプションに渡すことのできる他の値もあります。たとえば、-o yaml
を使用すると、YAML 形式で出力されます。-o json
を使用すると JSON として返されます。
oc get --help
のすべてのオプションが表示されます。
最も便利なオプションの 1 つは JSONPath サポート で、JSONPath 式を渡して Kubernetes API にクエリーを実行できます。JSONPath 式は、リソースの特定部分を抽出または操作できます。
たとえば、JSONPath 式 {.status.listeners[?(@.name=="tls")].bootstrapServers}
を使用して、Kafka カスタムリソースのステータスからブートストラップアドレスを取得し、Kafka クライアントで使用できます。
この場合、コマンドは tls
という名前のリスナーの bootstrapServers
値を取得します。
ブートストラップアドレスの取得
oc get kafka my-cluster -o=jsonpath='{.status.listeners[?(@.name=="tls")].bootstrapServers}{"\n"}' my-cluster-kafka-bootstrap.myproject.svc:9093
名前の条件を変更することで、他の Kafka リスナーのアドレスも取得できます。
jsonpath
を使用して、カスタムリソースから他のプロパティーまたはプロパティーのグループを抽出できます。
1.1.3. Streams for Apache Kafka カスタムリソースのステータス情報
ステータスプロパティーは、特定のカスタムリソースのステータス情報を提供します。
次の表に、ステータス情報 (デプロイ時) を提供するカスタムリソースと、ステータスプロパティーを定義するスキーマを示します。
スキーマの詳細は、Streams for Apache Kafka カスタムリソース API リファレンス を参照してください。
Streams for Apache Kafka リソース | スキーマリファレンス | ステータス情報が公開される場所 |
---|---|---|
|
| Kafka クラスター、そのリスナー、およびノードプール |
|
| ノードプール内のノード、そのロール、および関連する Kafka クラスター |
|
| Kafka クラスター内の Kafka トピック |
|
| Kafka クラスター内の Kafka ユーザー |
|
| Kafka Connect クラスターとコネクタープラグイン |
|
|
|
|
| Kafka MirrorMaker 2 クラスターと内部コネクター |
|
| Kafka MirrorMaker クラスター |
|
| Streams for Apache Kafka Bridge |
|
| リバランスの状況と結果 |
|
| 管理され、現在のバージョンを使用し、準備完了状態にある Pod の数 |
リソースの status
プロパティーは、リソースの状態に関する情報を提供します。status.conditions
および status.observedGeneration
プロパティーは、すべてのリソースに共通です。
status.conditions
-
ステータス条件は、リソースの 現在の状態 を表します。ステータス条件プロパティーは、
仕様
で指定された設定で定義されているように、リソースが 目的の状態 に到達することに関連する進行状況を追跡するのに役立ちます。状況条件プロパティーは、リソースの状態が変更された時間と理由、および Operator が目的の状態を実現するのを妨げたり遅らせたりするイベントの詳細を提供します。 status.observedGeneration
-
最後に観察された世代は、Cluster Operator によるリソースの最新の調整を示します。
observedGeneration
の値がmetadata.generation
(デプロイメントの現在のバージョン)(の値と異なる場合、リソースの最新の更新が Operator によって処理されていません。これらの値が同じである場合、リソースの最新の変更がステータス情報に反映されます。
status
プロパティーは、リソース固有の情報も提供します。たとえば、KafkaStatus
はリスナーアドレスに関する情報と Kafka クラスターの ID を提供します。
KafkaStatus
は、使用されている Kafka および Streams for Apache Kafka のバージョンに関する情報も提供します。operatorLastSuccessfulVersion
と kafkaVersion
の値を確認すると、AMQ Streams for Apache Kafka または Kafka のアップグレードが完了したかどうかを判断できます。
Streams for Apache Kafka は、カスタムリソースのステータスを作成および維持し、カスタムリソースの現在の状態を定期的に評価し、それに応じてステータスを更新します。たとえば、oc edit
を使用してカスタムリソースで更新を行う場合、その status
は編集不可能です。さらに、status
の変更は Kafka クラスターステータスの設定に影響しません。
ここでは、Kafka
カスタムリソースの status
プロパティーを確認します。
Kafka カスタムリソースのステータス
apiVersion: kafka.strimzi.io/v1beta2 kind: Kafka metadata: spec: # ... status: clusterId: XP9FP2P-RByvEy0W4cOEUA 1 conditions: 2 - lastTransitionTime: '2023-01-20T17:56:29.396588Z' status: 'True' type: Ready 3 kafkaMetadataState: KRaft 4 kafkaVersion: 3.7.0 5 kafkaNodePools: 6 - name: broker - name: controller listeners: 7 - addresses: - host: my-cluster-kafka-bootstrap.prm-project.svc port: 9092 bootstrapServers: 'my-cluster-kafka-bootstrap.prm-project.svc:9092' name: plain - addresses: - host: my-cluster-kafka-bootstrap.prm-project.svc port: 9093 bootstrapServers: 'my-cluster-kafka-bootstrap.prm-project.svc:9093' certificates: - | -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- name: tls - addresses: - host: >- 2054284155.us-east-2.elb.amazonaws.com port: 9095 bootstrapServers: >- 2054284155.us-east-2.elb.amazonaws.com:9095 certificates: - | -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- name: external3 - addresses: - host: ip-10-0-172-202.us-east-2.compute.internal port: 31644 bootstrapServers: 'ip-10-0-172-202.us-east-2.compute.internal:31644' certificates: - | -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- name: external4 observedGeneration: 3 8 operatorLastSuccessfulVersion: 2.7 9
- 1
- Kafka クラスター ID。
- 2
- ステータス
conditions
は、Kafka クラスターの現在の状態を表します。 - 3
Ready
状態は、Cluster Operator が Kafka クラスターがトラフィックを処理できると見なしていることを示します。- 4
- Kafka メタデータの管理と操作の調整に使用されるメカニズム (KRaft または ZooKeeper) を示す Kafka メタデータの状態。
- 5
- Kafka クラスターによって使用されている Kafka のバージョン。
- 6
- Kafka クラスターに属するノードプール。
- 7
listeners
は、Kafka ブートストラップアドレスをタイプ別に記述します。- 8
observedGeneration
値は、Cluster Operator によるKafka
カスタムリソースの最後の調整を示します。- 9
- 最後の調整を正常に完了した Operator のバージョン。
Kafka ブートストラップアドレスがステータスに一覧表示されても、それらのエンドポイントまたは Kafka クラスターが Ready
状態であるとは限りません。
1.1.4. カスタムリソースのステータスの検出
カスタムリソースの status
サブリソースで oc
を使用して、リソースに関する情報を取得します。
前提条件
- OpenShift クラスター
- Cluster Operator が稼働中である。
手順
カスタムリソースを指定し、
-o jsonpath
オプションを使用して標準の JSONPath 式を適用してstatus
プロパティーを選択します。oc get kafka <kafka_resource_name> -o jsonpath='{.status}' | jq
この式は、指定されたカスタムリソースのすべてのステータス情報を返します。
status.listeners
またはstatus.observedGeneration
などのドット表記を使用すると、表示するステータス情報を微調整できます。jq
コマンドライン JSON パーサーツール を使用すると、出力が読みやすくなります。
関連情報
- JSONPath の使用に関する詳細は、JSONPath support を参照してください。