Usa políticas de agentes

Las políticas de agentes permiten la instalación y el mantenimiento automáticos de los agentes de Google Cloud Observability en una flota de VMs de Compute Engine que coinciden con los criterios especificados por el usuario. Puedes crear una política para un proyecto de Google Cloud que regule las VMs existentes y nuevas asociadas con ese proyecto, lo que garantiza una instalación adecuada y actualización automática opcional de todos los agentes de Google Cloud Observability en esas VMs.

Para crear y administrar políticas de agente, debes usar el comando gcloud beta compute instances ops-agents policies en Google Cloud CLI o el módulo agent-policy de Terraform. Las políticas de agentes usan el conjunto de herramientas de VM Manager en Compute Engine para administrar las políticas del SO, que pueden automatizar la implementación y el mantenimiento de configuraciones de software, como los agentes de Google Cloud Observability: el agente de operaciones, el agente de Monitoring heredado y el agente de Logging heredado.

Sistemas operativos compatibles

Puedes aplicar una política de agentes a las Instancias de VM de Compute Engine que ejecutan los sistemas operativos que se muestran en la siguiente tabla.

Sistema operativo Agente de operaciones
(políticas de Google Analytics y Beta†) 		Agente de Logging
(solo políticas beta†) 		Agente de Monitoring
(solo políticas beta†)
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7:
rhel-7, rhel-7-6-sap-ha, rhel-7-7-sap-ha, rhel-7-9-sap-ha		 ‡
RHEL 8:
rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha		 ‡
Debian 9 (Stretch)
Debian 11 (Bullseye)
Deep Learning VM Images basadas en Debian 11 (Bullseye)
Ubuntu LTS 18.04 (Bionic Beaver):
ubuntu-1804-lts, ubuntu-minimal-1804-lts
Ubuntu LTS 20.04 (Focal Fossa):
ubuntu-2004-lts, ubuntu-minimal-2004-lts
Ubuntu LTS 22.04 (Jammy Jellyfish):
buntu-2204-lts, ubuntu-minimal-2204-lts
SLES 12:
sles-12, sles-12-sp5-sap
SLES 15:
sles-15, sles-15-sp2-sap, sles-15-sp3-sap, sles-15-sp4-sap, sles-15-sp5-sap, sles-15-sp6-sap
OpenSUSE Leap 15:
opensuse-leap (opensuse-leap-15-3-*,
opensuse-leap-15-4-*)
Windows Server:
2016, 2019, 2022, Core 2016, Core 2019, Core 2022
†  En las políticas de los agentes Beta, las columnas del agente se asignan a un tipo de agente especificado a la invocación gcloud beta compute instances ops-agents policies create:
  • El agente de operaciones se asigna al tipo de agente ops-agent.
  • El agente de Logging se asigna al tipo de agente logging.
  • El agente de Monitoring se asigna al tipo de agente metrics.
‡ El agente de Monitoring no es compatible con rhel-7-9-sap-ha, rhel-8-2-sap-ha o rhel-8-4-sap-ha.

Crear una política de agente

En esta sección, se describe cómo usar el SDK de Google Cloud para administrar las políticas de agentes. Para obtener información sobre cómo usar Terraform, consulta Integración de Terraform.

Para crear una política de agentes mediante Google Cloud CLI, completa los siguientes pasos:

  1. Si aún no lo hiciste, instala la Google Cloud CLI.

    Las políticas de agentes que se describen en este documento usan el grupo de comandos beta.

  2. Si aún no lo hiciste, instala el componente beta de gcloud CLI:

    gcloud components install beta

    A fin de verificar si tienes el componente beta para la instalación, ejecuta este comando:

    gcloud components list

    Si ya instalaste el componente beta, asegúrate de tener la última versión:

    gcloud components update

  3. Usa la siguiente secuencia de comandos para de habilitar las API y establecer los permisos adecuados a fin de usar Google Cloud CLI: set-permissions.sh.

    Para obtener información sobre la secuencia de comandos, consulta La secuencia de comandos set-permissions.sh.

  4. Usa el comando gcloud beta compute instances ops-agents policies create para crear una política. Para conocer la sintaxis del comando, consulta la documentación create gcloud beta compute instances ops-agents policies.

    Para ver ejemplos que muestren cómo dar formato al comando, consulta la sección de Ejemplos en la documentación de Google Cloud CLI.

    Para obtener más información sobre los demás comandos del grupo de comandos y las opciones disponibles, consulta la documentación gcloud beta compute instances ops-agents policies.

Prácticas recomendadas para el uso de políticas de agentes

Para controlar el impacto en los sistemas de producción durante el lanzamiento, te recomendamos que uses las etiquetas y zonas de instancia para filtrar las instancias a las que se aplica la política.

Este es un ejemplo de un plan de lanzamiento por fases para las VMs de Debian 11 en un proyecto llamado my_project:

Fase 1: Crea una política llamada ops-agents-policy-safe-rollout para instalar el agente de Logging heredado y el agente de Monitoring en todas las VMs con la etiqueta env=test y app=myproduct.

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=debian,version=11 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

Para obtener más información sobre cómo especificar el sistema operativo, consulta gcloud beta compute instances ops-agents policiescreate.

Fase 2: Actualiza esa política para orientarla a las VMs ubicadas en una sola zona que tengan las etiquetas env=prod y app=myproduct.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

Fase 3: Actualiza esa política para borrar el filtro de zonas a fin de que se lance de forma global.

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

Políticas en las VM que son anteriores a la configuración del SO

Es posible que debas instalar y configurar de forma manual el agente de configuración del SO en las VM anteriores a la configuración del SO. Para obtener información sobre cómo instalar y verificar el agente de configuración del SO de forma manual, consulta la lista de tareas para la verificación de VM Manager.

Soluciona problemas de políticas del agente Beta

En esta sección, se proporciona información para ayudarte a resolver problemas con las políticas del agente Beta para el Agente de operaciones, el agente de Monitoring heredado y el agente de Logging heredado.

Los comandos ops-agents policy fallan

Cuando un comando gcloud beta compute instances ops-agents policies falla, la respuesta muestra un error de validación. Resuelve esos errores mediante la corrección de las marcas y los argumentos del comando como lo sugiere el mensaje de error.

Además de los errores de validación, es posible que veas errores que indiquen las siguientes condiciones:

En las siguientes secciones, se describen esos pasos con más detalle.

Permiso de IAM insuficiente

Si un comando gcloud beta compute instances ops-agents policies falla con un error de permiso, asegúrate de que ejecutaste la secuencia de comandos set-permissions.sh como se describe en Crea una política de agentes para configurar los roles de la política de configuración del SO:

Para obtener más información sobre la secuencia de comandos set-permissions.sh, consulta La secuencia de comandos set-permissions.sh.

La API de configuración del SO no está habilitada

Un error de muestra se parece al siguiente ejemplo:

API [osconfig.googleapis.com] not enabled on project PROJECT_ID.
Would you like to enable and retry (this will take a few minutes)?
(y/N)?

Puedes ingresar y para habilitar la API o ejecutar la secuencia de comandos set-permissions.sh, que se describe en Crea una política de agente, para otorgar todos los permisos necesarios. Si ingresas y en el mensaje de error, aún debes ejecutar la secuencia de comandos set-permissions.sh para configurar los permisos necesarios.

A fin de verificar que la API de configuración del SO esté habilitada para el proyecto, ejecuta los siguientes comandos:

gcloud services list --project PROJECT_ID | grep osconfig.googleapis.com

El resultado esperado es el siguiente:

osconfig.googleapis.com    Cloud OS Config API

La política ya existe

Un error de muestra se parece al siguiente ejemplo:

ALREADY_EXISTS: Requested entity already exists

Este error indica que esta política ya existe con el mismo nombre, ID del proyecto y región. Puedes usar el comando describe gcloud beta compute instances ops-agents policies para confirmarlo.

La política no existe

Un error de muestra se parece al siguiente ejemplo:

NOT_FOUND: Requested entity was not found

Este error puede significar que la política nunca se creó, que se borró la política o que el ID de la política especificado es incorrecto. Asegúrate de que el POLICY_ID que se usa en un comando gcloud beta compute instances ops-agents policies describe, update o delete corresponda a una política existente. Para obtener una lista de políticas de agentes, usa el comando gcloud beta compute instances ops-agents policies list.

Se crea la política, pero parece no tener efecto

Los agentes de configuración del SO se implementan en cada instancia de Compute Engine a fin de administrar los paquetes de los agentes de Logging y Monitoring. Es posible que la política no tenga efecto si el agente de configuración del SO subyacente no está instalado.

Linux

Para verificar que el agente de configuración del SO esté instalado, ejecuta el siguiente comando:

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

El siguiente es un resultado de muestra:

    google-osconfig-agent.service - Google OSConfig Agent
    Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
    Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
    Main PID: 369 (google_osconfig)
     Tasks: 8 (limit: 4374)
    Memory: 102.7M
    CGroup: /system.slice/google-osconfig-agent.service
            └─369 /usr/bin/google_osconfig_agent

Windows

Para verificar que el agente de configuración del SO esté instalado, ejecuta el siguiente comando:

  1. Conéctate a tu instancia mediante RDP o una herramienta similar y accede a Windows.

  2. Abre una terminal de PowerShell y ejecuta los siguientes comandos de PowerShell. No necesitas privilegios de administrador.

    Get-Service google_osconfig_agent

El siguiente es un resultado de muestra:

    Status   Name               DisplayName
    ------   ----               -----------
    Running  google_osconfig_a… Google OSConfig Agent

Si el agente de configuración del SO no está instalado, es posible que uses un sistema operativo que no sea compatible con VM Manager. En el documento Detalles del sistema operativo de Compute Engine, se indica qué características de VM Manager son compatibles con cada sistema operativo de Compute Engine.

Si el sistema operativo es compatible con VM Manager, puedes instalar el agente de configuración del SO de forma manual.

El agente de configuración del SO está instalado, pero no instala el agente de supervisión

Para verificar si hay algún error cuando el agente de configuración del SO aplica las políticas, puedes verificar el registro del agente de configuración del SO. Esto se puede hacer mediante el Explorador de registros o SSH o RDP para verificar instancias individuales de Compute Engine.

Para ver los registros del agente de configuración del SO en el explorador de registros, usa el siguiente filtro:

resource.type="gce_instance"
logId(OSConfigAgent)

Para ver los registros del agente de configuración del SO, haz lo siguiente:

CentOS, RHEL,
SLES, SUSE

Ejecuta el siguiente comando: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/messages \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Debian/ Ubuntu

Ejecuta el siguiente comando: 

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/syslog \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Windows

  1. Conéctate a tu instancia mediante RDP o una herramienta similar y accede a Windows.

  2. Abre la app de Visualizador de eventos, selecciona Registros de Windows > Aplicación y busca registros que tengan Source igual a OSConfigAgent.

Si se produce un error cuando se establece la conexión al servicio de configuración del SO, asegúrate de ejecutar la secuencia de comandos set-permissions.sh como se describe en Crea una política de agentes para establecerla crear los metadatos de configuración del SO.

Para verificar que los metadatos de configuración del SO estén habilitados, puedes ejecutar el siguiente comando:

gcloud compute project-info describe \
    --project PROJECT_ID \
    | grep "enable-osconfig\|enable-guest-attributes" -A 1

El resultado esperado es el siguiente:

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

Se instalaron los agentes de observabilidad, pero no funcionan de forma correcta

Para obtener información sobre cómo depurar agentes específicos, consulta los siguientes documentos:

Habilita los registros de nivel de depuración para el agente de configuración del SO

Puede ser útil habilitar el registro de nivel de depuración en el agente de configuración del SO cuando se informa un problema.

Puedes configurar los metadatos osconfig-log-level: debug a fin de habilitar el registro de nivel de depuración del agente de configuración del SO. Los registros recopilados tienen más información que ayuda a la investigación.

Ejecuta el siguiente comando para habilitar el registro de nivel de depuración en todo el proyecto:

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Si deseas habilitar el registro de nivel de depuración de una VM, ejecuta el siguiente comando:

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

Secuencias de comandos auxiliares

En esta sección, se proporciona información adicional sobre las secuencias de comandos auxiliares descritas en este documento:

La secuencia de comandos set-permissions.sh

Después de descargar la secuencia de comandos set-permissions.sh, puedes usarla para realizar las siguientes acciones, según los argumentos que proporciones:

En los siguientes ejemplos, se muestran algunas invocaciones comunes para la secuencia de comandos. Para obtener más información, consulta los comentarios en la secuencia de comandos.

Para habilitar las API, otorgar los roles necesarios a la cuenta de servicio predeterminada y habilitar los metadatos de configuración del SO de un proyecto, ejecuta la secuencia de comandos de la siguiente manera:

bash set-permissions.sh --project=PROJECT_ID

Además, para otorgar una de las funciones de configuración del SO a un usuario que no tiene la función de propietario (roles/owner) en el proyecto, ejecuta la secuencia de comandos de la siguiente manera:

bash set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

Además, para otorgar una de las funciones de configuración del SO a una cuenta de servicio no predeterminada, ejecuta la secuencia de comandos de la siguiente manera:

bash set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

La secuencia de comandos diagnose.sh

Con un ID del proyecto, un ID de instancia de Compute Engine y el ID de política del agente, la secuencia de comandos diagnose.sh recopila de forma automática la información necesaria para ayudar a diagnosticar Problemas con la política:

  • La versión del agente de configuración del SO
  • La política de invitado de la configuración del SO subyacente
  • Las políticas que se aplican a esta instancia de Compute Engine
  • Los repositorios de paquetes de agente que se extraen a esta instancia de Compute Engine

Para invocar la secuencia de comandos, ejecuta el siguiente comando:

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID

Integración en Terraform

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform. Para obtener información sobre cómo funciona Terraform, consulta Cómo usar Terraform.

La compatibilidad con Terraform para las políticas de agentes se basa en los comandos de Google Cloud CLI. Para crear una política de agente con Terraform, sigue las instrucciones de agent-policy del módulo de Terraform. También puedes encontrar políticas de ejemplo en el directorio examples.