Actualiza una ACL de Kafka administrado

Después de crear un recurso de ACL de Managed Service para Apache Kafka, puedes editar su configuración para actualizar la lista de entradas de ACL.

Un recurso de ACL de Managed Service para Apache Kafka se puede actualizar de dos maneras:

Reemplazo completo: Sobrescribe toda la lista de entradas de LCA, como se documenta en esta página.
Actualización incremental: Agrega o quita una sola entrada de LCA, como se documenta en las páginas Cómo agregar una entrada de LCA y Cómo quitar una entrada de LCA.

No puedes modificar la lista de entradas de LCA para que esté vacía con una operación de actualización. Para quitar todas las entradas de un patrón de recursos, borra el recurso de LCA de Managed Service para Apache Kafka.

Roles y permisos requeridos

Para obtener los permisos que necesitas para actualizar una ACL del servicio administrado para Apache Kafka, pídele a tu administrador que te otorgue el rol de IAM de Editor de ACL de Kafka administrado (roles/managedkafka.aclEditor) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para actualizar una LCA de Managed Service for Apache Kafka. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para actualizar una LCA de Managed Service para Apache Kafka:

Otorga este permiso en la LCA solicitada para actualizarla con un reemplazo completo (API de UpdateAcl): managedkafka.acls.update
Otorga este permiso en la LCA solicitada para actualizarla con cambios incrementales (API de AddAclEntry o RemoveAclEntry): managedkafka.acls.updateEntries

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener más información sobre el rol de Editor de ACL de Kafka administrado, consulta Roles predefinidos de Google Cloud Managed Service para Apache Kafka.

La propiedad etag

El campo etag se usa para el control de simultaneidad optimista. Se devuelve un ETag en la respuesta a las operaciones GetAcl y CreateAcl. Debes incluir este ETag en la solicitud UpdateAcl para asegurarte de que los cambios se apliquen a la misma versión del recurso de ACL de Managed Service for Apache Kafka que recuperaste. Esto evita que se pierdan actualizaciones si el recurso se modificó de forma simultánea.

Un carácter T terminal en el ETag indica que la lista de entradas de LCA se truncó en la respuesta porque superó la cantidad máxima de elementos de campo repetibles. Existen más entradas para este patrón de recursos directamente en el clúster de Kafka, pero no se pudieron representar en el recurso de ACL de Managed Service para Apache Kafka. No se admiten las actualizaciones de reemplazo completo para los recursos con entradas de LCA truncadas. En este caso, usa las APIs estándar de Apache Kafka, como kafka-acls.sh o AdminClient, para administrar las LCA directamente.

Reemplazo completo de las entradas de LCA

Puedes usar el método de la API de UpdateAcl o el comando gcloud managed-kafka acls update para realizar un reemplazo completo de la lista de entradas de la ACL. Todo el campo acl_entries del recurso se reemplaza por la lista enviada en la solicitud de actualización.

Para modificar la lista con este método, por ejemplo, para agregar o quitar una sola entrada de LCA y conservar las demás, sigue estos pasos:

Recupera la lista actual de entradas de LCA y el ETag con el comando describe.
Construye la nueva lista de entradas de LCA.
Ejecuta el comando gcloud managed-kafka acls update junto con el ETag recuperado.

En la siguiente sección, se muestra cómo usar el comando gcloud managed-kafka acls update para reemplazar por completo la lista de entradas de la 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
```
Ejecuta el comando gcloud managed-kafka acls update para reemplazar todas las entradas de ACL existentes por las 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='*' \

Reemplaza lo siguiente:

ACL_ID (obligatorio): Es el ID del recurso de ACL de Managed Service para Apache Kafka que se actualizará. Para obtener más información sobre el ID de la LCA, consulta ID de la LCA.
CLUSTER_ID (obligatorio): Es el ID del clúster que contiene el recurso de la ACL.
LOCATION (obligatorio): Es la región en la que se encuentra el clúster. Para obtener más información sobre la región, consulta Ubicaciones admitidas.
ETAG_VALUE (obligatorio): Es el valor de ETag que se obtuvo de una operación de descripción o creación anterior para este recurso de LCA.
--acl-entry (obligatorio): Especifica una entrada de LCA para incluir en la lista nueva. Puedes repetir esta marca para incluir varias entradas. Toda la lista existente se reemplaza por las entradas especificadas en el comando.

PRINCIPAL (obligatorio): Es el principal de esta entrada de LCA. Usa el formato User:{google_service_account_email} o el comodín User:*.
OPERATION_TYPE (obligatorio): Es el tipo de operación para esta entrada de LCA. Los valores permitidos incluyen ALL, READ, WRITE, CREATE, DELETE, ALTER, DESCRIBE, CLUSTER_ACTION, DESCRIBE_CONFIGS, ALTER_CONFIGS y IDEMPOTENT_WRITE.
PERMISSION_TYPE (obligatorio): Es el tipo de permiso que se actualizará: ALLOW o DENY.
HOST (obligatorio): Es el host del cliente de la entrada de la LCA que se actualizará. En el caso de Google Cloud Managed Service para Apache Kafka, este valor debe establecerse en el comodín '*'.

Ejemplo de reemplazo completo

Este comando reemplaza todas las entradas de LCA existentes para el patrón de recursos topic/orders en test-kafka-cluster ubicado en us-central1 con una sola entrada nueva. Esta nueva entrada otorga permiso WRITE a la cuenta de servicio producer-app@test-project.iam.gserviceaccount.com. El comando requiere el etag actual del recurso de ACL, que es "AYk=Ags=" en este ejemplo.

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 el comando se ejecuta correctamente, el resultado muestra la configuración actualizada del recurso de ACL, incluida la nueva lista de aclEntries y un nuevo etag. Se quitarán todas las entradas existentes anteriormente para este recurso de LCA.

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

Actualización incremental de las entradas de LCA

Puedes agregar o quitar elementos de entrada de LCA individuales sin reemplazar toda la lista con los métodos de la API de AddAclEntry y RemoveAclEntry, o los comandos correspondientes de gcloud managed-kafka acls add-acl-entry y gcloud managed-kafka acls remove-acl-entry. Estos métodos no requieren una ETag.

Usar AddAclEntry agrega una sola entrada de ACL nueva al recurso de ACL de Managed Service for Apache Kafka. Esto es análogo a crear un solo AclBinding nuevo de Apache Kafka. Para obtener más información, consulta Cómo agregar una entrada de LCA.
Con RemoveAclEntry, se quita una sola entrada de ACL existente del recurso de ACL de Managed Service para Apache Kafka. Esto es análogo a borrar un solo AclBinding de Apache Kafka. Para obtener más información, consulta Cómo quitar una entrada de ACL.

¿Qué sigue?

Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados en Estados Unidos y otros países.