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 automáticamente extensiones en una flota de máquinas virtuales (VMs) de Compute Engine. Si defines una política, puedes asegurarte de que las extensiones específicas se instalen y mantengan en cualquier VM que coincida con los criterios que especifiques, como las etiquetas de VM.

Antes de comenzar

Roles de IAM obligatorios

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

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

Para obtener más información sobre los roles y permisos de IAM en Compute Engine, consulta Roles y permisos de Compute Engine.

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

Cuando se aplican varias políticas a la misma VM, VM Extension Manager usa la prioridad de la política para resolver conflictos.

Cuando dos políticas entran en conflicto para la misma extensión, prevalece la política con mayor prioridad. Los valores de prioridad varían de 0 a 65535, donde un número más bajo significa una prioridad más alta. La prioridad predeterminada es 1,000. Si varias políticas tienen la misma prioridad, VM Extension Manager aplica a las VMs la política que se actualizó más recientemente. Si borras una política, no se quitará la extensión si aún se aplica a la VM una política de menor prioridad.

Crea una política de extensión de VM global

Puedes crear una política de extensión de VM global para instalar extensiones en VMs de varias zonas de tu proyecto según un plan de lanzamiento. Una política de extensión de VM global no se aplica directamente a las VMs. En cambio, a medida que se implementa la política, VM Extension Manager crea políticas en cada zona según el plan de implementación. Luego, estas políticas administran la instalación de extensiones en las VMs dentro de sus respectivas zonas.

Puedes usar gcloud o el método globalVmExtensionPolicies.insert para crear políticas de extensiones globales.

Acerca de los planes de lanzamiento

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

  • slow_rollout: La política se lanza 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 segmenta 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, como se muestra en el ejemplo 2.

Crea una política global

Usa uno de los siguientes métodos para crear una política de extensión de VM global.

gcloud

Usa el comando gcloud beta compute global-vm-extension-policies create para crear una política de extensión de VM global:

gcloud beta compute global-vm-extension-policies create POLICY_NAME \
  --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 el nombre de 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 una lista separada por comas de las extensiones que se agregarán a la política. Debes especificar al menos una extensión. Los valores válidos para las extensiones son los siguientes:
    • 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, VM Extension Manager usa la última versión disponible y la actualiza automáticamente cuando hay versiones nuevas 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 les aplique la segmentación. Si especificas --inclusion-labels varias veces, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógica). Si omites esta marca, la política se aplicará a todas las VMs de tu proyecto en todas las zonas.

  • PRIORITY: Es un número entero que define la prioridad de la política. Los números más grandes indican una mayor prioridad. El valor predeterminado es 1,000. Si varias políticas tienen la misma prioridad, se aplica a las VMs la política que se actualizó más recientemente.

  • ROLLOUT_PLAN: Especifica slow_rollout o fast_rollout. Si necesitas usar un plan de lanzamiento personalizado, usa la marca --rollout-custom-plan en lugar de --rollout-predefined-plan y especifica el nombre del plan, por ejemplo:

    --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 se especifica ninguna marca de plan de lanzamiento, se usa slow_rollout.

  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando se detecta un conflicto entre una política zonal y una global. Los valores posibles son:

    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto con el mismo nombre. Este es el comportamiento predeterminado.
    • overwrite: La política global anula cualquier política zonal que tenga el mismo nombre y, luego, administra los lanzamientos de políticas en la zona.

    Para obtener más detalles, consulta la marca --rollout-conflict-behavior.

Ejemplo 1

El siguiente comando 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 YAML para el agente de operaciones, y --rollout-predefined-plan especifica el plan slow_rollout.

gcloud beta 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 2

El siguiente comando 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 YAML para el Agente de operaciones. La marca --rollout-custom-plan especifica un plan de lanzamiento personalizado.

 gcloud beta 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, realiza una solicitud POST al método globalVmExtensionPolicies.insert.

POST https://compute.googleapis.com/compute/beta/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: el ID de tu proyecto
  • POLICY_NAME: Es el nombre de la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: El nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Los valores válidos para las extensiones son los siguientes:
    • 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, VM Extension Manager usa la versión disponible más reciente y la actualiza automáticamente cuando hay versiones nuevas 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 les aplique la segmentación. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (operador lógico OR). 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 que define la prioridad de la política. Los números más grandes indican una mayor prioridad. El valor predeterminado es 1,000. Si varias políticas tienen la misma prioridad, se aplica a las VMs la política que se actualizó más recientemente.

  • ROLLOUT_CONFLICT_BEHAVIOR: Especifica el comportamiento cuando se detecta un conflicto entre una política zonal y una global. Los valores posibles son:

    • "" (cadena vacía): La política global no reemplaza las políticas zonales en conflicto con el mismo nombre. Este es el comportamiento predeterminado.

    • overwrite: La política global anula cualquier política zonal que tenga el mismo nombre y, luego, administra los lanzamientos de políticas en la zona.

      Para obtener más detalles, 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 durante cinco días. Este es el plan de lanzamiento predeterminado si no se especifica ninguno.
    • FAST_ROLLOUT: Implementa la política de inmediato en todas las zonas.

Ejemplo

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/beta/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"
    }
  }
}

Crea una política de extensión de VM zonal

Usa uno de los siguientes métodos para crear una política de extensión de VM zonal. Esta política zonal define qué extensiones se instalarán y en qué VMs de una zona específica.

Console

  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 mayor prioridad. El valor predeterminado es 1,000.
  6. En la lista Zona, selecciona la zona en la que deseas aplicar esta política.
  7. En la sección Extensiones, haz clic en Agregar extensión y realiza las siguientes acciones para cada extensión que quieras instalar en las VMs de destino:
    1. En la lista Extensión, selecciona una extensión. Consulta las extensiones compatibles.
    2. En la lista Versión, especifica el número de versión de la extensión. Déjalo en blanco para seleccionar la versión más reciente.
      • En el caso del Agente de operaciones, puedes especificar la versión 2.58.0 o posterior.
      • Para las cargas de trabajo de Extension for SAP y Extension for Compute, 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 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.
  9. Haz clic en Crear.

gcloud

Para crear una política de extensión de VM zonal y, luego, implementarla en las VMs de una zona específica, usa el comando gcloud beta compute zone-vm-extension-policies create:

gcloud beta compute zone-vm-extension-policies create POLICY_NAME \
    --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 el nombre de la política de extensión de VM.
  • 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. Los valores válidos para las extensiones son los siguientes:
    • 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, VM Extension Manager usa la última versión disponible y la actualiza automáticamente cuando hay versiones nuevas 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. Esta ruta de acceso 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 les aplique la segmentación. Si especificas --inclusion-labels varias veces, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (OR lógica). Si omites esta marca, la política se aplicará a todas las VMs de la zona especificada.

  • PRIORITY: Es un número entero del 0 al 65535 que define la prioridad de la política. Los números más bajos indican una mayor prioridad. El valor predeterminado es 1,000.

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

Ejemplo 1

El siguiente comando 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 YAML para el agente de operaciones.

gcloud beta 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 2

El siguiente comando 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 YAML para el Agente de operaciones.

 gcloud beta 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, realiza una solicitud POST al método zoneVmExtensionPolicies.insert. Este método define qué extensiones se instalarán y en qué VMs de una zona específica.

POST https://compute.googleapis.com/compute/beta/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: el ID de tu proyecto
  • ZONE: Es la zona en la que se aplica esta política.
  • POLICY_NAME: Es el nombre de la política de extensión de VM.
  • DESCRIPTION: Es una descripción opcional de la política.
  • EXTENSION_NAME_1, EXTENSION_NAME_2: El nombre de la extensión que se agregará a la política. Debes especificar al menos una extensión. Los valores válidos para las extensiones son los siguientes:
    • ops-agent
    • google-cloud-sap-extension
    • google-cloud-workload-extension

  • 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, VM Extension Manager usa la versión disponible más reciente y la actualiza automáticamente cuando hay versiones nuevas disponibles.

  • EXTENSION_NAME_1_CONFIG, EXTENSION_NAME_2_CONFIG: Es la configuración de la extensión, proporcionada como una cadena intercalada.

  • 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 les aplique la segmentación. Si especificas varios instanceSelectors, la política se aplica a las VMs que coinciden con cualquiera de los selectores proporcionados (operador lógico OR). Si omites instanceSelectors, la política se aplica a todas las VMs de la zona especificada.

  • PRIORITY: Es un número entero del 0 al 65535 que define la prioridad de la política. Los números más bajos indican una mayor prioridad. El valor predeterminado es 1,000.

Ejemplo

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/beta/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?