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
- Revisa los conceptos básicos sobre el Gestor de extensiones de VM.
- Revisa las cuotas del Gestor de extensiones de VM.
- Revisa los precios del Gestor de extensiones de VM. El Gestor de extensiones de VM está disponible sin costo adicional, pero es posible que se generen cargos por el uso de las extensiones que instalan tus políticas.
- Habilita la API de Compute Engine en tu proyecto de Google Cloud si aún no está habilitada.
- Asegúrate de que tu VM ejecute la versión
20241209.01o posterior del agente invitado. - Para ver los registros de depuración de los eventos del Gestor de extensiones de VM, establece la configuración de registros del agente invitado.
-
Si aún no lo hiciste, configura la autenticación.
La autenticación verifica tu identidad para acceder a los servicios y las APIs de Google Cloud . Para ejecutar
código o muestras desde un entorno de desarrollo local, puedes autenticarte en
Compute Engine seleccionando una de las siguientes opciones:
Selecciona la pestaña según cómo planeas usar las muestras de esta página:
Console
Cuando usas la consola de Google Cloud para acceder a los servicios y las APIs de Google Cloud , no necesitas configurar la autenticación.
gcloud
-
Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada. Después de acceder, inicializa Google Cloud CLI con el siguiente comando:
gcloud init
-
- Configura una región y una zona predeterminadas.
REST
Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.
Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada.
Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de Google Cloud .
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 esorganizations/{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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, 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
--configen lugar de--config-from-file, por ejemplo,EXTENSION_NAME_1="CONFIG_1". Puedes usar--config-from-fileo--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-labelsvarias 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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: Especificaslow_rolloutofast_rollout. Si necesitas usar un plan de lanzamiento personalizado, especifica la marca--rollout-custom-planen lugar de--rollout-predefined-plancon 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-agentgoogle-cloud-sap-extensiongoogle-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 variosinstanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omitesinstanceSelectors, 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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 camponameporpredefinedRolloutPlany 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 esfolders/{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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, 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
--configen lugar de--config-from-file, por ejemplo,EXTENSION_NAME_1="CONFIG_1". Puedes usar--config-from-fileo--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-labelsvarias 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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: Especificaslow_rolloutofast_rollout. Si necesitas usar un plan de lanzamiento personalizado, especifica la marca--rollout-custom-planen lugar de--rollout-predefined-plancon 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-agentgoogle-cloud-sap-extensiongoogle-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 variosinstanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omitesinstanceSelectors, 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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 camponameporpredefinedRolloutPlany 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:
- En la consola de Google Cloud , ve a la página Políticas de extensiones de VM.
- Haz clic en Crear política de extensión.
- En el campo Nombre, ingresa un nombre para la política.
- Opcional: En el campo Descripción, ingresa una descripción para la política.
- 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. - En la sección Alcance, selecciona Lanzamiento global.
- 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:
- En la lista Extensión, selecciona una extensión. Para obtener más información, consulta Extensiones compatibles.
- 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.0o 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.
- Para el Agente de operaciones, puedes especificar la versión
- Opcional: En el campo Contenido del archivo de configuración, ingresa los parámetros de configuración de la extensión.
- 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.
- 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.
- 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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, 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
--configen lugar de--config-from-file, por ejemplo,EXTENSION_NAME_1="CONFIG_1". Puedes usar--config-from-fileo--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-labelsvarias 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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: Especificaslow_rolloutofast_rollout. Si necesitas usar un plan de lanzamiento personalizado, especifica la marca--rollout-custom-planen lugar de--rollout-predefined-plancon 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-agentgoogle-cloud-sap-extensiongoogle-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 variosinstanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omitesinstanceSelectors, la política se aplica a todas las VMs de tu proyecto en todas las zonas.PRIORITY: Es un número entero de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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 camponameporpredefinedRolloutPlany 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 esorganizations/{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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, 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
--configen lugar de--config-from-file, por ejemplo,EXTENSION_NAME_1="CONFIG_1". Puedes usar--config-from-fileo--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-labelsvarias 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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-agentgoogle-cloud-sap-extensiongoogle-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 variosinstanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omitesinstanceSelectors, 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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 esfolders/{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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, 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
--configen lugar de--config-from-file, por ejemplo,EXTENSION_NAME_1="CONFIG_1". Puedes usar--config-from-fileo--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-labelsvarias 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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-agentgoogle-cloud-sap-extensiongoogle-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 variosinstanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omitesinstanceSelectors, 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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:
- En la consola de Google Cloud , ve a la página Políticas de extensiones de VM.
- Haz clic en Crear política de extensión.
- En el campo Nombre, ingresa un nombre para la política.
- Opcional: En el campo Descripción, ingresa una descripción para la política.
- 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. - En la sección Alcance, selecciona Lanzamiento zonal.
- 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.
- 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:
- En la lista Extensión, selecciona una extensión. Para obtener más información, consulta Extensiones compatibles.
- 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.0o 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.
- Para el Agente de operaciones, puedes especificar la versión
- Opcional: En el campo Contenido del archivo de configuración, ingresa los parámetros de configuración de la extensión.
- 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.
- 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-agentgoogle-cloud-sap-extensiongoogle-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 comandogcloud, 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
--configen lugar de--config-from-file, por ejemplo,EXTENSION_NAME_1="CONFIG_1". Puedes usar--config-from-fileo--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-labelsvarias 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 de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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-agentgoogle-cloud-sap-extensiongoogle-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 variosinstanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógico). Si omitesinstanceSelectors, la política se aplica a todas las VMs de la zona especificada dentro de tu proyecto.PRIORITY: Es un número entero de0a65535que define la prioridad de la política. Los números más bajos indican una prioridad más alta. El valor predeterminado es1000. 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?
- Para inspeccionar el progreso del lanzamiento y el estado de la extensión, consulta Visualiza los detalles y el estado de la extensión de VM.
- Para modificar los parámetros de configuración, cambiar las versiones fijadas o quitar los agentes implementados, consulta Administra extensiones de VM con políticas de extensiones.
- Para compilar paneles de Cloud Monitoring y configurar alertas para el estado del agente, la CPU y el uso de memoria, consulta Supervisa las extensiones de VM.
- Para diagnosticar lanzamientos con errores, verificar los procesos de invitado en ejecución o inspeccionar los registros de depuración del agente invitado, consulta Soluciona problemas de extensiones de VM.