Usa políticas de agentes (GA)

Para crear y administrar políticas de agente, debes usar el comando gcloud compute instances ops-agents policies en Google Cloud CLI o el módulo ops-agent-policy de Terraform. Las políticas de agentes usan VM Manager , con herramientas de este tipo Compute Engine para administrar las políticas del SO que puede automatizar la implementación y el mantenimiento de los parámetros de configuración de software como el Agente de operaciones. Estas políticas no se pueden aplicar al agente de Monitoring ni al agente de Logging heredados.

Las políticas del agente de Google Analytics usan Asignación de políticas del SO en la API de configuración del SO. Aunque hay gcloud CLI general grupo de comandos para administrar las asignaciones de políticas del SO, gcloud compute os-config os-policy-assignments, el El grupo de comandos gcloud compute instances ops-agents policies está diseñado específicamente para el agente las políticas descritas en este documento.

Antes de comenzar

El módulo ops-agent-policy de Terraform se compila a partir de los comandos gcloud compute instances ops-agents policies del SDK de Google Cloud. Para obtener información sobre cómo funciona Terraform, consulta Usa Terraform.

Antes de usar Google Cloud CLI o el módulo Terraform para crear políticas de agentes, completa los siguientes pasos:

  1. Si vas a usar los comandos de gcloud compute instances ops-agents policies y aún no lo hiciste, instala Google Cloud CLI.

  2. Si vas a usar el módulo de Terraform, haz lo siguiente:

    1. Si necesitas información para instalar Terraform, consulta Instala y configura Terraform Cloud Shell ya tiene instalado Terraform.

    2. Clona el repositorio terraform-google-cloud-operations, que Contiene el módulo ops-agent-policy:

      git clone https://github.com/terraform-google-modules/terraform-google-cloud-operations

  3. Descarga y ejecuta la secuencia de comandos prepare-for-ops-agents-policies.sh para habilitar las APIs necesarias y establecer los permisos adecuados para usar las APIs Google Cloud CLI o Terraform.

    Para obtener información sobre la secuencia de comandos, consulta la secuencia de comandos prepare-for-ops-agents-policies.sh.

Desinstala los agentes de Monitoring y Logging heredados

Si creas una política para el Agente de operaciones, asegúrate de que tus VMs no tengan el agente de Logging heredado ni el agente de Monitoring instalados. Ejecutar el Agente de operaciones y los agentes heredados en la misma VM puede causar la transferencia de registros duplicados o un conflicto en la transferencia de métricas. Si es necesario, desinstala el agente de Monitoring y desinstala el agente de Logging antes de crear una política para instalar el Agente de operaciones.

Verifica que el agente de configuración del SO esté instalado

Es posible que debas instalar y configurar de forma manual 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 el agente de configuración del SO de forma manual, consulta la lista de tareas para la verificación de VM Manager.

Encontrar valores para la información del sistema operativo

Si deseas aplicar políticas de agentes a versiones o sistemas operativos específicos, debes conocer los valores que usa la configuración del SO para hacer referencia a ellos.

Para encontrar valores para los campos osShortName y osVersion de una VM, usa los siguientes comandos:

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^ShortName: "

gcloud compute instances os-inventory describe INSTANCE_NAME \
--zone ZONE | grep "^Version: "

Estos comandos requieren que el agente de configuración del SO esté instalado en la VM.

Crea una política de agentes para administrar el Agente de operaciones

Línea de comandos

Para crear una política de agente, usa el comando gcloud compute instances ops-agents policiescreate. Este comando tiene la siguiente estructura:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone ZONE \
  --file path/to/policy-description-file.yaml \
  --project PROJECT_ID

Cuando uses este comando, reemplaza las variables de la siguiente manera:

  • POLICY_ID es un nombre para tu política.
  • ZONE es una zona de Compute Engine. Las políticas de agentes se aplican solo a las VMs en la zona especificada; para aplicar una política en varias zonas, debes crear varias políticas.
  • path/to/policy-description-file.yaml es la ruta de acceso a un archivo YAML que describe la política. Para obtener información sobre la estructura de este archivo, consulta Describe las políticas de agentes.
  • PROJECT_ID es el ID de tu proyecto de Google Cloud.

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

Describe las políticas de agentes

Proporcionas información sobre a la gcloud compute instances ops-agents policies create mediante la creación de un archivo YAML que describa la política y pasa ese archivo al comando como el valor de la opción --file.

En esta sección, se describe la estructura del archivo de descripción de políticas. Para obtener más información, consulta Ejemplo de archivos de descripción de la política.

Formato del archivo YAML de descripción de políticas

El archivo de descripción de una política de agente debe incluir dos grupos de campos:

  • agentsRule, que le indica al agente si se debe instalar o quitar el Agente de operaciones y especifica la versión en la que debe operar.

  • instanceFilter, que describe las VMs en las que se aplica la política.

Estructura del grupo de campos agentsRule

El grupo de campos agentsRule tiene la siguiente estructura:

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y
  • El campo packageState le indica a la política el estado previsto del Agente de operaciones. Los valores válidos son installed y removed.

  • El campo version indica la versión del Agente de operaciones que se debe instalar o quitar. Puedes especificar los siguientes valores:

    • latest es la versión más reciente del Agente de operaciones.
    • 2.*.* es la versión más reciente de la versión principal 2 del Agente de operaciones.
    • 2.x.y indica una versión específica de la versión principal 2.

    Para obtener información sobre las versiones disponibles del agente de operaciones, consulta el repositorio de GitHub del agente.

Estructura del grupo de campos instanceFilter

El grupo de campos instanceFilter indica las VMs en una zona a la que se aplica un filtro. Este grupo de campos es una representación YAML de la estructura InstanceFilter que usa el recurso OSPolicyAssignment en la API de OS Config.

El grupo de campos instanceFilter tiene una de las siguientes estructuras:

  • Para aplicar la política de agente a todas las VMs de una zona, usa lo siguiente:

    instanceFilter:
  all: True

    Si usas el filtro all: True, no puedes especificar cualquier otro criterio.

  • Para aplicar la política de agente a un conjunto específico de VM en una zona, describe las VMs mediante una combinación de cualquiera de las siguientes opciones:

    • Etiquetas en la VM, ya sea para su inclusión o exclusión:
      • inclusionLabels:
      • exclusionLabels:
    • Sistema operativo: inventories:

    Por ejemplo, el siguiente filtro aplica la política de agentes a las VMs con los sistemas operativos especificados que tienen la etiqueta "env=prod" y no tienen la etiqueta "app=web":

    instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  exclusionLabels:
  - labels:
      app: web
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

    Para obtener información sobre cómo encontrar los valores del sistema operativo, consulta Cómo encontrar información del sistema operativo.

Terraform

Para crear una política de agente totalmente personalizada, usa el Módulo ops-agent-policy en modules directorio del repositorio terraform-google-cloud-operations. Este módulo requiere la misma información que gcloud compute instances ops-agents policies create lo requiere. Para obtener una descripción de todos los campos que se usan para describir una política de agente, selecciona la pestaña Línea de comandos.

El directorio examples en el repositorio terraform-google-cloud-operations contiene archivos que proporcionan muchas de las variables que necesita el módulo ops-agent-policy por ti. Para obtener más información, consulta Ejemplos de configuraciones de políticas.

Para aprender a aplicar o quitar un archivo de Terraform, consulta Aspectos básicos de Terraform comandos. Para obtener información sobre cómo funciona Terraform, consulta Cómo usar Terraform.

Verifica el estado de las políticas de agentes

En esta sección, se describe cómo verificar el estado de las políticas creadas y la instalación del Agente de operaciones. Esta información también puede ayudar con solucionar problemas relacionados con las políticas de tu agente.

Página de políticas del SO de Compute Engine

La página Políticas del SO de Compute Engine proporciona información sobre las políticas de agentes que administran el agente de operaciones y sobre las VMs en la pestaña Instancias de VM. Por ejemplo:

  • La columna Estado indica si una política se instaló correctamente (“En cumplimiento”), en curso (“Pendiente”), posiblemente con errores (“Desconocido”) o faltante (“Sin políticas").
  • La columna VM supervisada indica si la configuración del SO administra el agente de operaciones (“Supervisado”) o no (“No supervisado”).

    Si una política es “En cumplimiento”, pero la VM muestra “No supervisado”, es posible que haya un problema para instalar el Agente de operaciones. Por ejemplo, es posible que ya tengas un agente heredado instalado.

En la consola de Google Cloud, ve a la página Políticas del SO:

Ir a Políticas del SO

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Compute Engine.

La pestaña Instancias de VM de la pestaña Políticas del SO de Compute Engine muestra información sobre los agentes que administran todas las políticas del SO en tu proyecto de Google Cloud. Estas políticas están etiquetadas como goog-ops-agent-policy.

  • El indicador goog-ops-agent-policy incluye varios tipos de políticas:

    Para distinguir entre políticas, usa la pestaña Asignaciones de políticas del SO en la página para ver los IDs de políticas de todas las asignaciones de políticas en tu proyecto de Google Cloud.

  • Esta columna Supervisión de VM no refleja la instalación del agente de operaciones por otros medios, como la instalación manual o las políticas del agente beta.

Página Instancias de VM de Cloud Monitoring

La página Instancias de VM en Cloud Monitoring incluye una columna Agente que enumera el agente instalado en cada VM y, para el Agente de operaciones, incluye un indicador del agentes instalados anteriores a la última versión.

En la consola de Google Cloud, ve a la página Instancias de VM:

Ve al Panel de instancias de VM

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

Ejemplos de configuraciones de políticas

En esta sección, se describen ejemplos para configurar políticas de agentes cuando se usa SDK de Google Cloud o Terraform.

Línea de comandos

Ejemplos de archivos de descripción de políticas

Esta sección proporciona algunos ejemplos de archivos YAML de descripción de políticas para en una variedad de situaciones. En los ejemplos, se supone que colocas YAML en un archivo llamado agent-policy-description.yaml y que crea la política en la zona us-central1-a con un comando de la siguiente manera:

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone us-central1-a \
  --file agent-policy-description.yaml \
  --project PROJECT_ID

Instala en todas las VMs

Para instalar la última versión del Agente de operaciones en todas las VMs del us-central1-a, usa la siguiente descripción de política:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  all: True

Quita de todas las VMs

Para quitar la versión más reciente del Agente de operaciones en todas las VMs del us-central1-a, usa la siguiente descripción de política:

agentsRule:
  packageState: removed
  version: latest
instanceFilter:
  all: True

Instala en VMs según las etiquetas

Para instalar la versión más reciente del agente de operaciones en todas las VMs de la zona us-central1-a con la etiqueta “env=prod” o “app=web”, usa la siguiente descripción de política:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  - labels:
      app: web

Cuando especificas varias entradas labels: para su inclusión o exclusión, una VM coincide si alguna de las etiquetas está presente; es decir, los conjuntos de etiquetas para inclusión o exclusión coinciden como una operación OR lógica, no una operación AND lógica.

Instala en VMs basadas en otras etiquetas

Para instalar la última versión del agente de operaciones en todas las VMs de la zona us-central1-a que ejecutan Debian 11, excepto aquellas con las etiquetas “env=prod” y “app=web6”, usa la siguiente descripción de política:

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  exclusionLabels:
  - labels:
      env: prod
      app: web6
  inventories:
  - osShortName: debian
    osVersion: '11'

Cuando especificas varios pares clave-valor en una sola entrada labels: para inclusión o exclusión, una VM coincide si todas las etiquetas están presentes, es decir, las etiquetas coinciden como un operación AND lógica, no una operación OR lógica.

Instala en VMs según el sistema operativo

Para instalar la versión 2 más reciente del agente de operaciones en todas las VMs que ejecutan Debian 11 o RHEL 7.* en la zona us-central1-a, usa la siguiente descripción de política:

agentsRule:
  packageState: installed
  version: 2.*.*
instanceFilter:
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

Terraform

En esta sección, se describen los ejemplos del directorio examples del repositorio terraform-google-cloud-operations. Estos ejemplos contienen archivos que configuran muchas de las variables requeridas por la ops-agent-policy para ti. También puedes copiar y modificar el ejemplos. En todos estos ejemplos, se instala el Agente de operaciones. puedes modificarlas para borrar el agente en su lugar.

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.

Ejemplo: ops_agent_policy_install_all

En este ejemplo, se instala la versión más reciente del Agente de operaciones en todas las VMs aptas de tu proyecto de Google Cloud.

Cuando ejecutas el comando terraform plan o terraform apply, se te solicitan los siguientes valores:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud.

Ejemplo: ops_agent_policy_install_all_in_region

En este ejemplo, se instala la versión más reciente del Agente de operaciones en todas las VM aptas de una región determinada, como us-west1. Una región contiene varias zonas, en este caso, us-west-1a, us-west-1b y us-west-1c.

Cuando ejecutes terraform plan o terraform apply, se te solicitará lo siguiente valores:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud.
  • REGION: Es la región en la que se instalará el agente en las VMs.

Ejemplo: ops_agent_policy_install_all_in_zone

En este ejemplo, se instala la versión más reciente del Agente de operaciones en todos VMs aptas en una zona determinada, como us-central1-a.

Cuando ejecutes terraform plan o terraform apply, se te solicitará lo siguiente valores:

  • PROJECT_ID: El ID de tu proyecto de Google Cloud
  • ZONE: Es la zona en la que se instalará el agente en las VMs.

Soluciona problemas de políticas del agente de DG

En esta sección, encontrarás información que te ayudará a resolver problemas relacionados con Políticas del agente de Google Analytics para el Agente de operaciones. La información que se describe en Cómo verificar el estado de las políticas del agente también podría ser útil.

Los comandos ops-agents policy fallan

Cuando un comando gcloud 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 compute instances ops-agents policies falla con un error de permiso, asegúrate de haber ejecutado la secuencia de comandos prepare-for-ops-agents-policies.sh como se describe en Antes de comenzar para configurar los roles de la política de configuración del SO:

Para obtener más información sobre la secuencia de comandos prepare-for-ops-agents-policies.sh, consulta La secuencia de comandos prepare-for-ops-agents-policies.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 prepare-for-ops-agents-policies.sh. secuencia de comandos, descrita en Antes de comenzar, otorgar todos los permisos necesarios. Si ingresas y en el mensaje de error, aún debes ejecutar la secuencia de comandos prepare-for-ops-agents-policies.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 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 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 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 lo instala el Agente de operaciones

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 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 prepare-for-ops-agents-policies.sh como se describe en Antes de comenzar para establecer la 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'

El agente de operaciones está instalado, pero no funciona de forma correcta

Para obtener más información sobre la depuración de problemas del Agente de operaciones, consulta Cómo solucionar problemas del Agente de operaciones.

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 prepare-for-ops-agents-policies.sh

Después de descargar la secuencia de comandos prepare-for-ops-agents-policies.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 prepare-for-ops-agents-policies.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 prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[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 prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

La secuencia de comandos diagnose_policies.sh

Con un ID del proyecto, un ID de la instancia de Compute Engine, una zona de Compute Engine y el ID de política del agente, la secuencia de comandos diagnose_policies.sh recopila automáticamente la información necesaria para diagnosticar problemas con la política:

  • La versión del agente de configuración del SO
  • La asignación de la política del SO subyacente
  • Las asignaciones de políticas del SO que se aplican Instancia de Compute Engine
  • Una descripción de esta instancia de Compute Engine

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

bash diagnose_policies.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID \
  --zone=ZONE

Precios

Los comandos gcloud compute instances ops-agents policies se implementan con los recursos de asignación de políticas del SO de VM Manager. La secuencia de comandos prepare-for-ops-agents-policies.sh, descrita en Antes de comenzar, configura VM Manager en modo de funciones limitadas (OSCONFIG_B), que es suficiente para crear y administrar políticas de agentes. Sin costo para usar VM Manager en modo limitado.

Si configuraste VM Manager en el modo con todas las funciones (OSCONFIG_C), es posible que se generen costos.