Confluent Cloud 向け ccloud-stack ユーティリティ

概要

この ccloud-stack ユーティリティにより、フルマネージド型サービスのスタックが Confluent Cloud に作成されます。この方法で、正しい資格情報とアクセス許可で Confluent Cloud にリソースがすばやく作成され、他のサンプルの学習、拡張、作成の際に使用できます。このユーティリティは、Confluent Cloud CLI を内部で使用して、以下のことを Confluent Cloud で動的に行います。

  • 新しい環境を作成する
  • 新しいサービスアカウントを作成する。
  • 新しい Kafka クラスターとそれに関連する資格情報を作成する。
  • スキーマレジストリとそれに関連する資格情報を有効にする。
  • (省略可)新しい ksqlDB アプリケーションとそれに関連する資格情報を作成する。
  • サービスアカウント用 ACL をワイルドカードを使用して作成する。
../../../../_images/ccloud-stack-resources.png

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 を有効にして ccloud-stack を実行した場合は、直ちに課金が開始されます。

以下に、ユーティリティが発行し、Confluent Cloud にリソースを作成する Confluent Cloud CLI コマンドのリストを示します(関数 ccloud::create_ccloud_stack() のソースコードは ccloud_library にあります)。デフォルトでは、Confluent Cloud ksqlDB アプリケーションは ccloud-stack で作成されないため、明示的に有効にする必要があります。

ccloud service-account create $SERVICE_NAME --description $SERVICE_NAME -o json

ccloud environment create $ENVIRONMENT_NAME -o json

ccloud kafka cluster create "$CLUSTER_NAME" --cloud $CLUSTER_CLOUD --region $CLUSTER_REGION
ccloud api-key create --service-account $SERVICE_ACCOUNT_ID --resource $RESOURCE -o json    // for kafka

ccloud schema-registry cluster enable --cloud $SCHEMA_REGISTRY_CLOUD --geo $SCHEMA_REGISTRY_GEO -o json
ccloud 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:
ccloud ksql app create --cluster $CLUSTER --api-key "$KAFKA_API_KEY" --api-secret "$KAFKA_API_SECRET" -o json "$KSQLDB_NAME"
ccloud api-key create --service-account $SERVICE_ACCOUNT_ID --resource $RESOURCE -o json    // for ksqlDB REST API

ccloud kafka acl create --allow --service-account $SERVICE_ACCOUNT_ID --operation <....>    // permissive ACLs for all services

Confluent Cloud のプロモーションコード

Confluent Cloud Console の Billing & payment セクションでプロモーションコード C50INTEG を入力すると、Confluent Cloud で $50 相当を無料で使用できます(詳細)。このプロモーションコードで、この Confluent Cloud サンプルの 1 日分の実行費用が補填されます。これを超えてサービスを利用すると、このサンプルで作成した Confluent Cloud リソースを破棄するまで、時間単位で課金されることがあります。

前提条件

ccloud-stack は、macOS 10.15.3 および bash バージョン 3.2.57 で検証済みです。それ以外のオペレーティングシステムまたはバージョンで問題が発生した場合は、confluentinc/examples で GitHub への問題を報告してください。

使用方法

セットアップ

  1. confluentinc/examples GitHub リポジトリのクローンを作成し、6.2.4-post ブランチをチェックアウトします。

    git clone https://github.com/confluentinc/examples
    cd examples
    git checkout 6.2.4-post
    
  2. ccloud-stack ユーティリティのディレクトリに変更します。

    cd ccloud/ccloud-stack/
    
  3. コマンド ccloud login で、Confluent Cloud のユーザー名とパスワードを使用して Confluent Cloud にログインします。--save 引数により、Confluent Cloud ユーザーログイン資格情報が保存されるか、ローカルの netrc ファイルに対してトークン(SSO の場合)が更新されます。

    ccloud login --save
    

ccloud-stack の作成

  1. デフォルトでは、cloud-stack ユーティリティにより、クラウドプロバイダー aws のリージョン us-west-2 にリソースが作成されます。これがターゲットのプロバイダーおよびリージョンである場合は、bash スクリプト ccloud_stack_create.sh を呼び出してスタックを作成します。ccloud-stack の構成時のその他のオプションについては、「高度なオプション」を参照してください。

    ./ccloud_stack_create.sh
    
  2. 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
    
  3. 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
    
  4. 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 の破棄

  1. 前の手順で作成した 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 にリソースが作成されます。デフォルト以外の別のクラウドプロバイダーまたはリージョンでリソースを作成する場合は、次の手順を実行します。

  1. Confluent Cloud CLI を使用して、使用可能なクラウドプロバイダーおよびリージョンを表示します。

    ccloud kafka region list
    
  2. 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.shccloud_stack_destroy.sh を使用して ccloud-stack の作成や破棄を行わない場合は、ccloud_library を取得し、関数 ccloud::create_ccloud_stack()ccloud::destroy_ccloud_stack() を直接呼び出すことができます。

  1. ccloud_library を取得します。

    wget -O ccloud_library.sh https://raw.githubusercontent.com/confluentinc/examples/latest/utils/ccloud_library.sh
    
  2. このライブラリをソースとして指定します。

    source ./ccloud_library.sh
    
  3. または、構成パラメーター CLUSTER_CLOUD および CLUSTER_REGION をオーバーライドします。

    CLUSTER_CLOUD=aws
    CLUSTER_REGION=us-west-2
    
  4. bash 関数をコマンドラインから直接実行します。

    Confluent Cloud ksqlDB を使用せずに cloud-stack を作成する場合:

    ccloud::create_ccloud_stack
    

    Confluent Cloud ksqlDB を使用して cloud-stack を作成する場合:

    ccloud::create_ccloud_stack true
    
  5. ccloud-stack を破棄するために、次のコマンドを実行します。デフォルトでは、これで、構成ファイルのサービスアカウント ID で指定された Confluent Cloud 環境を含め、すべてのリソースが破棄されます。

    ccloud::destroy_ccloud_stack $SERVICE_ACCOUNT_ID
    

Marketplace での実行

デフォルトでは、ccloud-stack がお支払い方法をチェックして、クレジットカードが登録されていることを確認します。ただし、Azure、GCP、AWS のセルフサービス方式の従量課金制アカウントを対象とした、クラウドプロバイダーの Marketplace 上で Confluent Cloud を使用している場合、お支払い方法は直接クラウドプロバイダーに関連付けられ、必ずしもクレジットカードに関連付けられているとは限りません。そのような場合は、ccloud-stack のチェックで不合格と判定されるため、なんらかの回避策が必要となります。

新しいスタックの作成時に、次の例のようにパラメーター CHECK_CREDIT_CARD=false を設定します。

CHECK_CREDIT_CARD=false ./ccloud_stack_create.sh

その他のリソース