マネージド Kafka ACL を更新する

Managed Service for Apache Kafka ACL リソースを作成したら、構成を編集して ACL エントリのリストを更新できます。

Managed Service for Apache Kafka ACL リソースの更新は、次の 2 つの方法で行うことができます。

完全置換: このページで説明されているように、ACL エントリのリスト全体を上書きします。
増分更新: ACL エントリを追加すると ACL エントリを削除するのページに記載されているように、単一の ACL エントリを追加または削除します。

更新オペレーションを使用して、ACL エントリのリストを空に変更することはできません。リソースパターンのすべてのエントリを削除するには、代わりに Managed Service for Apache Kafka ACL リソースを削除します。

必要なロールと権限

Managed Service for Apache Kafka ACL の更新に必要な権限を取得するには、プロジェクトに対する Managed Kafka ACL 編集者（roles/managedkafka.aclEditor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、Managed Service for Apache Kafka ACL の更新に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

Managed Service for Apache Kafka の ACL を更新するには、次の権限が必要です。

リクエストされた ACL にこの権限を付与して、完全置換（UpdateAcl API）を使用して更新します。 managedkafka.acls.update
増分変更（AddAclEntry または RemoveAclEntry API）を使用して更新するリクエストされた ACL にこの権限を付与します。 managedkafka.acls.updateEntries

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

Managed Kafka ACL エディタ ロールの詳細については、Google Cloud Managed Service for Apache Kafka の事前定義ロールをご覧ください。

etag プロパティ

etag フィールドは、オプティミスティック同時実行制御に使用されます。etag は、GetAcl オペレーションと CreateAcl オペレーションのレスポンスで返されます。この etag を UpdateAcl リクエストに含めて、取得した Managed Service for Apache Kafka ACL リソースの同じバージョンに変更が適用されるようにする必要があります。これにより、リソースが同時に変更された場合に更新が失われるのを防ぎます。

etag の末尾の T 文字は、繰り返し可能なフィールドアイテムの最大数を超えたため、レスポンスで ACL エントリのリストが切り捨てられたことを示します。このリソースパターンのエントリが Kafka クラスタに直接存在しますが、Managed Service for Apache Kafka ACL リソースで表現できませんでした。ACL エントリが切り捨てられたリソースでは、完全な置換更新はサポートされていません。このシナリオでは、kafka-acls.sh や AdminClient などの標準の Apache Kafka API を使用して、ACL を直接管理します。

ACL エントリの完全な置換

UpdateAcl API メソッドまたは gcloud managed-kafka acls update コマンドを使用して、ACL エントリリストの完全な置換を実行できます。リソースの acl_entries フィールド全体が、更新リクエストで送信されたリストで上書きされます。

この方法でリストを変更するには（たとえば、他の ACL エントリを保持しながら単一の ACL エントリを追加または削除するには）、次の操作を行います。

describe コマンドを使用して、ACL エントリの現在のリストと etag を取得します。
ACL エントリの新しいリストを作成します。
取得した etag とともに gcloud managed-kafka acls update コマンドを実行します。

次のセクションでは、gcloud managed-kafka acls update コマンドを使用して ACL エントリリストの完全な置換を行う方法について説明します。

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
gcloud managed-kafka acls update コマンドを実行して、既存のすべての ACL エントリを指定されたエントリに置き換えます。

gcloud managed-kafka acls update ACL_ID \
    --cluster=CLUSTER_ID \
    --location=LOCATION \
    --etag=ETAG_VALUE \
    --acl-entry=principal='PRINCIPAL',operation=OPERATION_TYPE,permission_type=PERMISSION_TYPE,host='*' \

次のように置き換えます。

ACL_ID（必須）: 更新する Managed Service for Apache Kafka ACL リソースの ID。ACL ID の詳細については、ACL ID をご覧ください。
CLUSTER_ID（必須）: ACL リソースを含むクラスタの ID。
LOCATION（必須）: クラスタが配置されているリージョン。リージョンの詳細については、サポートされているロケーションをご覧ください。
ETAG_VALUE（必須）: この ACL リソースの以前の describe オペレーションまたは create オペレーションから取得した etag 値。
--acl-entry（必須）: 新しいリストに含める ACL エントリを指定します。このフラグを繰り返して、複数のエントリを含めることができます。既存のリスト全体が、コマンドで指定されたエントリに置き換えられます。

PRINCIPAL（必須）: この ACL エントリのプリンシパル。User:{google_service_account_email} 形式またはワイルドカード User:* を使用します。
OPERATION_TYPE（必須）: この ACL エントリのオペレーションタイプ。使用できる値は、ALL、READ、WRITE、CREATE、DELETE、ALTER、DESCRIBE、CLUSTER_ACTION、DESCRIBE_CONFIGS、ALTER_CONFIGS、IDEMPOTENT_WRITE です。
PERMISSION_TYPE（必須）: 更新する権限のタイプ（ALLOW または DENY）。
HOST（必須）: 更新する ACL エントリのクライアントホスト。Google Cloud Managed Service for Apache Kafka の場合、この値はワイルドカード '*' に設定する必要があります。

完全な置き換えの例

このコマンドは、us-central1 にある test-kafka-cluster の topic/orders リソースパターンの既存の ACL エントリをすべて新しい単一のエントリに置き換えます。この新しいエントリは、サービスアカウント producer-app@test-project.iam.gserviceaccount.com に WRITE 権限を付与します。このコマンドには、ACL リソースの現在の etag（この例では "AYk=Ags="）が必要です。

gcloud managed-kafka acls update topic/orders \
    --cluster=test-kafka-cluster \
    --location=us-central1 \
    --project=test-project \
    --etag='"AYk=Ags="' \
    --acl-entry=principal='User:producer-app@test-project.iam.gserviceaccount.com',operation=WRITE,permission_type=ALLOW,host='*'

コマンドが成功すると、出力に更新された ACL リソース構成が表示されます。これには、新しい aclEntries リストと新しい etag が含まれます。この ACL リソースの既存のエントリはすべて削除されます。

aclEntries:
-   host: '*'
  operation: WRITE
  permissionType: ALLOW
  principal: User:producer-app@test-project.iam.gserviceaccount.com
etag: '"Bcn=Def="'  # Note: The etag value changes after a successful update.
name: projects/test-project/locations/us-central1/clusters/my-kafka-cluster/acls/topic/orders
resourcePatternType: TOPIC

ACL エントリの増分更新

AddAclEntry と RemoveAclEntry の API メソッド、または対応する gcloud managed-kafka acls add-acl-entry と gcloud managed-kafka acls remove-acl-entry のコマンドを使用すると、リスト全体を置き換えることなく、個々の ACL エントリ項目を追加または削除できます。これらのメソッドでは etag は必要ありません。

AddAclEntry を使用すると、Managed Service for Apache Kafka ACL リソースに新しい ACL エントリが 1 つ追加されます。これは、単一の新しい Apache Kafka AclBinding を作成するのと同様です。詳細については、ACL エントリを追加するをご覧ください。
RemoveAclEntry を使用すると、Managed Service for Apache Kafka ACL リソースから既存の単一の ACL エントリが削除されます。これは、単一の Apache Kafka AclBinding を削除するのと同様です。詳細については、ACL エントリを削除するをご覧ください。

次のステップ

Apache Kafka® は、Apache Software Foundation または米国その他の諸国における関連会社の商標です。