Instala extensiones de VM creando políticas de extensiones

En este documento, se describe cómo crear políticas de extensiones de VM, que te permiten instalar y administrar extensiones de forma automática en una flota de máquinas virtuales (VMs) de Compute Engine. Si defines una política, puedes asegurarte de que se instalen y mantengan extensiones específicas en cualquier VM que cumpla con los criterios que especifiques, como las etiquetas de VM. Puedes crear políticas de extensión de VM zonales o globales a nivel del proyecto, o a nivel de la organización y la carpeta (disponible en versión preliminar).

Antes de comenzar

Limitaciones de la creación de políticas

Solo puedes crear políticas de extensión de VM con alcance de carpeta y de organización con Google Cloud CLI o la API de REST de Compute Engine.

Prioridad de las políticas y resolución de conflictos

Cuando se aplican varias políticas en diferentes niveles de jerarquía (organización, carpeta o proyecto) a la misma VM, el nivel de jerarquía no determina la prioridad. En su lugar, el Gestor de extensiones de VM usa la prioridad de la política y las marcas de tiempo de actualización para resolver conflictos.

Cuando dos políticas entran en conflicto para la misma extensión, la política con la prioridad más alta tiene prioridad. Los valores de prioridad varían de 0 a 65535, en los que un número más bajo indica una prioridad más alta. La prioridad predeterminada es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs. Borrar una política no quita la extensión si aún se aplica a la VM una política de menor prioridad.

Instala extensiones de VM creando una política global de extensiones de VM

Puedes crear una política global de extensiones de VM para instalar extensiones en VMs en varias zonas según un plan de lanzamiento. Puedes definir una política global a nivel del proyecto, o a nivel de la carpeta o de la organización (disponible en versión preliminar).

El Gestor de extensiones de VM no aplica una política de extensión de VM global directamente a las VMs. En cambio, a medida que se lanza la política, el Gestor de extensiones de VM replica automáticamente la definición global en las políticas zonales correspondientes en cada zona según el plan de lanzamiento. Después de que una política replicada esté disponible en una zona, el Gestor de extensiones de VM evalúa las VMs de esa zona en función de las etiquetas de inclusión de la política y, luego, instala o actualiza las extensiones designadas. Cuando creas VMs nuevas, el Gestor de extensiones de VM las evalúa y configura automáticamente.

Planes de lanzamiento para las políticas globales

Las políticas de extensión de VM globales usan planes de lanzamiento para administrar la implementación de extensiones en diferentes ubicaciones. Puedes usar uno de los planes de lanzamiento predefinidos o crear uno personalizado.

Planes de lanzamiento predefinidos

Puedes seleccionar uno de los siguientes planes de lanzamiento predefinidos:

  • slow_rollout: implementa la política en un plazo de cinco días. El lanzamiento lento es el plan de lanzamiento predeterminado.
  • fast_rollout: implementa la política de inmediato en todas las zonas.

Planes de lanzamiento personalizados

Puedes crear planes de lanzamiento personalizados con el método rolloutPlans.insert. Por ejemplo, el siguiente JSON define un plan de lanzamiento llamado test-rollout-plan que se orienta a dos zonas:

{
  "name": "test-rollout-plan",
  "waves": [
    {
      "selectors": [
        {
          "locationSelector": {
            "includedLocations": [
              "us-central1-a",
              "us-west1-a"
            ]
          }
        }
      ],
      "validation": {
        "type": "time",
        "timeBasedValidationMetadata": {
          "waitDuration": "0s"
        }
      },
      "orchestrationOptions": {
        "maxConcurrentResourcesPerLocation": "10",
        "maxConcurrentLocations": "10"
      }
    }
  ]
}

Luego, puedes usar este plan de lanzamiento personalizado cuando crees una política global.

Instala extensiones de VM en todas las zonas de una organización

Crea una política de extensión global con alcance de organización para instalar y mantener extensiones de VM en todas las zonas de todos los proyectos descendientes de tu organización.

Permisos de IAM obligatorios

Para obtener el permiso que necesitas para crear una política de extensión con alcance de organización, pídele a tu administrador que te otorgue el rol de IAM de Administrador de políticas de extensión de VM de Compute a nivel de la organización (roles/compute.orgVmExtensionPolicyAdmin) en tu organización. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso compute.orgVmExtensionPolicies.create, que se requiere para crear una política de extensión con alcance de organización.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Para crear una política de extensión global con permiso de organización, selecciona una de las siguientes opciones:

gcloud

Para crear una política de extensión de VM global centrada en la organización, usa el comando gcloud preview compute global-vm-extension-policies create con la marca --organization:

gcloud preview compute global-vm-extension-policies create POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

Reemplaza lo siguiente:

  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • ORGANIZATION_ID: Es el ID de organización para la política con alcance de organización. El formato del recurso es organizations/{organization}/global/vmExtensionPolicies/{name}.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: Es una lista separada por comas de las extensiones que se agregarán a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la ruta de acceso al archivo de configuración de esa extensión. Este archivo se encuentra en la VM en la que ejecutas el comando gcloud, no en la VM en la que instalas la extensión.

    Como alternativa, para proporcionar la configuración como una cadena intercalada, usa la marca --config en lugar de --config-from-file, por ejemplo, EXTENSION_NAME_1="CONFIG_1". Puedes usar --config-from-file o --config, pero no ambos en el mismo comando.

  • KEY_1=VALUE_1: Es una lista separada por comas de pares clave-valor que definen etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas --inclusion-labels varias veces, la política se orienta a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites esta marca, la política se aplica a todas las VMs de todos los proyectos y zonas subordinados de la organización.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.
  • ROLLOUT_PLAN: Especifica slow_rollout o fast_rollout. Si necesitas usar un plan de lanzamiento personalizado, especifica la marca --rollout-custom-plan en lugar de --rollout-predefined-plan con el siguiente formato:
    --rollout-custom-plan=organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Reemplaza lo siguiente:

    • ORGANIZATION_ID: Es la organización en la que se define el plan de lanzamiento.
    • ROLLOUT_PLAN_NAME: Es el nombre del plan de lanzamiento personalizado que definiste.

    Si no especificas una marca de plan de lanzamiento, el Gestor de extensiones de VM usa slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando el Gestor de extensiones de VM detecta un conflicto entre una política de zona y una global. Puedes especificar uno de los siguientes comportamientos de conflicto:
    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto que tienen el mismo nombre. Este comportamiento de conflicto es el predeterminado.
    • overwrite: La política global reemplaza cualquier política zonal que tenga el mismo nombre y, luego, la política global administra los lanzamientos de políticas en la zona.

    Para obtener más información, consulta la marca --rollout-conflict-behavior.

Ejemplo: Crea una política global con alcance de organización

Con el siguiente comando, se crea una política global de alta prioridad llamada prod-frontend-policy a nivel de la organización (organizations/123456789) para las cargas de trabajo de frontend de producción (env=prod,workload=frontend), lo que fija una versión específica para la extensión ops-agent con un plan de lanzamiento lento:

gcloud preview compute global-vm-extension-policies create prod-frontend-policy \
  --organization=organizations/123456789 \
  --description="Standard monitoring policy for production frontend VMs" \
  --extensions=ops-agent \
  --version=ops-agent=2.58.0 \
  --config=ops-agent="some-monitoring-config" \
  --inclusion-labels="env=prod,workload=frontend" \
  --priority=100 \
  --rollout-predefined-plan=slow_rollout

REST

Para crear una política de extensión de VM global con alcance de organización, envía una solicitud POST al método organizationGlobalVmExtensionPolicies.insert:

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/global/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "organizations/ORGANIZATION_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Reemplaza lo siguiente:

  • ORGANIZATION_ID: Es el ID de tu organización.
  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: Es el nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: Es la configuración de la extensión, proporcionada como una cadena intercalada.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • KEY_1: VALUE_1: Es un par clave-valor que define las etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites instanceSelectors, la política se aplica a todas las VMs de todos los proyectos y zonas subordinados de la organización.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.
  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando el Gestor de extensiones de VM detecta un conflicto entre una política de zona y una global. Puedes especificar uno de los siguientes comportamientos de conflicto:
    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto que tienen el mismo nombre. Este comportamiento de conflicto es el predeterminado.
    • overwrite: La política global reemplaza cualquier política zonal que tenga el mismo nombre y, luego, la política global administra los lanzamientos de políticas en la zona.

    Para obtener más información, consulta la marca --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME: Es el nombre del plan de lanzamiento personalizado que definiste. Para usar un plan de lanzamiento predefinido, reemplaza el campo name por predefinedRolloutPlan y especifica uno de los siguientes valores:
    • SLOW_ROLLOUT: implementa la política en un plazo de cinco días. Este plan predefinido es el plan de lanzamiento predeterminado si no especificas uno.
    • FAST_ROLLOUT: implementa la política de inmediato en todas las zonas.

Ejemplo: Crea una política global con alcance de organización

En el siguiente ejemplo, se crea una política global llamada org-global-extension-policy que instala la extensión ops-agent para la organización 123456789 en las VMs con la etiqueta env=prod, con prioridad 100 y un plan de lanzamiento predefinido SLOW_ROLLOUT:

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/123456789/global/vmExtensionPolicies

{
"name": "org-global-extension-policy",
"description": "Standard monitoring policy for organization VMs",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "100",
"rolloutOperation": {
  "rolloutInput": {
    "predefinedRolloutPlan": "SLOW_ROLLOUT"
  }
}
}

Instala extensiones de VM en todas las zonas de una carpeta

Crea una política de extensión global con alcance de carpeta para instalar y mantener extensiones de VM en todas las zonas de todos los proyectos descendientes de tu carpeta.

Permisos de IAM obligatorios

Para obtener el permiso que necesitas para crear una política de extensión con alcance de carpeta, pídele a tu administrador que te otorgue el rol de IAM de Administrador de políticas de extensión de VM de Compute a nivel de carpeta (roles/compute.folderVmExtensionPolicyAdmin) en tu carpeta. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso compute.folderVmExtensionPolicies.create, que se requiere para crear una política de extensión con alcance de carpeta.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Para crear una política de extensión global con alcance de carpeta, selecciona una de las siguientes opciones:

gcloud

Para crear una política de extensión de VM global con alcance de carpeta, usa el comando gcloud preview compute global-vm-extension-policies create con la marca --folder:

gcloud preview compute global-vm-extension-policies create POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

Reemplaza lo siguiente:

  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • FOLDER_ID: Es el ID de la carpeta para la política con alcance de carpeta. El formato del recurso es folders/{folder}/global/vmExtensionPolicies/{name}.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: Es una lista separada por comas de las extensiones que se agregarán a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la ruta de acceso al archivo de configuración de esa extensión. Este archivo se encuentra en la VM en la que ejecutas el comando gcloud, no en la VM en la que instalas la extensión.

    Como alternativa, para proporcionar la configuración como una cadena intercalada, usa la marca --config en lugar de --config-from-file, por ejemplo, EXTENSION_NAME_1="CONFIG_1". Puedes usar --config-from-file o --config, pero no ambos en el mismo comando.

  • KEY_1=VALUE_1: Es una lista separada por comas de pares clave-valor que definen etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas --inclusion-labels varias veces, la política se orienta a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites esta marca, la política se aplica a todas las VMs de todos los proyectos y zonas descendientes dentro de la carpeta.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.
  • ROLLOUT_PLAN: Especifica slow_rollout o fast_rollout. Si necesitas usar un plan de lanzamiento personalizado, especifica la marca --rollout-custom-plan en lugar de --rollout-predefined-plan con el siguiente formato:
    --rollout-custom-plan=folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Reemplaza lo siguiente:

    • FOLDER_ID: Es la carpeta en la que se define el plan de lanzamiento.
    • ROLLOUT_PLAN_NAME: Es el nombre del plan de lanzamiento personalizado que definiste.

    Si no especificas una marca de plan de lanzamiento, el Gestor de extensiones de VM usa slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando el Gestor de extensiones de VM detecta un conflicto entre una política de zona y una global. Puedes especificar uno de los siguientes comportamientos de conflicto:
    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto que tienen el mismo nombre. Este comportamiento de conflicto es el predeterminado.
    • overwrite: La política global reemplaza cualquier política zonal que tenga el mismo nombre y, luego, la política global administra los lanzamientos de políticas en la zona.

    Para obtener más información, consulta la marca --rollout-conflict-behavior.

Ejemplo: Crea una política global con alcance de carpeta

Con el siguiente comando, se crea una política global llamada folder-global-extension-policy a nivel de la carpeta (folders/123456) que instala la extensión ops-agent en las VMs con la etiqueta env=prod con un plan de lanzamiento lento:

gcloud preview compute global-vm-extension-policies create folder-global-extension-policy \
  --folder=folders/123456 \
  --description="Standard monitoring policy for folder VMs" \
  --extensions=ops-agent \
  --version=ops-agent=2.58.0 \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --inclusion-labels="env=prod" \
  --priority=100 \
  --rollout-predefined-plan=slow_rollout

REST

Para crear una política de extensión de VM global con alcance de carpeta, envía una solicitud POST al método folderGlobalVmExtensionPolicies.insert:

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/global/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "folders/FOLDER_ID/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Reemplaza lo siguiente:

  • FOLDER_ID: Es el ID de tu carpeta.
  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: Es el nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: Es la configuración de la extensión, proporcionada como una cadena intercalada.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • KEY_1: VALUE_1: Es un par clave-valor que define las etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites instanceSelectors, la política se aplica a todas las VMs de todos los proyectos y zonas descendientes dentro de la carpeta.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.
  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando el Gestor de extensiones de VM detecta un conflicto entre una política de zona y una global. Puedes especificar uno de los siguientes comportamientos de conflicto:
    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto que tienen el mismo nombre. Este comportamiento de conflicto es el predeterminado.
    • overwrite: La política global reemplaza cualquier política zonal que tenga el mismo nombre y, luego, la política global administra los lanzamientos de políticas en la zona.

    Para obtener más información, consulta la marca --rollout-conflict-behavior.

  • ROLLOUT_PLAN_NAME: Es el nombre del plan de lanzamiento personalizado que definiste. Para usar un plan de lanzamiento predefinido, reemplaza el campo name por predefinedRolloutPlan y especifica uno de los siguientes valores:
    • SLOW_ROLLOUT: implementa la política en un plazo de cinco días. Este plan predefinido es el plan de lanzamiento predeterminado si no especificas uno.
    • FAST_ROLLOUT: implementa la política de inmediato en todas las zonas.

Ejemplo: Crea una política global con alcance de carpeta

En el siguiente ejemplo, se crea una política global llamada folder-global-extension-policy que instala la extensión ops-agent para la carpeta 123456 en las VMs con la etiqueta env=prod, con la prioridad 500 y un plan de lanzamiento predefinido SLOW_ROLLOUT:

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/123456/global/vmExtensionPolicies

{
"name": "folder-global-extension-policy",
"description": "Test extension policy for Ops Agent at folder level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "500",
"rolloutOperation": {
  "rolloutInput": {
    "predefinedRolloutPlan": "SLOW_ROLLOUT"
  }
}
}

Instala extensiones de VM en todas las zonas de un proyecto

Crea una política de extensiones global con alcance de proyecto para instalar y mantener extensiones de VM en todas las zonas de tu proyecto.

Permisos de IAM obligatorios

Para obtener el permiso que necesitas para crear una política de extensión con alcance de proyecto, pídele a tu administrador que te otorgue el rol de IAM de Administrador de políticas de extensión de VM de Compute (roles/compute.vmExtensionPolicyAdmin) 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 el permiso compute.vmExtensionPolicies.create, que se requiere para crear una política de extensión con alcance de proyecto.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Para crear una política de extensión global con alcance de proyecto, selecciona una de las siguientes opciones:

Console

Para crear una política de extensión de VM global con alcance de proyecto en la consola de Google Cloud , completa los siguientes pasos:

  1. En la consola de Google Cloud , ve a la página Políticas de extensiones de VM.

    Ir a Políticas de extensión de VM

  2. Haz clic en Crear política de extensión.
  3. En el campo Nombre, ingresa un nombre para la política.
  4. Opcional: En el campo Descripción, ingresa una descripción para la política.
  5. En el campo Prioridad, especifica un número de prioridad para resolver conflictos entre políticas. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000.
  6. En la sección Alcance, selecciona Lanzamiento global.
  7. En la sección Administrar extensiones, haz clic en Agregar extensión y haz lo siguiente para cada extensión que quieras instalar en las VMs de destino:
    1. En la lista Extensión, selecciona una extensión. Para obtener más información, consulta Extensiones compatibles.
    2. En la lista Versión, especifica el número de versión de la extensión. Deja este campo en blanco para seleccionar la versión más reciente.
      • Para el Agente de operaciones, puedes especificar la versión 2.58.0 o una posterior.
      • En el caso de Extension for SAP y Extension for Compute Workloads, deja el campo en blanco para seleccionar la versión más reciente.
    3. Opcional: En el campo Contenido del archivo de configuración, ingresa los parámetros de configuración de la extensión.
  8. En el campo Plan de lanzamiento, selecciona un plan de lanzamiento de las siguientes opciones:
    • Lanzamiento lento: Instala extensiones de forma gradual en tu flota de VMs durante un período. Este plan de lanzamiento es la opción predeterminada.
    • Lanzamiento rápido: Instala extensiones en todas las VMs de destino en todas las zonas y regiones de inmediato.

    Para obtener más información sobre los planes de lanzamiento, consulta Planes de lanzamiento.

  9. En la sección Instancias de VM de destino, selecciona las VMs para la política. Para seleccionar VMs con etiquetas específicas, haz clic en Agregar etiquetas y agrega el par clave-valor.
  10. Haz clic en Crear.

gcloud

Para crear una política de extensión de VM global con alcance de proyecto, usa el comando gcloud compute global-vm-extension-policies create:

gcloud compute global-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

Reemplaza lo siguiente:

  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • PROJECT_ID: Es el ID del proyecto para la política con alcance de proyecto.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: Es una lista separada por comas de las extensiones que se agregarán a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la ruta de acceso al archivo de configuración de esa extensión. Este archivo se encuentra en la VM en la que ejecutas el comando gcloud, no en la VM en la que instalas la extensión.

    Como alternativa, para proporcionar la configuración como una cadena intercalada, usa la marca --config en lugar de --config-from-file, por ejemplo, EXTENSION_NAME_1="CONFIG_1". Puedes usar --config-from-file o --config, pero no ambos en el mismo comando.

  • KEY_1=VALUE_1: Es una lista separada por comas de pares clave-valor que definen etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas --inclusion-labels varias veces, la política se orienta a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites esta marca, la política se aplica a todas las VMs de tu proyecto en todas las zonas.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.
  • ROLLOUT_PLAN: Especifica slow_rollout o fast_rollout. Si necesitas usar un plan de lanzamiento personalizado, especifica la marca --rollout-custom-plan en lugar de --rollout-predefined-plan con el siguiente formato:
    --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME

    Reemplaza lo siguiente:

    • PROJECT_NUMBER: Es el proyecto en el que se define el plan de lanzamiento.
    • ROLLOUT_PLAN_NAME: Es el nombre del plan de lanzamiento personalizado que definiste.

    Si no especificas una marca de plan de lanzamiento, el Gestor de extensiones de VM usa slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando el Gestor de extensiones de VM detecta un conflicto entre una política de zona y una global. Puedes especificar uno de los siguientes comportamientos de conflicto:
    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto que tienen el mismo nombre. Este comportamiento de conflicto es el predeterminado.
    • overwrite: La política global reemplaza cualquier política zonal que tenga el mismo nombre y, luego, la política global administra los lanzamientos de políticas en la zona.

    Para obtener más información, consulta la marca --rollout-conflict-behavior.

Ejemplo: Crea una política global con alcance de proyecto

Con el siguiente comando, se crea una política llamada global-test-extension-policy que instala la extensión ops-agent para el proyecto test-project. La marca --config-from-file especifica la ruta de acceso a un archivo local que contiene una configuración de YAML para el Agente de operaciones, y --rollout-predefined-plan especifica el plan de slow_rollout.

gcloud compute global-vm-extension-policies create global-test-extension-policy \
  --project=test-project \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --rollout-predefined-plan=slow_rollout

Ejemplo: Crea una política global con alcance de proyecto con un plan de lanzamiento personalizado

Con el siguiente comando, se crea una política llamada global-test-extension-policy-2 que instala la extensión ops-agent para el proyecto test-project en las VMs con la etiqueta env=prod. La prioridad de la política se establece en 500, y la marca --config-from-file especifica la ruta de acceso a un archivo local que contiene una configuración de YAML para el Agente de operaciones. La marca --rollout-custom-plan especifica un plan de lanzamiento personalizado.

gcloud compute global-vm-extension-policies create global-test-extension-policy-2 \
  --project=test-project \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod \
  --rollout-custom-plan=projects/12345678/locations/global/rolloutPlans/test-rollout-plan

REST

Para crear una política de extensión de VM global con alcance de proyecto, envía una solicitud POST al método globalVmExtensionPolicies.insert.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY",
"rolloutOperation": {
  "rolloutInput": {
    "conflictBehavior": "ROLLOUT_CONFLICT_BEHAVIOR",
    "name": "projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME"
  }
}
}

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: Es el nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: Es la configuración de la extensión, proporcionada como una cadena intercalada.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • KEY_1: VALUE_1: Es un par clave-valor que define las etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites instanceSelectors, la política se aplica a todas las VMs de tu proyecto en todas las zonas.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.
  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando el Gestor de extensiones de VM detecta un conflicto entre una política de zona y una global. Puedes especificar uno de los siguientes comportamientos de conflicto:
    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto que tienen el mismo nombre. Este comportamiento de conflicto es el predeterminado.
    • overwrite: La política global reemplaza cualquier política zonal que tenga el mismo nombre y, luego, la política global administra los lanzamientos de políticas en la zona.

    Para obtener más información, consulta la marca --rollout-conflict-behavior.

  • PROJECT_NUMBER: Es el proyecto en el que se define el plan de lanzamiento personalizado.
  • ROLLOUT_PLAN_NAME: Es el nombre del plan de lanzamiento personalizado que definiste. Para usar un plan de lanzamiento predefinido, reemplaza el campo name por predefinedRolloutPlan y especifica uno de los siguientes valores:
    • SLOW_ROLLOUT: implementa la política en un plazo de cinco días. Este plan predefinido es el plan de lanzamiento predeterminado si no especificas uno.
    • FAST_ROLLOUT: implementa la política de inmediato en todas las zonas.

Ejemplo: Crea una política global con alcance de proyecto

En el siguiente ejemplo, se crea una política llamada global-test-extension-policy que instala la extensión ops-agent para el proyecto 12345678 en las VMs con la etiqueta env=prod. La prioridad de la política se establece en 500 y usa el plan de lanzamiento test-rollout-plan.

POST https://compute.googleapis.com/compute/v1/projects/12345678/global/vmExtensionPolicies

{
"name": "global-test-extension-policy",
"description": "Test extension policy for Ops Agent",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "500",
"rolloutOperation": {
  "rolloutInput": {
    "name": "projects/12345678/locations/global/rolloutPlans/test-rollout-plan"
  }
}
}

Instala extensiones de VM creando una política de extensión de VM zonal

Puedes crear una política de extensiones de VM zonales para definir qué extensiones instalar y en qué VMs de una zona específica. Puedes definir una política zonal a nivel del proyecto, o a nivel de la carpeta o de la organización (disponible en versión preliminar).

Instala extensiones de VM en una zona de una organización

Crea una política de extensiones zonales con alcance de organización para instalar y mantener extensiones de VM en una zona específica en todos los proyectos descendientes de tu organización.

Permisos de IAM obligatorios

Para obtener el permiso que necesitas para crear una política de extensión con alcance de organización, pídele a tu administrador que te otorgue el rol de IAM de Administrador de políticas de extensión de VM de Compute a nivel de la organización (roles/compute.orgVmExtensionPolicyAdmin) en tu organización. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso compute.orgVmExtensionPolicies.create, que se requiere para crear una política de extensión con alcance de organización.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Para crear una política de extensión zonal con alcance de organización, selecciona una de las siguientes opciones:

gcloud

Para crear una política de extensiones de VM zonal con alcance de organización y, luego, implementarla en las VMs de una zona específica, usa el comando gcloud preview compute zone-vm-extension-policies create con la marca --organization:

gcloud preview compute zone-vm-extension-policies create POLICY_NAME \
  --organization=organizations/ORGANIZATION_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Reemplaza lo siguiente:

  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • ORGANIZATION_ID: Es el ID de organización para la política con alcance de organización. El formato del recurso es organizations/{organization}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE: Es la zona en la que se aplica esta política.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: Es una lista separada por comas de las extensiones que se agregarán a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la ruta de acceso al archivo de configuración de esa extensión. Este archivo se encuentra en la VM en la que ejecutas el comando gcloud, no en la VM en la que instalas la extensión.

    Como alternativa, para proporcionar la configuración como una cadena intercalada, usa la marca --config en lugar de --config-from-file, por ejemplo, EXTENSION_NAME_1="CONFIG_1". Puedes usar --config-from-file o --config, pero no ambos en el mismo comando.

  • KEY_1=VALUE_1: Es una lista separada por comas de pares clave-valor que definen etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas --inclusion-labels varias veces, la política se orienta a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites esta marca, la política se aplica a todas las VMs de la zona especificada en todos los proyectos descendientes de la organización.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.

El comando falla si ya existe una política con el nombre especificado en la zona.

Ejemplo: Crea una política zonal con alcance de organización

Con el siguiente comando, se crea una política zonal llamada org-test-extension-policy que instala la extensión ops-agent en la zona us-central1-f para la organización organizations/123456789 en las VMs con la etiqueta env=prod:

gcloud preview compute zone-vm-extension-policies create org-test-extension-policy \
  --organization=organizations/123456789 \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=100 \
  --inclusion-labels=env=prod

REST

Para crear una política de extensión de VM zonal con alcance de organización, envía una solicitud POST al método organizationZoneVmExtensionPolicies.insert. Este método define qué extensiones instalar y en qué VMs de una zona específica de la organización.

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/ORGANIZATION_ID/zones/ZONE/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Reemplaza lo siguiente:

  • ORGANIZATION_ID: Es el ID de tu organización.
  • ZONE: Es la zona en la que se aplica esta política.
  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: Es el nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: Es la configuración de la extensión, proporcionada como una cadena intercalada.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • KEY_1: VALUE_1: Es un par clave-valor que define las etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites instanceSelectors, la política se aplica a todas las VMs de la zona especificada en todos los proyectos descendientes de la organización.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.

Ejemplo: Crea una política zonal con alcance de organización

En el siguiente ejemplo, se crea una política llamada org-test-extension-policy que instala la extensión ops-agent en la zona us-central1-f para la organización 123456789.

POST https://compute.googleapis.com/compute/2026-10-01-preview/organizations/123456789/zones/us-central1-f/vmExtensionPolicies

{
"name": "org-test-extension-policy",
"description": "Test extension policy for Ops Agent at organization level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "prod"
       }
    }
  }
],
"priority": "100"
}

Instala extensiones de VM en una zona en una carpeta

Crea una política de extensiones zonales con alcance de carpeta para instalar y mantener extensiones de VM en una zona específica en todos los proyectos secundarios de tu carpeta.

Permisos de IAM obligatorios

Para obtener el permiso que necesitas para crear una política de extensión con alcance de carpeta, pídele a tu administrador que te otorgue el rol de IAM de Administrador de políticas de extensión de VM de Compute a nivel de carpeta (roles/compute.folderVmExtensionPolicyAdmin) en tu carpeta. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso compute.folderVmExtensionPolicies.create, que se requiere para crear una política de extensión con alcance de carpeta.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Para crear una política de extensión zonal con alcance de carpeta, selecciona una de las siguientes opciones:

gcloud

Para crear una política de extensiones de VM zonal con alcance de carpeta y, luego, implementarla en las VMs de una zona específica, usa el comando gcloud preview compute zone-vm-extension-policies create con la marca --folder:

gcloud preview compute zone-vm-extension-policies create POLICY_NAME \
  --folder=folders/FOLDER_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Reemplaza lo siguiente:

  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • FOLDER_ID: Es el ID de la carpeta para la política con alcance de carpeta. El formato del recurso es folders/{folder}/zones/{zone}/vmExtensionPolicies/{name}.
  • ZONE: Es la zona en la que se aplica esta política.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: Es una lista separada por comas de las extensiones que se agregarán a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la ruta de acceso al archivo de configuración de esa extensión. Este archivo se encuentra en la VM en la que ejecutas el comando gcloud, no en la VM en la que instalas la extensión.

    Como alternativa, para proporcionar la configuración como una cadena intercalada, usa la marca --config en lugar de --config-from-file, por ejemplo, EXTENSION_NAME_1="CONFIG_1". Puedes usar --config-from-file o --config, pero no ambos en el mismo comando.

  • KEY_1=VALUE_1: Es una lista separada por comas de pares clave-valor que definen etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas --inclusion-labels varias veces, la política se orienta a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites esta marca, la política se aplica a todas las VMs de la zona especificada en todos los proyectos descendientes de la carpeta.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.

El comando falla si ya existe una política con el nombre especificado en la zona.

Ejemplo: Crea una política zonal con alcance de carpeta

Con el siguiente comando, se crea una política zonal llamada folder-test-extension-policy que instala la extensión ops-agent en la zona us-central1-f para la carpeta folders/123456 en las VMs con la etiqueta env=prod:

gcloud preview compute zone-vm-extension-policies create folder-test-extension-policy \
  --folder=folders/123456 \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod

REST

Para crear una política de extensión de VM zonal con alcance de carpeta, envía una solicitud POST al método folderZoneVmExtensionPolicies.insert. Este método define qué extensiones instalar y en qué VMs de una zona específica de la carpeta.

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/FOLDER_ID/zones/ZONE/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Reemplaza lo siguiente:

  • FOLDER_ID: Es el ID de tu carpeta.
  • ZONE: Es la zona en la que se aplica esta política.
  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: Es el nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: Es la configuración de la extensión, proporcionada como una cadena intercalada.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • KEY_1: VALUE_1: Es un par clave-valor que define las etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites instanceSelectors, la política se aplica a todas las VMs de la zona especificada en todos los proyectos descendientes de la carpeta.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.

Ejemplo: Crea una política zonal con alcance de carpeta

En el siguiente ejemplo, se crea una política llamada folder-test-extension-policy que instala la extensión ops-agent en la zona us-central1-f para la carpeta 123456.

POST https://compute.googleapis.com/compute/2026-10-01-preview/folders/123456/zones/us-central1-f/vmExtensionPolicies

{
"name": "folder-test-extension-policy",
"description": "Test extension policy for Ops Agent at folder level",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "test"
       }
    }
  }
],
"priority": "500"
}

Instala extensiones de VM en una zona de un proyecto

Crea una política de extensiones zonales con alcance de proyecto para instalar y mantener extensiones de VM en una zona específica de tu proyecto.

Permisos de IAM obligatorios

Para obtener el permiso que necesitas para crear una política de extensión con alcance de proyecto, pídele a tu administrador que te otorgue el rol de IAM de Administrador de políticas de extensión de VM de Compute (roles/compute.vmExtensionPolicyAdmin) 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 el permiso compute.vmExtensionPolicies.create, que se requiere para crear una política de extensión con alcance de proyecto.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Para crear una política de extensión zonal con alcance de proyecto, selecciona una de las siguientes opciones:

Console

Para crear una política de extensión de VM zonal con alcance de proyecto en la consola de Google Cloud , completa los siguientes pasos:

  1. En la consola de Google Cloud , ve a la página Políticas de extensiones de VM.

    Ir a Políticas de extensión de VM

  2. Haz clic en Crear política de extensión.
  3. En el campo Nombre, ingresa un nombre para la política.
  4. Opcional: En el campo Descripción, ingresa una descripción para la política.
  5. En el campo Prioridad, especifica un número de prioridad para resolver conflictos entre políticas. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000.
  6. En la sección Alcance, selecciona Lanzamiento zonal.
  7. En las listas Región y Zona, selecciona la región y la zona en las que se encuentran tus VMs. El Gestor de extensiones de VM aplica la política a las VMs de la región y la zona seleccionadas.
  8. En la sección Administrar extensiones, haz clic en Agregar extensión y haz lo siguiente para cada extensión que quieras instalar en las VMs de destino:
    1. En la lista Extensión, selecciona una extensión. Para obtener más información, consulta Extensiones compatibles.
    2. En la lista Versión, especifica el número de versión de la extensión. Deja este campo en blanco para seleccionar la versión más reciente.
      • Para el Agente de operaciones, puedes especificar la versión 2.58.0 o una posterior.
      • En el caso de Extension for SAP y Extension for Compute Workloads, deja el campo en blanco para seleccionar la versión más reciente.
    3. Opcional: En el campo Contenido del archivo de configuración, ingresa los parámetros de configuración de la extensión.
  9. En la sección Instancias de VM de destino, selecciona las VMs para la política. Para seleccionar VMs con etiquetas específicas, haz clic en Agregar etiquetas y agrega el par clave-valor.
  10. Haz clic en Crear.

gcloud

Para crear una política de extensiones de VM zonal con alcance de proyecto y, luego, implementarla en las VMs de una zona específica, usa el comando gcloud compute zone-vm-extension-policies create:

gcloud compute zone-vm-extension-policies create POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE \
  --description="DESCRIPTION" \
  --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
  --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
  --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
  --inclusion-labels=KEY_1=VALUE_1 \
  --priority=PRIORITY

Reemplaza lo siguiente:

  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • PROJECT_ID: Es el ID del proyecto para la política con alcance de proyecto.
  • ZONE: Es la zona en la que se aplica esta política.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1,EXTENSION_NAME_2: Es una lista separada por comas de las extensiones que se agregarán a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2: Es una lista separada por comas de pares clave-valor en la que la clave es el nombre de la extensión y el valor es la ruta de acceso al archivo de configuración de esa extensión. Este archivo se encuentra en la VM en la que ejecutas el comando gcloud, no en la VM en la que instalas la extensión.

    Como alternativa, para proporcionar la configuración como una cadena intercalada, usa la marca --config en lugar de --config-from-file, por ejemplo, EXTENSION_NAME_1="CONFIG_1". Puedes usar --config-from-file o --config, pero no ambos en el mismo comando.

  • KEY_1=VALUE_1: Es una lista separada por comas de pares clave-valor que definen etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas --inclusion-labels varias veces, la política se orienta a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites esta marca, la política se aplica a todas las VMs de la zona especificada dentro de tu proyecto.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.

El comando falla si ya existe una política con el nombre especificado en la zona.

Ejemplo: Crea una política zonal con alcance de proyecto

Con el siguiente comando, se crea una política llamada test-extension-policy que instala la extensión ops-agent en la zona us-central1-f para el proyecto test-project. La marca --config-from-file especifica la ruta de acceso a un archivo local que contiene una configuración de YAML para el Agente de operaciones.

gcloud compute zone-vm-extension-policies create test-extension-policy \
  --project=test-project \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml"

Ejemplo: Crea una política zonal con alcance de proyecto con etiquetas de inclusión y prioridad

Con el siguiente comando, se crea una política llamada test-extension-policy-2 que instala la extensión ops-agent en la zona us-central1-f para el proyecto test-project en las VMs con la etiqueta env=prod. La prioridad de la política se establece en 500, y la marca --config-from-file especifica la ruta de acceso a un archivo local que contiene una configuración de YAML para el Agente de operaciones.

gcloud compute zone-vm-extension-policies create test-extension-policy-2 \
  --project=test-project \
  --zone=us-central1-f \
  --extensions=ops-agent \
  --config-from-file=ops-agent="/usr/ops-agent-config.yaml" \
  --priority=500 \
  --inclusion-labels=env=prod

REST

Para crear una política de extensión de VM zonal con alcance de proyecto, envía una solicitud POST al método zoneVmExtensionPolicies.insert. Este método define qué extensiones instalar y en qué VMs de una zona específica.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/vmExtensionPolicies

{
"name": "POLICY_NAME",
"description": "DESCRIPTION",
"extensionPolicies": {
   "EXTENSION_NAME_1": {
     "stringConfig": "EXTENSION_NAME_1_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_1_VERSION"
  },
   "EXTENSION_NAME_2": {
     "stringConfig": "EXTENSION_NAME_2_CONFIG",
     "pinnedVersion": "EXTENSION_NAME_2_VERSION"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "KEY_1": "VALUE_1"
       }
    }
  }
],
"priority": "PRIORITY"
}

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto.
  • ZONE: Es la zona en la que se aplica esta política.
  • POLICY_NAME: Es un nombre para la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: Es el nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Puedes especificar cualquiera de las siguientes extensiones compatibles:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension
  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: Es la configuración de la extensión, proporcionada como una cadena intercalada.
  • EXTENSION_NAME_1_VERSION, EXTENSION_NAME_2_VERSION: es la versión de la extensión. Si no especificas una versión para una extensión, el Gestor de extensiones de VM usa la versión más reciente disponible y la actualiza automáticamente cuando hay nuevas versiones disponibles.
  • KEY_1: VALUE_1: Es un par clave-valor que define las etiquetas de inclusión para un selector. Las VMs deben tener todas las etiquetas especificadas en un selector para que se las pueda seleccionar. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omites instanceSelectors, la política se aplica a todas las VMs de la zona especificada dentro de tu proyecto.
  • PRIORITY: Es un número entero de 0 a 65535 que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es 1000. Si varias políticas tienen la misma prioridad, el Gestor de extensiones de VM aplica la política actualizada más recientemente a las VMs.

Ejemplo: Crea una política zonal con alcance de proyecto

En el siguiente ejemplo, se crea una política llamada test-extension-policy que instala la extensión ops-agent en la zona us-central1-f para my-project.

POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/vmExtensionPolicies

{
"name": "test-extension-policy",
"description": "Test extension policy for Ops Agent",
"extensionPolicies": {
   "ops-agent": {
     "stringConfig": "logging:
      receivers:
        systemd_logs:
          type: systemd_journald
      service:
        pipelines:
          systemd_pipeline:
            receivers: [systemd_logs]",
     "pinnedVersion": "2.58.0"
  }
},
"instanceSelectors": [
  {
    "labelSelector": {
       "inclusionLabels": {
         "env": "test"
       }
    }
  }
],
"priority": "500"
}

¿Qué sigue?