Confluent Cloud 向け ccloud-stack ユーティリティ¶
概要¶
この ccloud-stack ユーティリティにより、フルマネージド型サービスのスタックが Confluent Cloud に作成されます。この方法で、正しい資格情報とアクセス許可で Confluent Cloud にリソースがすばやく作成され、他のサンプルの学習、拡張、作成の際に使用できます。このユーティリティは、Confluent CLI を内部で使用して、以下のことを Confluent Cloud で動的に行います。
- 新しい環境を作成する
- 新しいサービスアカウントを作成する。
- 新しい Kafka クラスターとそれに関連する資格情報を作成する。
- スキーマレジストリとそれに関連する資格情報を有効にする。
- （省略可）新しい ksqlDB アプリケーションとそれに関連する資格情報を作成する。
- サービスアカウント用 ACL をワイルドカードを使用して作成する。
ccloud-stack は、これらのリソースを作成するだけでなく、上記のサービスのすべてに対する接続情報を含むローカル構成ファイルも生成します。Confluent Cloud インスタンスに対する接続情報を含むこのファイルは非常に便利で、あらゆる下流アプリケーションまたは Kafka クライアントで使用できます。また、他のデモや自動化ワークフローにも使用できます。
ccloud-stack の実行コスト¶
注意¶
Confluent Cloud のすべてのサンプルでは、課金される可能性のある実際の Confluent Cloud リソースを使用しています。サンプルで、新しい Confluent Cloud 環境、Kafka クラスター、トピック、ACL、サービスアカウントに加えて、コネクターや ksqlDB アプリケーションのように時間で課金されるリソースを作成する場合があります。想定外の課金を避けるために、慎重に リソースのコストを確認 してから開始してください。Confluent Cloud のサンプルの実行を終了したら、サービスへの時間単位の課金を回避するためにすべての Confluent Cloud リソースを破棄し、リソースが削除されたことを確認します。
このユーティリティでは、実際の Confluent Cloud リソースを使用します。目的は、正しい資格情報とアクセス許可で Confluent Cloud にリソースをすばやく作成することであり、他のサンプルの学習、拡張、作成の際に使用できます。
- 明示的に Confluent Cloud ksqlDB を有効にすることなく、単に
ccloud-stackを実行した場合は、トピックを作成するか、Kafka クラスターに対してデータを生成するか、他のフルマネージド型サービスをプロビジョニングするまでは課金されません。 - Confluent Cloud ksqlDB（1 CSU）を有効にして
ccloud-stackを実行した場合は、直ちに課金が開始されます。
以下に、ユーティリティが発行し、Confluent Cloud にリソースを作成する Confluent CLI コマンドのリストを示します（関数 ccloud::create_ccloud_stack() のソースコードは ccloud_library にあります）。デフォルトでは、Confluent Cloud ksqlDB アプリケーションは ccloud-stack で作成されないため、明示的に有効にする必要があります。
confluent iam service-account create $SERVICE_NAME --description $SERVICE_NAME -o json
confluent environment create $ENVIRONMENT_NAME -o json
confluent kafka cluster create "$CLUSTER_NAME" --cloud $CLUSTER_CLOUD --region $CLUSTER_REGION
confluent api-key create --service-account $SERVICE_ACCOUNT_ID --resource $RESOURCE -o json // for kafka
confluent schema-registry cluster enable --cloud $SCHEMA_REGISTRY_CLOUD --geo $SCHEMA_REGISTRY_GEO -o json
confluent api-key create --service-account $SERVICE_ACCOUNT_ID --resource $RESOURCE -o json // for schema-registry
# By default, ccloud-stack does not enable Confluent Cloud ksqlDB, but if you explicitly enable it:
confluent ksql cluster create --cluster $CLUSTER --api-key "$KAFKA_API_KEY" --api-secret "$KAFKA_API_SECRET" --csu 1 -o json "$KSQLDB_NAME"
confluent api-key create --service-account $SERVICE_ACCOUNT_ID --resource $RESOURCE -o json // for ksqlDB REST API
confluent kafka acl create --allow --service-account $SERVICE_ACCOUNT_ID --operation <....> // permissive ACLs for all services
前提条件¶
- Confluent Cloud でのユーザーアカウントの作成
- ローカルにインストールされた Confluent CLI v2.2.0 以降
jqツール
ccloud-stack は、macOS 10.15.3 および bash バージョン 3.2.57 で検証済みです。それ以外のオペレーティングシステムまたはバージョンで問題が発生した場合は、confluentinc/examples で GitHub への問題を報告してください。
使用方法¶
セットアップ¶
confluentinc/examples GitHub リポジトリのクローンを作成し、
7.0.3-postブランチをチェックアウトします。git clone https://github.com/confluentinc/examples cd examples git checkout 7.0.3-post
ccloud-stack ユーティリティのディレクトリに変更します。
cd ccloud/ccloud-stack/コマンド
confluent loginで、Confluent Cloud のユーザー名とパスワードを使用して Confluent Cloud にログインします。--save引数により、Confluent Cloud ユーザーログイン資格情報が保存されるか、ローカルのnetrcファイルに対してトークン（SSO の場合）が更新されます。confluent login --save
ccloud-stack の作成¶
デフォルトでは、
cloud-stackユーティリティにより、クラウドプロバイダーawsのリージョンus-west-2にリソースが作成されます。これがターゲットのプロバイダーおよびリージョンである場合は、bash スクリプト ccloud_stack_create.sh を呼び出してスタックを作成します。ccloud-stackの構成時のその他のオプションについては、「高度なオプション」を参照してください。./ccloud_stack_create.sh
2 つのプロンプトが表示されます。Confluent Cloud ksqlDB を有効にする場合（任意）は、2 番目のプロンプトに応答します。
Do you still want to run this script? [y/n] y Do you also want to create a Confluent Cloud ksqlDB app (hourly charges may apply)? [y/n] n
ccloud-stackにより、ワイルドカードを使用できる緩やかな ACL が構成されます。これは、開発や学習の環境で便利です。本稼働環境では、より厳格な ACL を構成してください。ksqlDB を使用せずに実行した場合:
ServiceAccountId | Permission | Operation | Resource | Name | Type +------------------+------------+------------------+------------------+---------------+---------+ User:186607 | ALLOW | DESCRIBE | TRANSACTIONAL_ID | * | LITERAL User:186607 | ALLOW | WRITE | TRANSACTIONAL_ID | * | LITERAL User:186607 | ALLOW | IDEMPOTENT_WRITE | CLUSTER | kafka-cluster | LITERAL User:186607 | ALLOW | READ | GROUP | * | LITERAL User:186607 | ALLOW | WRITE | GROUP | * | LITERAL User:186607 | ALLOW | CREATE | GROUP | * | LITERAL User:186607 | ALLOW | DESCRIBE | TOPIC | * | LITERAL User:186607 | ALLOW | DELETE | TOPIC | * | LITERAL User:186607 | ALLOW | CREATE | TOPIC | * | LITERAL User:186607 | ALLOW | DESCRIBE_CONFIGS | TOPIC | * | LITERAL User:186607 | ALLOW | WRITE | TOPIC | * | LITERAL User:186607 | ALLOW | READ | TOPIC | * | LITERAL
ksqlDB を使用して実行した場合:
ServiceAccountId | Permission | Operation | Resource | Name | Type +------------------+------------+------------------+------------------+------------------------------+----------+ User:186588 | ALLOW | DESCRIBE_CONFIGS | GROUP | * | LITERAL User:186588 | ALLOW | DESCRIBE | GROUP | * | LITERAL User:186588 | ALLOW | DELETE | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | READ | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | ALTER | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DESCRIBE | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | ALTER_CONFIGS | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DESCRIBE_CONFIGS | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | CREATE | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | WRITE | TOPIC | pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DESCRIBE | TOPIC | * | LITERAL User:186588 | ALLOW | DESCRIBE_CONFIGS | TOPIC | * | LITERAL User:186588 | ALLOW | DESCRIBE | TRANSACTIONAL_ID | pksqlc-o3g5o | LITERAL User:186588 | ALLOW | WRITE | TRANSACTIONAL_ID | pksqlc-o3g5o | LITERAL User:186588 | ALLOW | ALTER | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | WRITE | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | READ | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DELETE | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DESCRIBE | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | ALTER_CONFIGS | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | CREATE | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DESCRIBE_CONFIGS | TOPIC | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | IDEMPOTENT_WRITE | CLUSTER | kafka-cluster | LITERAL User:186588 | ALLOW | DESCRIBE | CLUSTER | kafka-cluster | LITERAL User:186588 | ALLOW | DESCRIBE_CONFIGS | CLUSTER | kafka-cluster | LITERAL User:186588 | ALLOW | WRITE | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DESCRIBE | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DELETE | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | READ | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | CREATE | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | ALTER | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | ALTER_CONFIGS | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED User:186588 | ALLOW | DESCRIBE_CONFIGS | GROUP | _confluent-ksql-pksqlc-o3g5o | PREFIXED
ccloud-stackを実行すると、関連付けられたサービスアカウントと ACL を使用して Confluent Cloud ですべてのリソースが作成され、すべての Confluent Cloud 接続情報を含むローカル構成ファイルも生成されます。これは、他のデモや自動化の際に便利です。このファイルをstack-configs/java-service-account-<SERVICE_ACCOUNT_ID>.configで確認します。これは、以下のようになります。# ------------------------------ # ENVIRONMENT ID: <ENVIRONMENT ID> # SERVICE ACCOUNT ID: <SERVICE ACCOUNT ID> # KAFKA CLUSTER ID: <KAFKA CLUSTER ID> # SCHEMA REGISTRY CLUSTER ID: <SCHEMA REGISTRY CLUSTER ID> # KSQLDB APP ID: <KSQLDB APP ID> # ------------------------------ security.protocol=SASL_SSL sasl.mechanism=PLAIN bootstrap.servers=<BROKER ENDPOINT> sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username='<API KEY>' password='<API SECRET>'; basic.auth.credentials.source=USER_INFO basic.auth.user.info=<SR API KEY>:<SR API SECRET> schema.registry.url=https://<SR ENDPOINT> ksql.endpoint=<KSQLDB ENDPOINT> ksql.basic.auth.user.info=<KSQLDB API KEY>:<KSQLDB API SECRET>
ccloud-stack の破棄¶
前の手順で作成した
cloud-stackを破棄するには、bash スクリプト ccloud_stack_destroy.sh を呼び出し、上記の手順で自動生成されたクライアントプロパティファイルを渡します。デフォルトでは、これで、構成ファイルのサービスアカウント ID で指定された Confluent Cloud 環境を含め、すべてのリソースが破棄されます。./ccloud_stack_destroy.sh stack-configs/java-service-account-<SERVICE_ACCOUNT_ID>.config
Confluent Cloud のすべてのサンプルでは、実際の Confluent Cloud リソースを使用しています。Confluent Cloud のサンプルの実行を終了したら、予定外の課金を回避するために、すべての Confluent Cloud リソースが破棄されていることを直接確認してください。
詳細¶
詳細については、「ccloud-stack の破棄」を参照してください。
高度なオプション¶
クラウドプロバイダーとリージョンの選択¶
デフォルトでは、cloud-stack ユーティリティにより、クラウドプロバイダー aws のリージョン us-west-2 にリソースが作成されます。デフォルト以外の別のクラウドプロバイダーまたはリージョンでリソースを作成する場合は、次の手順を実行します。
Confluent CLI を使用して、使用可能なクラウドプロバイダーおよびリージョンを表示します。
confluent kafka region list
ccloud-stackを作成し、次の例に示すように、パラメーターCLUSTER_CLOUDおよびCLUSTER_REGIONをオーバーライドします。CLUSTER_CLOUD=aws CLUSTER_REGION=us-west-2 ./ccloud_stack_create.sh
既存の環境の再利用¶
デフォルトでは、新しい ccloud-stack により、新しい環境が作成されます。つまり、デフォルトでは、./ccloud_stack_create.sh によって新しい環境が作成され、./ccloud_stack_destroy.sh によって、構成ファイルで指定された環境が削除されます。ただし、Confluent Cloud には、組織ごとの環境の制限 があるため、既存の環境内で作業を行うことが望ましい場合があります。
新しいスタックの作成時に既存の環境を再利用するには、例に示すように、パラメーター ENVIRONMENT に既存の環境の ID を設定します。
ENVIRONMENT=env-oxv5x ./ccloud_stack_create.sh
ccloud-stack で作成されたリソースを破棄する場合、デフォルトの動作では、構成ファイルのサービスアカウント ID で指定された環境が破棄されます。ただし、これには 2 つの付加的なオプションがあります。
ccloud-stack 内の他のすべてのリソースを破棄する際に環境を保持するには、次の例に示すように、パラメーター PRESERVE_ENVIRONMENT=true に設定します。PRESERVE_ENVIRONMENT=true を設定しない場合は、構成ファイルのサービスアカウント ID で指定された環境が削除されます。
PRESERVE_ENVIRONMENT=true ./ccloud_stack_destroy.sh stack-configs/java-service-account-<SERVICE_ACCOUNT_ID>.config
ccloud-stack 内の他のすべてのリソースを破棄する際に環境を破棄する場合で、環境名にサービスアカウントが含まれていない（同じ環境内に複数の ccloud-stacks が作成されていた）場合は、次の例に示すように、パラメーター ENVIRONMENT_NAME_PREFIX=ccloud-stack-<SERVICE_ACCOUNT_ID> を設定します。環境名のサービスアカウント ID は、構成名のサービスアカウント ID とは異なることに注意してください。環境名のプレフィックスを指定しないと、破棄の関数で、削除対象の適切な環境の ID を特定することができなくなります。
ENVIRONMENT_NAME_PREFIX=ccloud-stack-<SERVICE_ACCOUNT_ID_original> ./ccloud_stack_destroy.sh stack-configs/java-service-account-<SERVICE_ACCOUNT_ID_current>.config
自動化されたワークフロー¶
用意されている bash スクリプト ccloud_stack_create.sh と ccloud_stack_destroy.sh を使用して ccloud-stack の作成や破棄を行わない場合は、ccloud_library を取得し、関数 ccloud::create_ccloud_stack() と ccloud::destroy_ccloud_stack() を直接呼び出すことができます。
ccloud_library を取得します。
wget -O ccloud_library.sh https://raw.githubusercontent.com/confluentinc/examples/latest/utils/ccloud_library.sh
このライブラリをソースとして指定します。
source ./ccloud_library.shまたは、構成パラメーター
CLUSTER_CLOUDおよびCLUSTER_REGIONをオーバーライドします。CLUSTER_CLOUD=aws CLUSTER_REGION=us-west-2
bash 関数をコマンドラインから直接実行します。
Confluent Cloud ksqlDB を使用せずに
cloud-stackを作成する場合:ccloud::create_ccloud_stack
Confluent Cloud ksqlDB を使用して
cloud-stackを作成する場合:ccloud::create_ccloud_stack trueccloud-stackを破棄するために、次のコマンドを実行します。デフォルトでは、これで、構成ファイルのサービスアカウント ID で指定された Confluent Cloud 環境を含め、すべてのリソースが破棄されます。ccloud::destroy_ccloud_stack $SERVICE_ACCOUNT_ID
その他のリソース¶
- Confluent Cloud 使用時の Kafka クライアントアプリケーションの構成、モニタリング、最適化を行うための実用的なガイドが必要な場合は、「Confluent Cloud でのクライアントアプリケーションの開発」を参照してください。
- Confluent Cloud を使用した、オンプレミスとクラウドの両方でのデプロイを使用するデータパイプラインの管理 についてのブログをご覧ください。
ccloud-stackの使用方法の例については、「Confluent Cloud のサンプル」または「Confluent Cloud に接続する Apache Kafka® クライアント用の Observability のデモ」を参照してください。