Mettre à jour une LCA Managed Kafka

Après avoir créé une ressource LCA Managed Service pour Apache Kafka, vous pouvez modifier sa configuration pour mettre à jour la liste des entrées LCA.

Il existe deux façons de mettre à jour une ressource LCA Managed Service pour Apache Kafka :

Remplacement complet : remplace l'intégralité de la liste des entrées de LCA, comme indiqué sur cette page.
Mise à jour incrémentielle : ajoute ou supprime une seule entrée de LCA, comme indiqué dans les pages Ajouter une entrée de LCA et Supprimer une entrée de LCA.

Vous ne pouvez pas vider la liste des entrées de LCA à l'aide d'une opération de mise à jour. Pour supprimer toutes les entrées d'un modèle de ressource, supprimez plutôt la ressource LCA Managed Service pour Apache Kafka.

Rôles et autorisations nécessaires

Pour obtenir les autorisations nécessaires pour mettre à jour une LCA Managed Service pour Apache Kafka, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de LCA Managed Kafka (roles/managedkafka.aclEditor) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour mettre à jour une LCA Managed Service for Apache Kafka. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour mettre à jour une liste ACL Managed Service pour Apache Kafka :

Accordez cette autorisation sur la LCA demandée pour la mettre à jour en la remplaçant complètement (API UpdateAcl) : managedkafka.acls.update
Accordez cette autorisation sur la LCA à mettre à jour à l'aide de modifications incrémentielles (API AddAclEntry ou RemoveAclEntry) : managedkafka.acls.updateEntries

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour en savoir plus sur le rôle Éditeur des LCA Kafka gérés, consultez Rôles prédéfinis de Google Cloud Managed Service pour Apache Kafka.

Propriété etag

Le champ etag est utilisé pour le contrôle de simultanéité optimiste. Un etag est renvoyé dans la réponse aux opérations GetAcl et CreateAcl. Vous devez inclure cet etag dans la requête UpdateAcl pour vous assurer que vos modifications s'appliquent à la même version de la ressource LCA Managed Service pour Apache Kafka que celle que vous avez récupérée. Cela permet d'éviter la perte de mises à jour si la ressource a été modifiée simultanément.

Un caractère T terminal dans l'etag indique que la liste des entrées ACL a été tronquée dans la réponse, car elle dépassait le nombre maximal d'éléments de champ répétables. D'autres entrées pour ce modèle de ressource existent directement sur le cluster Kafka, mais n'ont pas pu être représentées dans la ressource LCA Managed Service pour Apache Kafka. Les mises à jour de remplacement complet ne sont pas acceptées pour les ressources dont les entrées LCA sont tronquées. Dans ce scénario, utilisez des API Apache Kafka standards telles que kafka-acls.sh ou AdminClient pour gérer directement les LCA.

Remplacement complet des entrées de LCA

Vous pouvez utiliser la méthode d'API UpdateAcl ou la commande gcloud managed-kafka acls update pour remplacer complètement la liste des entrées ACL. L'intégralité du champ acl_entries de la ressource est remplacée par la liste envoyée dans la demande de mise à jour.

Pour modifier la liste à l'aide de cette méthode, par exemple pour ajouter ou supprimer une seule entrée ACL tout en conservant les autres, procédez comme suit :

Récupérez la liste actuelle des entrées de LCA et l'etag à l'aide de la commande describe.
Construisez la nouvelle liste d'entrées LCA.
Exécutez la commande gcloud managed-kafka acls update avec l'etag récupéré.

La section suivante montre comment utiliser la commande gcloud managed-kafka acls update pour remplacer complètement la liste des entrées 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
```
Exécutez la commande gcloud managed-kafka acls update pour remplacer toutes les entrées ACL existantes par celles spécifiées :

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

Remplacez les éléments suivants :

ACL_ID (obligatoire) : ID de la ressource LCA Managed Service pour Apache Kafka à mettre à jour. Pour en savoir plus sur l'ID de la LCA, consultez ID de la LCA.
CLUSTER_ID (obligatoire) : ID du cluster contenant la ressource ACL.
LOCATION (obligatoire) : région dans laquelle se trouve le cluster. Pour en savoir plus sur la région, consultez la section Emplacements disponibles.
ETAG_VALUE (obligatoire) : valeur etag obtenue à partir d'une opération de description ou de création précédente pour cette ressource ACL.
--acl-entry (obligatoire) : spécifie une entrée de LCA à inclure dans la nouvelle liste. Vous pouvez répéter cette option pour inclure plusieurs entrées. La liste existante est entièrement remplacée par les entrées spécifiées dans la commande.

PRINCIPAL (obligatoire) : principal pour cette entrée de LCA. Utilisez le format User:{google_service_account_email} ou le caractère générique User:*.
OPERATION_TYPE (obligatoire) : type d'opération pour cette entrée LCA. Les valeurs autorisées sont ALL, READ, WRITE, CREATE, DELETE, ALTER, DESCRIBE, CLUSTER_ACTION, DESCRIBE_CONFIGS, ALTER_CONFIGS et IDEMPOTENT_WRITE.
PERMISSION_TYPE (obligatoire) : type d'autorisation à modifier : ALLOW ou DENY.
HOST (obligatoire) : hôte client de l'entrée de la LCA à mettre à jour. Pour Google Cloud Managed Service pour Apache Kafka, cette valeur doit être définie sur le caractère générique '*'.

Exemple de remplacement complet

Cette commande remplace toutes les entrées ACL existantes pour le modèle de ressource topic/orders dans test-kafka-cluster situé dans us-central1 par une seule et nouvelle entrée. Cette nouvelle entrée accorde l'autorisation WRITE au compte de service producer-app@test-project.iam.gserviceaccount.com. La commande nécessite le etag actuel de la ressource ACL, qui est "AYk=Ags=" dans cet exemple.

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

Si la commande aboutit, le résultat affiche la configuration de la ressource ACL mise à jour, y compris la nouvelle liste aclEntries et un nouveau etag. Toutes les entrées existantes pour cette ressource de LCA sont supprimées.

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

Mise à jour incrémentielle des entrées de LCA

Vous pouvez ajouter ou supprimer des éléments d'entrée de LCA individuels sans remplacer la liste entière à l'aide des méthodes d'API AddAclEntry et RemoveAclEntry, ou des commandes gcloud managed-kafka acls add-acl-entry et gcloud managed-kafka acls remove-acl-entry correspondantes. Ces méthodes ne nécessitent pas d'etag.

L'utilisation de AddAclEntry ajoute une seule entrée de LCA à la ressource LCA Managed Service pour Apache Kafka. Cela revient à créer un seul AclBinding Apache Kafka. Pour en savoir plus, consultez Ajouter une entrée de LCA.
L'utilisation de RemoveAclEntry supprime une entrée LCA existante de la ressource LCA Managed Service pour Apache Kafka. Cela revient à supprimer un seul AclBinding Apache Kafka. Pour en savoir plus, consultez Supprimer une entrée LCA.

Étapes suivantes

Apache Kafka® est une marque déposée d'Apache Software Foundation ou de ses filiales aux États-Unis et/ou dans d'autres pays.