Administra las políticas para consumidores

La activación jerárquica de servicios te permite administrar la habilitación de servicios que se heredan a través de la jerarquía de recursos Google Cloud . Para obtener más información, consulta la descripción general.

El recurso ConsumerPolicy es un recurso de la API de Service Usage que se encuentra en cada nivel de la jerarquía de recursosGoogle Cloud . Este recurso, siempre llamado default, contiene el enableRules que define qué servicios están habilitados. En lugar de habilitar o inhabilitar un servicio específico, puedes modificar el recurso ConsumerPolicy. Cuando el nombre de un servicio está en su lista, el servicio está habilitado en ese nivel de jerarquía.

En este documento, se muestra cómo usar Google Cloud CLI para administrar las políticas del consumidor de proyectos, carpetas y organizaciones.

Antes de comenzar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. Si usas un proveedor de identidad externo (IdP), primero debes Acceder a la gcloud CLI con tu identidad federada.

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Si usas un proyecto existente para esta guía, verifica que tengas los permisos necesarios para completarla. Si creaste un proyecto nuevo, ya tienes los permisos necesarios.

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Service Usage API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable serviceusage.googleapis.com

  9. Install the Google Cloud CLI.

  10. Si usas un proveedor de identidad externo (IdP), primero debes Acceder a la gcloud CLI con tu identidad federada.

  11. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  12. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  13. Si usas un proyecto existente para esta guía, verifica que tengas los permisos necesarios para completarla. Si creaste un proyecto nuevo, ya tienes los permisos necesarios.

  14. Verify that billing is enabled for your Google Cloud project.

  15. Enable the Service Usage API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable serviceusage.googleapis.com

  16. Si no indicas el recurso Google Cloud que deseas administrar, los comandos de este documento se establecerán de forma predeterminada en el proyecto actual. Por ejemplo, gcloud beta services policies get --policy-name=default devuelve la política del consumidor para el proyecto actual.

    Puedes recuperar el ID del proyecto actual:

    gcloud config list --format='text(core.project)'

    17. Roles obligatorios

    Si deseas obtener los permisos que necesitas para administrar las políticas de consumidor, pídele a tu administrador que te otorgue el rol de IAM Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin) en tu recurso de destino. 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 administrar las políticas del consumidor. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

    Permisos necesarios

    Se requieren los siguientes permisos para administrar las políticas del consumidor:

    • Obtén una política de consumidor: serviceusage.consumerpolicy.get
    • Actualiza una política del consumidor:
      • serviceusage.consumerpolicy.analyze
      • serviceusage.consumerpolicy.update
    • Obtén una política vigente: serviceusage.effectivepolicy.get
    • Verifica si un servicio está habilitado: serviceusage.values.test

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

    Obtén una política de consumidor

    Puedes recuperar el ConsumerPolicy de un proyecto, una carpeta o una organización con el comando gcloud beta services policies get.

    Este comando devuelve el enableRules establecido en ese nivel de recurso exacto, y no las reglas heredadas. Para obtener una vista más completa que incluya las reglas heredadas, puedes recuperar la política efectiva. Solo se admite el nombre de política default.

    Proyecto

    gcloud beta services policies get --policy-name=default \
    --project=PROJECT_ID \
    --output-file=OUTPUT_FILE

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el Google Cloud ID del proyecto. También puedes omitir la marca para usar el proyecto actual de forma predeterminada.
    • OUTPUT_FILE: Es la ruta de acceso a un archivo de salida en el que se puede guardar el contenido de la política del consumidor (opcional). Los formatos de archivo admitidos son JSON y YAML.

    Carpeta

    gcloud beta services policies get --policy-name=default \
    --folder=FOLDER_ID \
    --output-file=OUTPUT_FILE

    Reemplaza lo siguiente:

    • FOLDER_ID: Es el Google Cloud ID de la carpeta.
    • OUTPUT_FILE: Es la ruta de acceso a un archivo de salida en el que se puede guardar el contenido de la política del consumidor (opcional). Los formatos de archivo admitidos son JSON y YAML.

    Organización

    gcloud beta services policies get --policy-name=default \
    --organization=ORGANIZATION_ID \
    --output-file=OUTPUT_FILE

    Reemplaza lo siguiente:

    • ORGANIZATION_ID: Es el Google Cloud ID del recurso de organización.
    • OUTPUT_FILE: Es la ruta de acceso a un archivo de salida en el que se puede guardar el contenido de la política del consumidor (opcional). Los formatos de archivo admitidos son JSON y YAML.

    Actualiza una política del consumidor

    Puedes actualizar un ConsumerPolicy con el comando gcloud beta services policies update. Esto te permite reemplazar la política actual y usar un archivo YAML para actualizar muchos servicios habilitados a la vez.

    Este comando no habilita automáticamente las dependencias de servicio. Debes enumerar todas las dependencias de servicio de forma explícita en el archivo de entrada. Puedes usar la marca --validate-only para obtener una vista previa de los cambios antes de aplicarlos.

    gcloud beta services policies update --consumer-policy-file=PATH_TO_CONSUMER_POLICY

    Reemplaza PATH_TO_CONSUMER_POLICY por la ruta de acceso al archivo YAML que contiene la política del consumidor, por ejemplo:

    gcloud beta services policies update --consumer-policy-file=/path/to/the/file.yaml

    Marcas compatibles:

    • --bypass-api-usage-check para omitir las verificaciones de uso De lo contrario, el sistema devolverá un error si alguno de los servicios que deseas inhabilitar se usó en los últimos 30 días o se habilitó en los últimos 3 días.

    • --bypass-dependency-check para omitir la verificación de dependencias Cuando agregues un servicio, todas las dependencias del servicio deben estar presentes en la política. Cuando quitas un servicio, ningún otro servicio de la política puede depender de él. De lo contrario, la actualización no se realizará correctamente y se mostrará un error.

    • --validate-only para validar la actualización sin realizar la operación.

    Ten en cuenta lo siguiente:

    • Para obtener una plantilla en formato YAML para el archivo de política, primero recupera la política del consumidor y usa la marca --output-file para guardar la política en un archivo. Luego, modifica este archivo y úsalo como entrada para el comando de actualización. Plantilla de ejemplo:

      name: projects/PROJECT_ID/consumerPolicies/default
enableRules:
  services:
    - services/SERVICE
    - ...
    - ...

      Reemplaza lo siguiente:

      • PROJECT_ID: Es el Google Cloud ID del proyecto. Otros nombres de recursos admitidos siguen un formato similar, por ejemplo: folders/FOLDER_ID/consumerPolicies/default.

      • SERVICE: Es el nombre del servicio, por ejemplo, bigquery.googleapis.com.

    Obtén una política vigente

    Puedes recuperar la política vigente de un recurso con el comando gcloud beta services policies get-effective.

    La política vigente combina el ConsumerPolicy del recurso con las políticas de todos sus recursos principales. Esto te brinda una vista completa de todos los servicios habilitados, incluidos los que se habilitaron directamente en el recurso y los que se heredaron de sus antecesores.

    Proyecto

    gcloud beta services policies get-effective --project=PROJECT_ID \
    --view=VIEW

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el Google Cloud ID del proyecto. También puedes omitir la marca para usar el proyecto actual de forma predeterminada.
    • VIEW: Puede ser BASIC para recuperar un conjunto limitado de metadatos o FULL para recuperar el conjunto completo de metadatos, incluido el lugar en el que se habilitó cada servicio en la jerarquía. El valor predeterminado es BASIC.

    Carpeta

    gcloud beta services policies get-effective --folder=FOLDER_ID \
    --view=VIEW

    Reemplaza lo siguiente:

    • FOLDER_ID: Es el Google Cloud ID de la carpeta.
    • VIEW: Puede ser BASIC para recuperar un conjunto limitado de metadatos o FULL para recuperar el conjunto completo de metadatos, incluido el lugar donde se habilitó cada servicio en la jerarquía. El valor predeterminado es BASIC.

    Organización

    gcloud beta services policies get-effective --organization=ORGANIZATION_ID \
    --view=VIEW

    Reemplaza lo siguiente:

    • ORGANIZATION_ID: Es el Google Cloud ID del recurso de organización.
    • VIEW: Puede ser BASIC para recuperar un conjunto limitado de metadatos o FULL para recuperar el conjunto completo de metadatos, incluido el lugar en el que se habilitó cada servicio en la jerarquía. El valor predeterminado es BASIC.

    Cómo verificar si un servicio está habilitado

    Puedes verificar si un servicio está habilitado en un recurso con el comando gcloud beta services policies test-enabled.

    Cuando se verifica el estado de un servicio, este comando considera la política efectiva y la jerarquía completa de recursos Google Cloud .

    Proyecto

    gcloud beta services policies test-enabled SERVICE \
    --project=PROJECT_ID

    Reemplaza lo siguiente:

    • SERVICE: Es el nombre del servicio que deseas verificar.
    • PROJECT_ID: Es el Google Cloud ID del proyecto. También puedes omitir la marca para usar el proyecto actual de forma predeterminada.

    Carpeta

    gcloud beta services policies test-enabled SERVICE \
    --folder=FOLDER_ID

    Reemplaza lo siguiente:

    Organización

    gcloud beta services policies test-enabled SERVICE \
    --organization=ORGANIZATION_ID

    Reemplaza lo siguiente:

    Ejemplos

    Cómo recuperar la política del consumidor

    • Recupera la política de consumidor para el proyecto actual: 
      gcloud beta services policies get

      Resultado:

      name: projects/PROJECT_ID/consumerPolicies/default
enableRules:
 services:
  - services/apikeys.googleapis.com
  - services/compute.googleapis.com
  - services/oslogin.googleapis.com
  - services/serviceusage.googleapis.com
updateTime: 2025-09-11T23:05:22.758394Z
createTime: 2025-01-31T20:17:37.272343Z
etag: W/"W9nsVJK0V1m7ee7tM7pFDg=="

    Actualización de la política del consumidor

    • Se actualizó correctamente la política del consumidor: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

      Resultado:

      Operation [operations/ucpat.p39-581601899707-86fe7e37-c7f9-4624-90c4-d54754d57eed] complete. Result: {
    "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
    "createTime":"1970-01-01T00:00:00Z",
    "enableRules":[
        {
            "services":[
                "services/apikeys.googleapis.com"
            ]
        }
    ],
    "name":"projects/PROJECT_ID/consumerPolicies/default",
    "updateTime":"1970-01-01T00:00:00Z"
}
    • No se actualizó correctamente la política del consumidor: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.json

      Mensaje de error:

      ERROR: (gcloud.beta.services.policies.update) Invalid consumer_policy_file format. Please provide path to a yaml file.
    • Intenta actualizar la política del consumidor cuando el servicio se usó o habilitó recientemente: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

      Resultado:

      The operation "operations/ucpat.p39-581601899707-4884bdb0-d899-49ac-9c83-38457950ef33" resulted in a failure "The services apikeys.googleapis.com have usage in the last 30 days or were enabled in the past 3 days. Please specify force if you want to proceed with the destructive policy change. Help Token: AVSZLmtCfGwMm4oHmOyExdDEFRQ0pFiBrl879nbZlY2JkfVzeU63u66ApXYr6MIEAoig..."
    • Actualiza la política del consumidor cuando se usó o habilitó el servicio recientemente sin omitir la verificación de uso: 
      gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml --bypass-api-usage-check

      Resultado:

      Operation [operations/ucpat.p39-581601899707-8ffda670-ed04-4776-8d43-d2f8e1817e00] complete. Result: {
    "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
    "createTime":"1970-01-01T00:00:00Z",
    "enableRules":[
        {
            "services":[
                "services/serviceusage.googleapis.com"
            ]
        }
    ],
    "name":"projects/PROJECT_ID/consumerPolicies/default",
    "updateTime":"1970-01-01T00:00:00Z"
}

    Cómo recuperar la política vigente

    • Recupera la vista BASIC de la política vigente para el proyecto actual: 
      gcloud beta services policies get-effective

      Resultado:

      EnabledRules:
 Services:
  -   services/apikeys.googleapis.com
  -   services/compute.googleapis.com
  -   services/computescanning.googleapis.com
  -   services/containeranalysis.googleapis.com
  -   services/containerscanning.googleapis.com
  -   services/gkebackup.googleapis.com
  -   services/osconfig.googleapis.com
  -   services/oslogin.googleapis.com
  -   services/serviceusage.googleapis.com
    • Recupera la vista FULL de la política vigente para el proyecto actual: 
      gcloud beta services policies get-effective --view=FULL

      Resultado:

      EnabledRules:
 Services:
  -   services/apikeys.googleapis.com
  -   services/compute.googleapis.com
  -   services/computescanning.googleapis.com
  -   services/containeranalysis.googleapis.com
  -   services/containerscanning.googleapis.com
  -   services/gkebackup.googleapis.com
  -   services/osconfig.googleapis.com
  -   services/oslogin.googleapis.com
  -   services/serviceusage.googleapis.com

Metadata of effective policy:
EnabledService: services/apikeys.googleapis.com
EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']

EnabledService: services/bcidcloudenforcer-pa.googleapis.com
EnabledPolicies: ['folders/FOLDER_ID/consumerPolicies/default']

EnabledService: services/compute.googleapis.com
EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']
...

    Cómo verificar si un servicio está habilitado

    • Verifica el estado del servicio de claves de API habilitadas para el proyecto actual: 
      gcloud beta services policies test-enabled apikeys.googleapis.com

      Resultado:

      Service apikeys.googleapis.com is ENABLED for resource projects/test-project Hierarchical Service Activation.
    • Verifica el estado del servicio de App Hub inhabilitado para el proyecto actual: 
      gcloud beta services policies test-enabled apphub.googleapis.com

      Resultado:

      Service apphub.googleapis.com is NOT ENABLED for resource projects/test-project Hierarchical Service Activation.

    ¿Qué sigue?