Crea y administra etiquetas

Antes de comenzar

Para obtener más información sobre qué son las etiquetas y cómo funcionan, consulta la Descripción general de Tag Manager.

Para utilizar los comandos de la herramienta de línea de comandos de gcloud de Tag Manager, el administrador de seguridad que está en la lista blanca de acceso debe habilitar la API en un proyecto del consumidor. Esto se puede hacer en la herramienta de gcloud con el siguiente comando:

gcloud services enable labelmanager.googleapis.com

Para crear y administrar etiquetas, debes tener la función roles/labelmanager.labelAdmin en el nivel del recurso de tu organización. Debes usar el comando add-policy-binding de la herramienta de gcloud para otorgar esta función, ya que no aparecerá en la IU.

Vista previa del registro

La API de Tag Manager se puede habilitar para proyectos individuales de Google Cloud. Si deseas llamar directamente a la API de Tag Manager, te podemos otorgar permiso para habilitar la API en uno o más proyectos de consumidores. Comunícate con el representante de tu cuenta. El proceso de inclusión en la lista blanca demorará varias semanas. Una vez que se otorgue el permiso y se habilite API, también tendrás acceso a la herramienta gcloud.

Limitaciones de la vista previa

La fase de vista previa no tendrá asistencia para IU, y no aparecerán elementos de etiquetas ni de Tag Manager en Google Cloud Console. Si creas una política de la organización con una condición y, luego, intentas acceder a esa política desde Cloud Console, recibirás un mensaje de error:

Mensaje de error de IU de la etiqueta

Para usar etiquetas durante la fase de vista previa, debes editar y administrar políticas con la herramienta de línea de comandos de gcloud.

Recomendamos probar las etiquetas en un entorno de desarrollo o etapa de pruebas, idealmente en un nodo de la organización separado de las cargas de trabajo principales.

No se crearán registros de auditoría de Cloud para las llamadas a la API Alfa de la política de la organización o la vista previa de Tag Manager. Tampoco hay objetivos de nivel de servicio para el uso de estas API.

Los proyectos y las carpetas que estén en el ID de la carpeta especificado y que lo incluyan se incorporarán a la lista blanca de la API Alfa de la política de la organización. Una vez que un recurso se incluye en la lista blanca, no se lo puede modificar con la API de V1 y, por lo tanto, no se lo puede editar con Google Cloud Console.

Hay una limitación estricta en la creación y el traslado de proyectos y carpetas dentro de la carpeta incluida en la lista blanca. Los proyectos creados o trasladados a una carpeta pueden tardar hasta dos semanas en incluirse en la lista blanca antes de que las etiquetas puedan comenzar a trabajar con ellos. Esto puede causar experiencias de usuario confusas y resultados ambiguos, por lo que es mejor no agregar ni trasladar nuevos proyectos a una carpeta incluida en la lista blanca.

Además, puede que experimentes un aumento de la latencia cuando te dirijas a los recursos incluidos en la lista blanca con los servicios de Google Cloud que reconocen las políticas de la organización. No podemos garantizar la eliminación rápida de un recurso de la lista blanca, después de lo cual se borrarán las políticas de la organización en esas carpetas.

Los administradores deberán llamar a las API de Tag Manager y de la política de la organización desde un proyecto del cliente. Cuando llamas a la API de la política de la organización o de Tag Manager, debes usar el autenticador que es propiedad de este proyecto. Luego, configura el proyecto como tu proyecto de facturación mediante la herramienta de gcloud.

Después de incluirlo en la lista blanca, el administrador podrá crear etiquetas en cualquier organización a la que tenga acceso.

La carpeta incluida en la lista blanca representa el subárbol de jerarquía que se incorporará a la lista blanca para aplicar de forma forzosa la política de la organización con etiquetas. La configuración de políticas debe hacerse en esta carpeta, y debes adjuntar etiquetas solo en el subárbol de esta carpeta.

Durante la fase de vista previa, habrá un desarrollo continuo que puede provocar cambios de API susceptibles de afectar el comportamiento, incluida la herramienta gcloud y sus mensajes de error. Por ejemplo, el campo display_name será inmutable a medida que cambiemos este campo a short_name.

Crea y define una nueva etiqueta

Las etiquetas son recursos que se componen de un par clave-valor y se crean en el nodo de la organización en tu jerarquía de recursos.

Para crear una nueva etiqueta, primero debes crear una clave con el comando gcloud alpha labelmanager keys create:

$ gcloud alpha labelmanager keys create env --label-parent="organizations/456"
displayName: env
name: labelKeys/123
parent: organizations/456
state: ACTIVE

Una vez que hayas creado la clave, tendrá un nombre visible y legible por humanos con un espacio de nombres dentro de su organización principal y un ID global único. Puedes mostrar la información relacionada con una clave determinada si usas el comando gcloud alpha labelmanager keys describe:

$ gcloud alpha labelmanager keys describe env --label-parent="organizations/456"
displayName: env
name: labelKeys/123
parent: organizations/456
state: ACTIVE

$ gcloud alpha labelmanager keys describe labelKeys/123
displayName: env

Una vez que hayas creado una clave, puedes agregar valores aceptados para la clave mediante el comando gcloud alpha labelmanager values create:

$ gcloud alpha labelmanager values create test --label-key="env" \
  --label-parent="organizations/456"
displayName: test
name: labelValues/789
parent: labelKeys/123
state: ACTIVE

$ gcloud alpha labelmanager values create prod --label-key="labelKeys/123"
displayName: prod
name: labelValues/999
parent: labelKeys/123
state: ACTIVE

Después de la creación del valor, el valor tendrá un ID global único y un nombre visible y legible por humanos dentro de su clave principal. Tanto el nombre como el ID se pueden usar para hacer referencias a fin de ayudar a elegir la etiqueta correcta durante la creación de políticas y el agregado de recursos. Puedes usar el comando gcloud alpha labelmanager values describe para mostrar la información relacionada con un valor determinado:

$ gcloud alpha labelmanager values describe test --label-key="env" \
  --label-parent="organizations/456"
displayName: test
name: labelValues/789
parent: labelKeys/123
state: ACTIVE

$ gcloud alpha labelmanager values describe labelValues/999
displayName: prod
name: labelValues/999
parent: labelKeys/123
state: ACTIVE

Se puede crear un máximo de 300 claves en una organización determinada, y puede haber un total de 300 creadas para cada clave. Los nombres visibles y legibles por humanos de la clave y el valor pueden tener una longitud máxima de 63 caracteres. El conjunto de caracteres permitido para estos nombres visibles incluye caracteres alfanuméricos en mayúsculas y minúsculas (sin internacionalización), guiones, guiones bajos y puntos. El nombre visible debe comenzar y terminar con un carácter alfanumérico.

Borra y recupera claves

Puedes borrar una clave con el comando gcloud alpha labelmanager keys delete:

$ gcloud alpha labelmanager keys delete env --label-parent="organizations/456"
displayName: env
name: labelKeys/123
parent: organizations/456
state: DELETE_REQUESTED

$ gcloud alpha labelmanager keys delete labelKeys/123
displayName: env
name: labelKeys/123
parent: organizations/456
state: DELETE_REQUESTED

Puedes recuperar una clave con el comando gcloud alpha labelmanager keys undelete:

$ gcloud alpha labelmanager keys undelete env --label-parent="organizations/456"
displayName: env
name: labelKeys/123
parent: organizations/456
state: ACTIVE

$ gcloud alpha labelmanager keys delete labelKeys/123
displayName: env
name: labelKeys/123
parent: organizations/456
state: ACTIVE

Borra y recupera valores

Puedes borrar un valor con el comando gcloud alpha labelmanager values delete:

$ gcloud alpha labelmanager values delete test --label-key="env" \
  --label-parent="organizations/456"
displayName: test
name: labelValues/789
parent: labelKeys/123
state: DELETE_REQUESTED

$ gcloud alpha labelmanager values delete labelValues/999
displayName: prod
name: labelValues/999
parent: labelKeys/123
state: DELETE_REQUESTED

Puedes recuperar un valor con el comando gcloud alpha labelmanager values undelete:

$ gcloud alpha labelmanager values undelete test --label-key="env" \
  --label-parent="organizations/456"
displayName: test
name: labelValues/789
parent: labelKeys/123
state: ACTIVE

$ gcloud alpha labelmanager values undelete labelValues/999
displayName: prod
name: labelValues/999
parent: labelKeys/123
state: ACTIVE

Administra la separación de control para las etiquetas

Los administradores obtienen una separación de control de las etiquetas mediante la restricción de quién tiene la capacidad de crear, actualizar, borrar y agregar etiquetas a los recursos.

Gestiona quién puede administrar etiquetas

Los administradores pueden seleccionar una etiqueta individual para realizar ediciones, como actualizar el nombre de la clave, los nombres de los valores, agregar o quitar valores, y actualizar la descripción.

La función Administrador de etiquetas estará disponible para permitir que tu equipo de administradores cree, actualice y borre etiquetas. La función se debe establecer en los siguientes elementos:

  • El nodo o una carpeta la organización, que permitirá la creación y edición de todas las etiquetas de la organización o la carpeta respectiva
  • El recurso de etiqueta, que permitirá la creación y la edición de todos los valores dentro de esa etiqueta
  • El recurso del valor, que solo permite actualizar y borrar ese valor individual

Los permisos individuales son los siguientes:

  • labelmanager.labelKeys.create
  • labelmanager.labelKeys.edit
  • labelmanager.labelKeys.delete
  • labelmanager.labelKeys.list
  • labelmanager.labelKeys.get
  • labelmanager.labelValues.create
  • labelmanager.labelValues.update
  • labelmanager.labelValues.delete
  • labelmanager.labelValues.list
  • labelmanager.labelValues.get

Si necesitas otorgar acceso a un auditor para ver las etiquetas, entonces otórgale la función Visualizador de etiquetas.

Administra quién puede adjuntar etiquetas a los recursos

Puedes otorgar la función roles/labelmanager.labelUser para permitir que tu equipo de administradores adjunte una etiqueta a un recurso. La función se debe establecer en los siguientes elementos:

  • El nodo o una carpeta de la organización: otorgar la función en este nivel permitirá que todos los usuarios con acceso a recursos en la organización o la carpeta adjunten la etiqueta a los recursos
  • El recurso de la etiqueta, que permitirá que el usuario adjunte esa etiqueta
  • El recurso del valor, que solo permite adjuntar ese valor individual

Los permisos individuales son los siguientes:

  • labelmanager.labelValueBindings.bind
  • labelmanager.labelValueBindings.unbind

Además, el usuario que adjunte una etiqueta a un recurso también requerirá que el recurso de destino tenga los siguientes permisos:

  • labelmanager.resourceBindings.bind
  • labelmanager.resourceBindings.unbind

Estos permisos están incluidos en las funciones básicas Propietario y Editor.

Esto permite dos casos prácticos principales. En el caso del administrador de seguridad central, otorga la función Usuario de etiquetas. Podrás adjuntar estas etiquetas a los recursos a los que tienes acceso de Propietario o Editor. Sin embargo, para obtener recursos más detallados, otorga a las etiquetas (o valores) individuales la función Usuario de etiquetas a los desarrolladores que necesitarán realizar el agregado.

Para ver qué vinculaciones están disponibles en un recurso, el usuario necesitará estos permisos:

  • labelmanager.labelValueBindings.list
  • labelmanager.resourceBindings.list

Estos permisos están incluidos en las funciones básicas Propietario y Editor.

Crea una política para usar etiquetas

Para usar una etiqueta con una política, debes crear una nueva política. Las políticas que implementan etiquetas, como la política de la organización y la de Cloud Identity and Access Management, tienen la opción de agregar una condición para esa política. Puedes hacer que la presencia o ausencia de un valor de etiqueta sea la condición para esa política.

Adjunta etiquetas a los recursos

Una vez que se crea una etiqueta y se establecen los permisos adecuados, se puede adjuntar a una organización, una carpeta o un recurso de proyecto como un par clave-valor (con los permisos adecuados en la etiqueta y el recurso). Ten en cuenta que solo se puede adjuntar un valor a un recurso para una clave determinada. Por ejemplo, si se adjunta env=dev, env=prod o env=test no se pueden adjuntar. No puedes adjuntar una etiqueta a otra. Cada recurso puede tener un máximo de 300 pares clave-valor adjuntos.

Entornos de etiquetas

Para adjuntar una etiqueta, debes crear un enlace mediante el comando gcloud alpha labelmanager bindings create:

$ gcloud alpha labelmanager bindings create labelValues/789 \
  --resource="//cloudresourcemanager.googleapis.com/projects/12345"
label_binding: labelValues/789
resource: //cloudresourcemanager.googleapis.com/projects/12345

$ gcloud alpha labelmanager bindings create prod --label-key="env" \
  --label-parent="organizations/123" \
  --resource="//cloudresourcemanager.googleapis.com/folders/78910"
label_binding: labelValues/999
resource: //cloudresourcemanager.googleapis.com/folders/78910

Cuando adjuntes la etiqueta, verás una descripción de para qué sirve, de modo que puedas tomar la mejor decisión sobre qué valor elegir.

Para borrar una vinculación de etiqueta, usa el comando gcloud alpha labelmanager bindings delete:

$ gcloud alpha labelmanager bindings delete labelValues/789 \
  --resource="//cloudresourcemanager.googleapis.com/projects/12345"

$ gcloud alpha labelmanager bindings delete test --label-key="env" \
  --label-parent="organizations/123" \
  --resource="//cloudresourcemanager.googleapis.com/folders/78910"

Para enumerar todas las vinculaciones de etiquetas de un valor determinado, usa el comando gcloud alpha labelmanager bindings list:

$ gcloud alpha labelmanager bindings list labelValues/789
Resource
//cloudresourcemanager.googleapis.com/folders/78910

$ gcloud alpha labelmanager bindings list \
--resource="//cloudresourcemanager.googleapis.com/folders/78910"
Label Value
labelValues/999

Establece la política de Cloud IAM para una clave

Si deseas establecer una política de Cloud IAM para una clave, puedes usar el comando gcloud alpha labelmanager keys add-iam-policy-binding:

$ gcloud alpha labelmanager keys add-iam-policy-binding env \
  --label-parent="organizations/456" --member=user:test@gmail.com \
  --role=roles/labelmanager.labelUser
bindings:
  - members:
    - user:test@gmail.com
      role: roles/labelmanager.labelUser
  - members:
    - user:testViewer@gmail.com
      role: roles/labelmanager.labelViewer
etag: BwWUlZ6XEfY=
version: 1

Puedes ver qué política de Cloud IAM se adjunta a una clave mediante el comando gcloud alpha labelmanager keys get-iam-policy:

$ gcloud alpha labelmanager keys get-iam-policy env --label-parent="organizations/456"
bindings:
  - members:
    - user:testViewer@gmail.com
      role: roles/labelmanager.labelViewern
etag: BwWUlZ6XEfY=
version: 1

$ gcloud alpha labelmanager keys get-iam-policy labelKeys/123
bindings:
  - members:
    - user:testViewer@gmail.com
      role: roles/labelmanager.labelViewer
etag: BwWUlZ6XEfY=
version: 1

Puedes quitar una política de Cloud IAM de una clave mediante el comando gcloud alpha labelmanager keys remove-iam-policy-binding:

$ gcloud alpha labelmanager keys remove-iam-policy-binding env \
  --label-parent="organizations/456" --member=user:test@gmail.com \
  --role=roles/labelmanager.labelUser
bindings:
  - members:
    - user:testViewer@gmail.com
      role: roles/labelmanager.labelViewer
etag: BwWUlZ6XEfY=
version: 1

Establece una política de la organización con etiquetas

Si deseas usar etiquetas para determinar en qué ubicación debe entrar en vigencia una política de la organización, debes crear una nueva política de la organización que especifique una condición. Cuando crees el archivo yaml de la política de la organización, usa el número de ID del recurso en la forma labelKeys/123 y labelValues/789, en lugar de usar el recurso displayName.

Ejemplo de política de listas

En el siguiente ejemplo, se muestra un archivo de política de la organización que aplica la restricción gcp.resourceLocations. Existe un conjunto de valores sin condiciones que se aplicarán en este recurso y sus elementos secundarios. También hay un conjunto de valores condicionados a una etiqueta en particular:

$ gcloud alpha org-policies set-policy path/to/your/config/resource_policy.yaml

resource_policy.yaml example:
{
  "name":"RESOURCE_TYPE/RESOURCE_ID/policies/gcp.resourceLocations",
  "spec":{
    "rules":[
       {
        // As there is no condition specified, this allowedValue is enforced unconditionally.
        "values":{
          "allowedValues": ["us-east1"]
        },
      },
     {
        // This condition applies to the values block.
        "condition":{
          "expression":"resource.matchLabels('labelKeys/123', 'labelValues/789')"
        },
        "values":{
          "allowedValues": ["us-west1"]
        }
      }
    ]
  }
}

Donde:

  • RESOURCE_TYPE es organizations, folders o projects.
  • RESOURCE_ID es el ID de la organización, el ID de la carpeta, el ID del proyecto o el número del proyecto.

Para la política de la organización anterior, el recurso y todos sus recursos secundarios tendrán la restricción gcp.resourceLocations aplicada, con allowedValues de us-east1 únicamente. Se aplicará la restricción gcp.resourceLocations a cualquiera de estos recursos que tengan la etiqueta (labelKeys/123, labelValues/789), con allowedValues de us-east1 y us-west1.

De esta manera, se pueden aplicar conjuntos de valores condicionales y no condicionales para una restricción en una sola política de la organización. Si no configuras conjuntos de valores condicionales, se aplica la restricción a todos los recursos, ya sea que hayan establecido una etiqueta o no.

En el siguiente ejemplo, se muestra un archivo de política de la organización que aplica la restricción gcp.resourceLocations. Hay un conjunto condicional de valores que aplica la restricción en los recursos con una etiqueta específica, pero no hay valores configurados:

$ gcloud alpha org-policies set-policy path/to/your/config/resource_policy.yaml

resource_policy.yaml example:
{
  "name":"RESOURCE_TYPE/RESOURCE_ID/policies/gcp.resourceLocations",
  "spec":{
    "rules":[
        // Because there are no unconditional values, any resource that does not
        // match the following condition is effectively set as `deny_all`.
       {
         "condition":{
            "expression":"resource.matchLabels('labelKeys/123', 'labelValues/789')"
          },
          "values":{
            "allowedValues": ["us-west1"]
          }
        }
    ]
  }
}

Donde:

  • RESOURCE_TYPE es organizations, folders o projects.
  • RESOURCE_ID es el ID de la organización, el ID de la carpeta, el ID del proyecto o el número del proyecto.

Si establecieras la política de la organización anterior en un recurso de carpeta, se heredaría a todos los recursos secundarios. Debido a que esta política de la organización incluye una condición, cualquier recurso que no tenga la etiqueta (labelKeys/123, labelValues/789) de forma explícita se considerará una infracción de la política de la organización.

Incluso si el recurso no especifica ninguna etiqueta, la política de la organización se evaluaría de manera efectiva a deny_all en ese recurso.

Ejemplo de política booleana

$ gcloud alpha org-policies set-policy path/to/your/config/resource_boolean_policy.yaml

resource_boolean_policy.yaml example:
{
   "name":"RESOURCE_TYPE/RESOURCE_ID/policies/gcp.resourceLocations",
   "spec":{
      "rules":[
         {
            "allow_all": "true",
            "condition":{
                "expression":"resource.matchLabels('labelKeys/123', 'labelValues/789')"
            }
         }
      ]
   }
}

Donde:

  • RESOURCE_TYPE es organizations, folders o projects.
  • RESOURCE_ID es el ID de la organización, el ID de la carpeta, el ID del proyecto o el número del proyecto.

Obtén la política de la organización vigente

Para ver la política de la organización vigente en un recurso de carpeta o de proyecto, haz lo siguiente:

$ gcloud alpha org-policies describe \
  --effective constraints/gcp.resourceLocations \
  --RESOURCE_FLAG="RESOURCE_NAME"

Si la condición que estableciste anteriormente coincide, deberías obtener una respuesta similar a la siguiente:

name: RESOURCE_TYPE/RESOURCE_NAME/policies/gcp.resourceLocations
spec:
 rules:
 - values:
     allowedValues:
     - us-west1
     - us-east1

Si la condición no coincide, la política lo rechazará de forma predeterminada y mostrará una respuesta similar a la siguiente:

name: RESOURCE_TYPE/RESOURCE_NAME/policies/gcp.resourceLocations
spec:
 rules:
 - denyAll: true

Donde:

  • RESOURCE_FLAG es organization, folder o project.
  • RESOURCE_TYPE es organizations, folders o projects.
  • RESOURCE_NAME es el nombre de tu carpeta o proyecto.

Si el recurso al que te orientas con el comando anterior es diferente del proyecto del cliente, también debes establecer la marca --billing-project para configurar el proyecto del cliente. Si usas --project, este proyecto se convertirá en el proyecto de tu consumidor a los fines de la llamada a la API, que es la que se debe incluir en la lista blanca a fin de permitirte usar la API.

Usa el nombre visible

Para algunas restricciones de la política de la organización, puedes usar el nombre visible de tus recursos.

Para agregar us-east1 y us-west1 a la lista de valores permitidos en la política asociada con la restricción gcp.resourceLocations y el proyecto foo-project, ejecuta lo siguiente:

$ gcloud alpha org-policies allow gcp.resourceLocations us-east1 \
  us-west1 --project=foo-project

Si deseas agregar solo valores para recursos que tengan el valor de etiqueta 2222 asociado con la clave de etiqueta 1111, ejecuta lo siguiente:

$ gcloud alpha org-policies allow gcp.resourceLocations us-east1 \
  us-west1 --project=foo-project \
  --condition='resource.matchLabels("labelKeys/1111", "labelValues/2222")'

Si deseas agregar el comportamiento de la política para el proyecto foo-project condicionado al valor de etiqueta dev en la clave de etiqueta env en la organización organizations/123, ejecuta lo siguiente:

$ gcloud alpha org-policies allow gcp.resourceLocations us-east1 \
  us-west1 --project=foo-project \
  --condition='resource.matchLabels("env", "dev")' \
  --label-parent='organizations/123'

Herencia de la política de la organización

Las restricciones de la Lista de políticas de la organización que se habilitan mediante etiquetas se fusionarán con la política de la organización existente, según las reglas de herencia normales. Estas reglas condicionales solo se aplicarán si la condición es verdadera.

Las restricciones booleanas de la política de la organización habilitadas mediante etiquetas anularán la política de la organización existente. Además, debido a que las políticas booleanas solo pueden tener dos estados, verdadero o falso, todas las declaraciones condicionales deben ser lo opuesto a la declaración sin condición para evitar que varias etiquetas entren en conflicto.

Por ejemplo, considera una política de la organización que aplique la restricción serialPortAccess. El valor incondicional, que es el valor que se usa si no hay condiciones que lo anulen, es verdadero. Por lo tanto, cualquier otra declaración condicional para esta política debe establecerse en falso a fin de no entrar en conflicto.

Borra una política de la organización

Para borrar una política de la organización de un recurso de carpeta, haz lo siguiente:

$ gcloud alpha org-policies delete constraints/gcp.resourceLocations \
  --RESOURCE_FLAG="FOLDER_NAME"

Donde:

  • RESOURCE_FLAG es organization,carpeta, orproyecto.
  • RESOURCE_NAME es el nombre de tu organización, carpeta o proyecto.