建立代管 Kafka ACL

透過代管 Kafka 存取控制清單 (ACL)，您可以對 Managed Service for Apache Kafka 叢集內的操作進行精細授權。建立 Managed Kafka ACL 資源時，會為特定 Kafka 資源模式定義一組權限規則。如需基本概念，請參閱「使用 IAM 和 Kafka ACL 控管存取權」。

事前準備

確認您已有現有的 Managed Service for Apache Kafka 叢集。

必要角色和權限

如要取得建立代管 Kafka ACL 所需的權限，請要求管理員授予您專案的代管 Kafka ACL 編輯者 (roles/managedkafka.aclEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備建立代管 Kafka ACL 所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立代管 Kafka ACL，您必須具備下列權限：

在父項叢集上授予這項權限： managedkafka.acls.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

代管 Kafka ACL 編輯者 (roles/managedkafka.aclEditor) 角色可授予建立、查看、更新及刪除 ACL 資源的權限。如要進一步瞭解角色，請參閱「Managed Service for Apache Kafka 預先定義角色」。

代管 Kafka ACL 的屬性

建立代管 Kafka ACL 資源時，您必須定義下列屬性：

ACL ID

這是叢集和位置資訊中，代管 Kafka ACL 資源的專屬 ID。ACL_ID 的結構也會定義 ACL 規則適用的資源模式 (資源類型、資源名稱、模式類型)。

根據要用於 ACL 繫結的資源模式，選擇 ACL_ID：

叢集： cluster (適用於叢集資源本身)
特定主題： topic/{topic_name}
特定群組： consumerGroup/{group_name}
特定交易 ID： transactionalId/{transactional_id}
所有含有前置字元的主題： topicPrefixed/{prefix}
所有含有前置字串的消費者群組： consumerGroupPrefixed/{prefix}
所有含有前置字元的交易 ID： transactionalIdPrefixed/{prefix}
所有主題： allTopics (代表 topic/*)
所有群組： allConsumerGroups (代表 consumerGroup/*)
所有交易 ID： allTransactionalIds (代表 transactionalId/*)

詳情請參閱「Managed Service for Apache Kafka 資源命名指南」。

ACL ID 建立後即無法變更。這項設定無法變更。

ACL 項目

這是適用於 ACL ID 定義的資源模式的特定權限規則清單。

建立資源時，您至少須提供一個 ACL 項目；系統不允許空白清單。
每個代管 Kafka ACL 資源允許的項目數上限為 100。如果單一資源模式需要更多規則，您必須使用標準 Apache Kafka 工具直接管理 ACL。
每個 ACL 項目都包含下列欄位：
- 主體：套用規則的使用者或服務帳戶。請使用 User:{google_service_account_email} 格式指定，或使用萬用字元 User:*。
- 作業：Kafka 作業類型，例如 ALL、READ、WRITE、CREATE、DELETE、ALTER、DESCRIBE、CLUSTER_ACTION、DESCRIBE_CONFIGS、ALTER_CONFIGS 或 IDEMPOTENT_WRITE (不區分大小寫)。如需有效的作業和資源類型組合，請參閱 Apache Kafka 說明文件中的「Operations and Resources on Protocols」。
- Permission-type：ALLOW 或 DENY (不區分大小寫)。
- 主機：必須設為 Managed Service for Apache Kafka 的萬用字元 *。

您可以使用 --acl-entry 標記，直接在指令列上提供這些項目，也可以使用 --acl-entries-from-file 標記提供 JSON 或 YAML 檔案。

僅供輸出的資源模式屬性

建立 ACL 時，Managed Service for Apache Kafka 會根據提供的 ACL ID，填入下列資源模式欄位：

資源類型：從名稱衍生的 ACL 資源類型。只能設為以下任一種：CLUSTER、TOPIC、GROUP 或 TRANSACTIONAL_ID。
資源名稱：ACL 資源名稱 (或相符前置字元，適用於 PREFIXED 模式類型)，衍生自名稱。如果是 CLUSTER 資源類型，這項值一律為 "kafka-cluster"。可以是萬用字元常值 "*"。
ACL 模式類型：從名稱衍生的 ACL 模式類型。LITERAL 或 PREFIXED。

這些欄位僅供輸出，方便您將代管 Kafka ACL 資源對應至 Kafka ACL 繫結。

ETag

Etag 用於並行控制。系統會在 GetAcl 和 CreateAcl 作業的回應中傳回 Etag。呼叫端必須將該 Etag 放入 UpdateAcl 的要求中，確保變更套用至 Kafka 叢集中現有的 ACL 項目版本。

Etag 中的終端 'T' 字元表示 ACL 項目遭到截斷。Kafka 叢集上還有更多 ACL 項目，但因欄位重複限制，無法在 ACL 中傳回。

建立 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 create 指令：
```
gcloud managed-kafka acls create ACL_ID \
  --cluster=CLUSTER_ID \
  --location=LOCATION \
  --acl-entries-from-file=PATH_TO_FILE | \
  --acl-entry=principal=PRINCIPAL,operation=OPERATION, \
  permission-type=PERMISSION-TYPE,host=HOST \
```
更改下列內容：
- ACL_ID (必要)：Managed Kafka ACL 資源的專屬 ID。這會定義資源模式。如要進一步瞭解 ACL ID，請參閱「ACL ID」。
- CLUSTER_ID (必要)：建立 ACL 資源的叢集 ID。
- LOCATION (必要)：叢集所在的區域，例如 us-central1。請參閱「支援的位置」。
- 您必須指定下列其中一個旗標，才能提供 ACL 項目：
  - PATH_TO_FILE (必要)：本機 JSON 或 YAML 檔案的路徑，其中包含格式正確的 ACL 項目清單。
  - --acl-entry=principal=PRINCIPAL,operation=OPERATION, permission-type=PERMISSION-TYPE,host=HOST (必要)：直接指定單一 ACL 項目。針對要新增的每個項目重複使用這個旗標。

使用`--acl-entry`

執行 gcloud managed-kafka acls create 指令，直接提供 ACL 項目。您可以多次執行這項指令，為存取控制清單指定多個存取控制清單項目。

gcloud managed-kafka acls create ACL_ID \
  --cluster=CLUSTER_ID \
  --location=LOCATION \
  --acl-entry=principal=PRINCIPAL,operation=OPERATION, \
  permission-type=PERMISSION-TYPE,host=HOST\

更改下列內容：

ACL_ID (必填)：新 ACL 資源的 ID，例如 topic/my-topic 或 cluster。
CLUSTER_ID (必要)：叢集 ID。
LOCATION (必要)：叢集所在的區域，例如 us-central1。
--acl-entry (必要)：指定一個 ACL 項目。如要輸入多個項目，請重複使用這個旗標。
- PRINCIPAL_1、PRINCIPAL_2：ACL 項目主體，例如 'User:admin@example.iam.gserviceaccount.com 或 'User:*'。
- OPERATION_1、OPERATION_2：作業類型，例如 ALL 或 READ。
- PERMISSION_1、PERMISSION_2：權限類型，例如 ALLOW 或 DENY。
- HOST_1、HOST_2：ACL 項目主機。如果是 Google Cloud Managed Service for Apache Kafka，則必須設為萬用字元 '*'。

使用`--acl-entries-from-file`

建立本機檔案 (例如 acl_entries.yaml)，並以 YAML 格式加入必要的 ACL 項目：

---
aclEntries:
- principal: User:admin@project.iam.gserviceaccount.com
  operation: READ
  permissionType: ALLOW
  host: "*"
- principal: User:admin@project.iam.gserviceaccount.com
  operation: WRITE
  permissionType: ALLOW
  host: "*"

執行 gcloud managed-kafka acls create 指令，並參照該檔案：
```
gcloud managed-kafka acls create ACL_ID \
  --cluster=CLUSTER_ID \
  --location=LOCATION \
  --acl-entries-from-file=acl_entries.yaml
```
更改下列內容：
- ACL_ID (必要)：新 ACL 資源的 ID，例如 topic/my-topic 或 cluster。
- CLUSTER_ID (必要)：叢集 ID。
- LOCATION (必要)：叢集所在的區域，例如 us-central1。
- acl_entries.yaml (必要)：包含 ACL 項目清單的本機檔案路徑。

後續步驟

Apache Kafka® 是 The Apache Software Foundation 或其關聯企業在美國與/或其他國家/地區的註冊商標。

建立代管 Kafka ACL 透過集合功能整理內容 你可以依據偏好儲存及分類內容。