Usar políticas de agente

Las políticas de agente permiten instalar y mantener automáticamente los agentes de observabilidad de Google Cloud en un conjunto de máquinas virtuales de Compute Engine que cumplan los criterios especificados por el usuario. Puedes crear una política para unGoogle Cloud proyecto que rija las VMs asociadas a ese proyecto, tanto las que ya existen como las nuevas, y así asegurarte de que todos los agentes de observabilidad de Google Cloud se instalen, desinstalen y actualicen automáticamente (opcionalmente) correctamente en esas VMs.Google Cloud

Para crear y gestionar políticas de agente, usa el grupo de comandos gcloud beta compute instances ops-agents policies de la CLI de Google Cloud o el agent-policy módulo de Terraform. Las políticas de agente usan el paquete de herramientas VM Manager de Compute Engine para gestionar las políticas de SO, que pueden automatizar la implementación y el mantenimiento de configuraciones de software, como los agentes de observabilidad de Google Cloud: el agente de operaciones, el agente de monitorización antiguo y el agente de registro antiguo.

Sistemas operativos compatibles

Puedes aplicar una política de agente a las instancias de máquina virtual de Compute Engine que ejecuten los sistemas operativos que se muestran en la siguiente tabla:

Sistema operativo Agente de operaciones
(políticas de disponibilidad general y beta†) 		Agente de Logging
(solo políticas beta†) 		Agente de monitorización
(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)
Imágenes de máquinas virtuales de aprendizaje profundo 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):
ubuntu-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 y Core 2022
†  En las políticas de agentes beta, las columnas de agentes se asignan a un tipo de agente especificado en la gcloud beta compute instances ops-agents policies create invocación:
  • Agente de operaciones se asigna al tipo de agente ops-agent.
  • El agente de Logging se asigna al tipo de agente logging.
  • Agente de monitorización se asigna al tipo de agente metrics.
‡ El agente de monitorización no es compatible con rhel-7-9-sap-ha, rhel-8-2-sap-ha ni 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 gestionar las políticas de agentes. Para obtener información sobre el uso de Terraform, consulta Integración con Terraform.

Para crear una política de agente con la CLI de Google Cloud, sigue estos pasos:

  1. Si aún no lo has hecho, instala la CLI de Google Cloud.

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

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

    gcloud components install beta

    Para comprobar si tienes el componente beta instalado, ejecuta el siguiente comando:

    gcloud components list

    Si ya has instalado el componente beta, asegúrate de tener la versión más reciente:

    gcloud components update

  3. Descarga y usa la siguiente secuencia de comandos para habilitar las APIs y definir los permisos adecuados para usar la CLI de Google Cloud: set-permissions.sh.

    Para obtener información sobre la secuencia de comandos, consulta el artículo Secuencia de comandos set-permissions.sh.

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

    Para ver ejemplos de cómo dar formato al comando, consulta la sección Ejemplos de 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 de gcloud beta compute instances ops-agents policies.

Prácticas recomendadas para usar políticas de agente

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

A continuación, se muestra un ejemplo de un plan de lanzamiento gradual para máquinas virtuales 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 y el agente de Monitoring antiguos en todas las VMs con las etiquetas 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 policies create.

Fase 2: Actualiza esa política para orientarla a las VMs de 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: Actualizar la política para borrar el filtro de zonas y que se implemente a nivel mundial

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

Políticas en VMs anteriores a la configuración del SO

Es posible que tengas que instalar y configurar manualmente el agente de configuración del SO en las VMs anteriores a la configuración del SO. Para obtener información sobre cómo instalar y verificar manualmente el agente de configuración del SO, consulta la lista de comprobación de verificación de VM Manager.

Solucionar problemas con las políticas de agentes beta

En esta sección se proporciona información para ayudarle a resolver problemas con las políticas del agente beta del agente de operaciones, el agente de monitorización antiguo y el agente de registro antiguo.

Los comandos ops-agents policy no funcionan

Cuando falla un comando gcloud beta compute instances ops-agents policies, la respuesta muestra un error de validación. Corrija los errores modificando los argumentos y las marcas del comando tal como se sugiere en 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 estas condiciones con más detalle.

Permiso de gestión de identidades y accesos insuficiente

Si un comando gcloud beta compute instances ops-agents policies falla y muestra un error de permiso, asegúrate de haber ejecutado la secuencia de comandos set-permissions.sh tal como se describe en Crear una política de agente 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 OS Config no está habilitada

Un error de ejemplo tiene el siguiente aspecto:

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 introducir y para habilitar la API o ejecutar la secuencia de comandos set-permissions.sh que se describe en Crear una política de agente para conceder todos los permisos necesarios. Si introduces y en la petición del mensaje de error, tendrás que ejecutar la secuencia de comandos set-permissions.sh para definir los permisos necesarios.

Para verificar que la API OS Config está habilitada en 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 ejemplo tiene el siguiente aspecto:

ALREADY_EXISTS: Requested entity already exists

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

La política no existe

Un error de ejemplo tiene el siguiente aspecto:

NOT_FOUND: Requested entity was not found

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

La política se crea, pero parece que no tiene ningún efecto

Los agentes de configuración de SO se despliegan en cada instancia de Compute Engine para gestionar los paquetes de los agentes de Logging y Monitoring. Puede parecer que la política no tiene ningún 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

Un ejemplo de salida es el siguiente:

    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, sigue estos pasos:

  1. Conéctate a tu instancia mediante RDP o una herramienta similar e inicia sesión en Windows.

  2. Abre una terminal de PowerShell y ejecuta el siguiente comando de PowerShell. No necesitas privilegios de administrador.

    Get-Service google_osconfig_agent

Un ejemplo de salida es el siguiente:

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

Si el agente de configuración del SO no está instalado, es posible que estés usando un sistema operativo que no sea compatible con Gestor de VMs. En el documento Detalles del sistema operativo de Compute Engine se indica qué funciones de VM Manager se admiten en cada sistema operativo de Compute Engine.

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

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

Para comprobar si hay algún error cuando el agente de configuración del SO aplica las políticas, puedes consultar el registro del agente de configuración del SO. Puedes hacerlo con el Explorador de registros o con SSH o RDP para comprobar instancias de Compute Engine concretas.

Para ver los registros del agente de OS Config 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 y 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 y 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 e inicia sesión en Windows.

  2. Abre la aplicación Visor de eventos y selecciona Registros de Windows > Aplicación. A continuación, busca los registros en los que Source sea igual a OSConfigAgent.

Si se produce un error al conectar con el servicio OS Config, asegúrate de ejecutar la secuencia de comandos set-permissions.sh tal como se describe en Crear una política de agente para configurar los metadatos de OS Config.

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'

Los agentes de observabilidad están instalados, pero no funcionan correctamente

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

Habilitar 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 al informar de un problema.

Puedes definir los metadatos osconfig-log-level: debug para habilitar el registro de nivel de depuración del agente de configuración del SO. Los registros recogidos contienen más información que puede ayudar con la investigación.

Para habilitar el registro a nivel de depuración en todo el proyecto, ejecuta el siguiente comando:

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

Para habilitar el registro a nivel de depuración en una máquina virtual, 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 ofrece información adicional sobre las secuencias de comandos auxiliares descritas en este documento:

Secuencia de comandos set-permissions.sh

Después de descargar la secuencia de comandos set-permissions.sh, puede usarla para realizar las siguientes acciones en función de los argumentos que proporcione:

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

Para habilitar las APIs, conceda los roles necesarios a la cuenta de servicio predeterminada y habilite los metadatos de configuración del SO de un proyecto. Para ello, ejecute la siguiente secuencia de comandos:

bash set-permissions.sh --project=PROJECT_ID

Para conceder además uno de los roles de configuración del SO a un usuario que no tenga el rol 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]

Para conceder además uno de los roles de configuración de SO a una cuenta de servicio que no sea la 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]

Secuencia de comandos diagnose.sh

Dado un ID de proyecto, un ID de instancia de Compute Engine y un ID de política de agente, la secuencia de comandos diagnose.sh recoge automáticamente la información necesaria para diagnosticar problemas con la política:

  • Versión del agente de configuración del SO
  • La política de invitado de configuración del SO subyacente
  • Las políticas que se aplican a esta instancia de Compute Engine
  • Los repositorios de paquetes del agente que se extraen en 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 de Terraform

Para saber cómo aplicar o quitar una configuración de Terraform, consulta Comandos básicos de Terraform. Para obtener información sobre cómo funciona Terraform, consulta el artículo Usar Terraform.

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