Atualizar uma ACL do Kafka gerenciado

Depois de criar um recurso de ACL do Serviço gerenciado para Apache Kafka, é possível editar a configuração dele para atualizar a lista de entradas de ACL.

É possível atualizar um recurso de ACL do Serviço gerenciado para Apache Kafka de duas maneiras:

Substituição completa: substitui toda a lista de entradas de ACL, conforme documentado nesta página.
Atualização incremental: adiciona ou remove uma única entrada de ACL, conforme documentado nas páginas Adicionar uma entrada de ACL e Remover uma entrada de ACL.

Não é possível modificar a lista de entradas da ACL para ficar vazia usando uma operação de atualização. Para remover todas as entradas de um padrão de recurso, exclua o recurso de ACL do Serviço gerenciado para Apache Kafka.

Papéis e permissões necessárias

Para receber as permissões necessárias para atualizar uma ACL do Serviço gerenciado para Apache Kafka, peça ao administrador para conceder a você o papel do IAM de Editor de ACLs gerenciadas do Kafka (roles/managedkafka.aclEditor) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para atualizar uma ACL do Managed Service para Apache Kafka. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para atualizar uma ACL do Serviço Gerenciado para Apache Kafka:

Conceda essa permissão na ACL solicitada para atualizar usando a substituição completa (API UpdateAcl): managedkafka.acls.update
Conceda essa permissão na ACL solicitada para atualizar usando mudanças incrementais (API AddAclEntry ou RemoveAclEntry): managedkafka.acls.updateEntries

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações sobre a função Editor de ACLs gerenciadas do Kafka, consulte Funções predefinidas do serviço gerenciado do Google Cloud para Apache Kafka.

A propriedade "etag"

O campo etag é usado para controle de simultaneidade otimista. Uma ETag é retornada na resposta às operações GetAcl e CreateAcl. Inclua essa ETag na solicitação UpdateAcl para garantir que as mudanças sejam aplicadas à mesma versão do recurso de ACL do Serviço gerenciado para Apache Kafka que você recuperou. Isso evita a perda de atualizações se o recurso tiver sido modificado simultaneamente.

Um caractere T terminal na ETag indica que a lista de entradas da ACL foi truncada na resposta porque excedeu o número máximo de itens de campo repetíveis. Mais entradas para esse padrão de recurso existem diretamente no cluster do Kafka, mas não puderam ser representadas no recurso de ACL do Serviço gerenciado para Apache Kafka. Não é possível fazer atualizações de substituição completa em recursos com entradas de ACL truncadas. Nesse cenário, use APIs padrão do Apache Kafka, como kafka-acls.sh ou o AdminClient, para gerenciar as ACLs diretamente.

Substituição completa das entradas de ACL

Use o método da API UpdateAcl ou o comando gcloud managed-kafka acls update para fazer uma substituição completa da lista de entradas da ACL. Todo o campo acl_entries no recurso é substituído pela lista enviada na solicitação de atualização.

Para modificar a lista usando esse método, por exemplo, para adicionar ou remover uma única entrada de ACL mantendo outras, siga estas etapas:

Recupere a lista atual de entradas de ACL e a ETag usando o comando describe.
Construa a nova lista de entradas de ACL.
Execute o comando gcloud managed-kafka acls update com a ETag recuperada.

A seção a seguir mostra como usar o comando gcloud managed-kafka acls update para fazer uma substituição completa da lista de entradas de 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
```
Execute o comando gcloud managed-kafka acls update para substituir todas as entradas de ACL atuais pelas especificadas:

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='*' \

Substitua:

ACL_ID (obrigatório): o ID do recurso de ACL do Serviço gerenciado para Apache Kafka a ser atualizado. Para mais informações sobre o ID da ACL, consulte ID da ACL.
CLUSTER_ID (obrigatório): o ID do cluster que contém o recurso de ACL.
LOCATION (obrigatório): a região em que o cluster está localizado. Para mais informações sobre a região, consulte Locais com suporte.
ETAG_VALUE (obrigatório): o valor de ETag obtido de uma operação de descrição ou criação anterior para esse recurso de ACL.
--acl-entry (obrigatório): especifica uma entrada de ACL para incluir na lista new. Repita essa flag para incluir várias entradas. Toda a lista atual é substituída pelas entradas especificadas no comando.

PRINCIPAL (obrigatório): o principal desta entrada de ACL. Use o formato User:{google_service_account_email} ou o caractere curinga User:*.
OPERATION_TYPE (obrigatório): o tipo de operação para esta entrada de ACL. Os valores permitidos incluem ALL, READ, WRITE, CREATE, DELETE, ALTER, DESCRIBE, CLUSTER_ACTION, DESCRIBE_CONFIGS, ALTER_CONFIGS e IDEMPOTENT_WRITE.
PERMISSION_TYPE (obrigatório): o tipo de permissão a ser atualizada: ALLOW ou DENY.
HOST (obrigatório): o host do cliente da entrada da ACL a ser atualizada. Para o Google Cloud Managed Service para Apache Kafka, esse valor precisa ser definido como o curinga '*'.

Exemplo de substituição completa

Esse comando substitui todas as entradas de ACL atuais do padrão de recurso topic/orders no test-kafka-cluster localizado em us-central1 por uma única entrada nova. Essa nova entrada concede permissão WRITE à conta de serviço producer-app@test-project.iam.gserviceaccount.com. O comando requer o etag atual do recurso ACL, que é "AYk=Ags=" neste exemplo.

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='*'

Se o comando for bem-sucedido, a saída vai mostrar a configuração atualizada do recurso ACL, incluindo a nova lista aclEntries e um novo etag. Todas as entradas anteriores desse recurso de ACL são removidas.

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

Atualização incremental de entradas de ACL

É possível adicionar ou remover itens de entrada de ACL individuais sem substituir a lista inteira usando os métodos de API AddAclEntry e RemoveAclEntry ou os comandos gcloud managed-kafka acls add-acl-entry e gcloud managed-kafka acls remove-acl-entry correspondentes. Esses métodos não exigem uma ETag.

Usar AddAclEntry adiciona uma única entrada de ACL ao recurso de ACL do Serviço gerenciado para Apache Kafka. Isso é análogo à criação de um único novo AclBinding do Apache Kafka. Para mais informações, consulte Adicionar uma entrada de ACL.
Usar RemoveAclEntry remove uma única entrada de ACL do recurso de ACL do Serviço gerenciado para Apache Kafka. Isso é análogo à exclusão de um único AclBinding do Apache Kafka. Para mais informações, consulte Remover uma entrada de ACL.

A seguir

Apache Kafka® é uma marca registrada da The Apache Software Foundation ou afiliadas nos Estados Unidos e/ou em outros países.