Utiliser des règles d'agent (DG)

Vous créez et gérez des règles d'agent à l'aide du groupe de commandes gcloud compute instances ops-agents policies dans Google Cloud CLI. Les commandes de ce groupe utilisent la suite d'outils VM Manager de Compute Engine pour gérer les règles d'OS, ce qui peut automatiser le déploiement et la maintenance de configurations logicielles comme l'agent Ops. Ces règles ne peuvent pas être appliquées à l'ancien agent Monitoring, ni à l'ancien agent Logging.

Le groupe de commandes gcloud compute instances ops-agents policies utilise des ressources d'attribution de règles d'OS dans l'API OS Config. Bien qu'il existe un groupe de commandes général gcloud CLI pour gérer les attributions de règles d'OS, gcloud compute os-config os-policy-assignments, le groupe de commandes gcloud compute instances ops-agents policies est conçu spécifiquement pour les règles d'agent décrites dans ce document.

Avant de commencer

Avant d'utiliser Google Cloud CLI pour créer des règles d'agent, procédez comme suit :

  1. Si vous ne l'avez pas déjà fait, installez Google Cloud CLI.

  2. Téléchargez et exécutez le script prepare-for-ops-agents-policies.sh pour activer les API requises et définir les autorisations appropriées pour utiliser Google Cloud CLI.

    Pour en savoir plus sur ce script, consultez la section Script prepare-for-ops-agents-policies.sh.

Désinstaller les anciens agents Monitoring et Logging

Si vous créez une règle pour l'agent Ops, assurez-vous que l'ancien agent Logging ou Monitoring n'est pas installé sur vos VM. L'exécution de l'agent Ops et des anciens agents sur la même VM peut entraîner l'ingestion de journaux en double ou créer un conflit dans l'ingestion des métriques. Si nécessaire, désinstallez l'agent Monitoring et désinstallez l'agent Logging avant de créer une règle pour installer l'agent Ops.

Vérifier que l'agent OS Config est installé

Vous devrez peut-être installer et configurer manuellement l'agent OS Config sur les VM antérieures à OS Config. Pour en savoir plus sur l'installation et la vérification manuelles de l'agent OS Config, consultez la checklist de vérification de VM Manager.

Créer une règle d'agent pour gérer l'Agent Ops

Pour créer une règle d'agent, utilisez la commande gcloud compute instances ops-agents policiescreate. La structure de cette commande est la suivante:

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

Lorsque vous utilisez cette commande, remplacez les variables comme suit:

  • POLICY_ID est le nom de votre règle.
  • ZONE correspond à une zone Compute Engine. Les règles d'agent ne sont appliquées qu'aux VM de la zone spécifiée ; pour appliquer une règle dans plusieurs zones, vous devez créer plusieurs règles.
  • path/to/policy-description-file.yaml est le chemin d'accès à un fichier YAML décrivant la règle. Pour en savoir plus sur la structure de ce fichier, consultez la section Décrire les règles d'agent.
  • PROJECT_ID est l'ID du projet Google Cloud.

Pour en savoir plus sur les autres commandes du groupe de commandes et les options disponibles, consultez la documentation de gcloud compute instances ops-agents policies.

Décrire les règles d'agent

Fournissez les informations de règle au gcloud compute instances ops-agents policies create en créant un fichier YAML décrivant la stratégie et en le transmettant à la commande en tant que valeur de l'option --file.

Cette section décrit la structure du fichier de description des règles. Pour en savoir plus, consultez la section Exemples de fichiers de description de règle.

Format du fichier de description de la règle YAML

Le fichier de description d'une règle d'agent doit inclure deux groupes de champs:

  • agentsRule, qui indique à la règle d'agent si elle doit installer ou supprimer l'Agent Ops, et spécifie la version de l'agent Ops sur laquelle effectuer des opérations.

  • instanceFilter, qui décrit les VM auxquelles la règle s'applique.

Structure du groupe de champs agentsRule

Le groupe de champs agentsRule présente la structure suivante:

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y
  • Le champ packageState indique à la stratégie l'état souhaité de l'agent Ops. Les valeurs valides sont installed et removed.

  • Le champ version indique la version de l'agent Ops à installer ou à supprimer. Vous pouvez spécifier les valeurs suivantes :

    • latest est la version la plus récente de l'agent Ops.
    • 2.*.* est la version la plus récente de la version majeure 2 de l'agent Ops.
    • 2.x.y indique une version spécifique de la version majeure 2.

    Pour en savoir plus sur les versions disponibles de l'agent Ops, consultez le dépôt GitHub de l'agent.

Structure du groupe de champs instanceFilter

Le groupe de champs instanceFilter indique les VM d'une zone à laquelle le filtre s'applique. Ce groupe de champs est une représentation YAML de la structure InstanceFilter utilisée par la ressource OSPolicyAssignment de l'API OS Config.

Le groupe de champs instanceFilter présente l'une des structures suivantes :

  • Pour appliquer la règle d'agent à toutes les VM d'une zone, utilisez ce qui suit :

    instanceFilter:
  all: True

    Si vous utilisez le filtre all: True, vous ne pouvez spécifier aucun autre critère.

  • Pour appliquer la règle d'agent à un ensemble spécifique de VM dans une zone, décrivez les VM en combinant l'un des éléments suivants:

    • Libellés sur la VM, pour inclusion ou exclusion :
      • inclusionLabels:
      • exclusionLabels:
    • Système d'exploitation : inventories:

    Par exemple, le filtre suivant applique la règle de l'agent aux VM avec les systèmes d'exploitation spécifiés qui ont le libellé "env=prod" et ne portent pas le libellé "app=web" :

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

    Pour trouver les valeurs des champs osShortName et osVersion d'une VM, utilisez les commandes suivantes :

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

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

    Ces commandes nécessitent que l'agent OS Config soit installé sur la VM.

Vérifier l'état des règles de l'agent

Cette section explique comment vérifier l'état des règles créées et l'installation de l'agent Ops. Ces informations peuvent également vous aider à dépanner vos règles d'agent.

Page Règles d'OS de Compute Engine

La page Règles d'OS de Compute Engine fournit des informations sur les règles d'agent qui gèrent l'agent Ops et sur les VM dans l'onglet Instances de VM. Exemple :

  • La colonne State (État) indique si une règle a été ou non installée avec succès ("Compliant"), est en cours ("Pending"), a peut-être échoué ("Unknown") ou est manquante ("No policies").
  • La colonne VM monitored (VM surveillée) indique si l'agent Ops est géré par OS Config ("Monitored") ou non ("Not monitored").

    Si une règle est "Compliant" (Conforme), mais que la VM affiche "Not monitored" (Non surveillée), il est possible qu'un problème soit survenu lors de l'installation de l'agent Ops. Par exemple, il se peut qu'un ancien agent soit déjà installé.

Dans la console Google Cloud, accédez à la page Règles d'OS.

Accéder aux règles d'OS

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Compute Engine.

Les instances de VM de l'onglet Règles d'OS de Compute Engine affichent des informations sur les agents gérés par toutes les règles d'OS de votre projet Google Cloud. Ces règles sont identifiées par le libellé goog-ops-agent-policy.

  • L'indicateur goog-ops-agent-policy inclut plusieurs types de règles :

    Pour distinguer les règles, utilisez l'onglet Attributions de règles d'OS de la page afin d'afficher les ID de toutes les attributions de règles dans votre projet Google Cloud.

  • La colonne VM surveillée ne reflète pas l'installation de l'agent Ops par d'autres moyens, comme une installation manuelle ou par des règles d'agent bêta.

Page Instances de VM de Cloud Monitoring

La page Instances de VM dans Cloud Monitoring inclut une colonne Agent qui liste l'agent installé sur chaque VM et, pour l'agent Ops, elle inclut un indicateur pour les agents installés qui sont antérieurs à la dernière version.

Dans la console Google Cloud, accédez à la page Tableau de bord des instances de VM :

Accéder au tableau de bord des instances de VM

Si vous utilisez la barre de recherche pour trouver cette page, sélectionnez le résultat dont le sous-titre est Surveillance.

Exemples de fichiers de description de règles

Cette section fournit des exemples de fichiers de description de règle YAML pour divers scénarios. Les exemples supposent que vous placez le fichier YAML dans un fichier nommé agent-policy-description.yaml et que vous créez la règle dans la zone us-central1-a à l'aide d'une commande semblable à la suivante :

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

Installer sur toutes les VM

Pour installer la dernière version de l'agent Ops sur toutes les VM de la zone us-central1-a, utilisez la description de règle suivante:

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

Supprimer de toutes les VM

Pour supprimer la dernière version de l'Agent Ops sur toutes les VM de la zone us-central1-a, utilisez la description de règle suivante :

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

Installer sur des VM en fonction des libellés

Pour installer la dernière version de l'Agent Ops sur toutes les VM de la zone us-central1-a avec le libellé "env=prod" ou "app=web", utilisez la description de règle suivante :

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

Lorsque vous spécifiez plusieurs entrées labels: pour l'inclusion ou l'exclusion, une VM correspond si l'un des libellés est présent. Autrement dit, les ensembles de libellés pour l'inclusion ou l'exclusion sont mis en correspondance en tant qu'opération OR logique, et non en tant qu'opération AND logique.

Installer sur des VM basées sur d'autres libellés

Pour installer la dernière version de l'Agent Ops sur toutes les VM de la zone us-central1-a exécutant Debian 11, à l'exception de celles portant les libellés "env=prod" et "app=web6", utilisez la description de règle suivante :

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

Lorsque vous spécifiez plusieurs paires clé/valeur sous une même entrée labels: pour l'inclusion ou l'exclusion, une VM correspond si tous les libellés sont présents. Autrement dit, les libellés sont mis en correspondance en tant qu'opération AND operation, et non en tant qu'opération OR logique.

Installation sur des VM en fonction du système d'exploitation

Pour installer la dernière version 2 de l'agent Ops sur toutes les VM exécutant Debian 11 ou RHEL 7.* dans la zone us-central1-a, utilisez la description de règle suivante:

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

Résoudre les problèmes liés aux règles d'agent DG

Cette section fournit des informations pour vous aider à résoudre les problèmes liés aux règles d'agent DG pour l'agent Ops. Les informations décrites dans Vérifier l'état des règles concernant les agents peuvent également vous être utiles.

Échec des commandes ops-agents policy

Lorsqu'une commande gcloud compute instances ops-agents policies échoue, la réponse affiche une erreur de validation. Corrigez ces erreurs en corrigeant les arguments de commande et les options, comme indiqué par le message d'erreur.

Outre les erreurs de validation, des erreurs peuvent indiquer les conditions suivantes:

Les sections suivantes décrivent ces conditions plus en détail.

Autorisation IAM insuffisante

Si une commande gcloud compute instances ops-agents policies échoue avec une erreur d'autorisation, assurez-vous d'avoir exécuté le script prepare-for-ops-agents-policies.sh comme décrit dans la section Avant de commencer. Pour configurer les rôles OS Config, procédez comme suit:

Pour en savoir plus sur le script prepare-for-ops-agents-policies.sh, consultez Le script prepare-for-ops-agents-policies.sh.

L'API OS Config n'est pas activée

Voici un exemple d'erreur:

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)?

Vous pouvez entrer y pour activer l'API, ou vous pouvez exécuter le script prepare-for-ops-agents-policies.sh, décrit dans Avant de commencer, afin d'accorder toutes les autorisations requises. Si vous saisissez y à l'invite du message d'erreur, vous devez quand même exécuter le script prepare-for-ops-agents-policies.sh pour définir les autorisations requises.

Pour vérifier que l'API OS Config est activée pour le projet, exécutez les commandes suivantes:

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

Le résultat attendu est le suivant:

osconfig.googleapis.com    Cloud OS Config API

La règle n'existe pas

Voici un exemple d'erreur:

NOT_FOUND: Requested entity was not found

Cette erreur peut signifier que la règle n'a jamais été créée, qu'elle a été supprimée ou que l'ID de règle spécifié est incorrect. Assurez-vous que la valeur POLICY_ID utilisée dans une commande gcloud compute instances ops-agents policies describe, update ou delete correspond à une stratégie existante. Pour obtenir la liste des règles d'agent, utilisez la commande gcloud compute instances ops-agents policies list.

La règle est créée, mais elle semble n'avoir aucun effet

Les agents OS Config sont déployés sur chaque instance Compute Engine afin de gérer les packages pour les agents Logging et Monitoring. Cette règle peut sembler sans effet si l'agent OS Config sous-jacent n'est pas installé.

Linux

Pour vérifier que l'agent OS Config est installé, exécutez la commande suivante :

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

Voici un exemple de sortie :

    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

Pour vérifier que l'agent OS Config est installé, exécutez la commande suivante :

  1. Connectez-vous à votre instance via RDP ou un outil similaire, et connectez-vous à Windows.

  2. Ouvrez un terminal PowerShell, puis exécutez la commande PowerShell suivante. Vous n'avez pas besoin de droits d'administrateur.

    Get-Service google_osconfig_agent

Voici un exemple de sortie :

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

Si l'agent OS Config n'est pas installé, vous utilisez peut-être un système d'exploitation non compatible avec VM Manager. Le document Détails des systèmes d'exploitation de Compute Engine indique les fonctionnalités de VM Manager compatibles avec chaque système d'exploitation Compute Engine.

Si le système d'exploitation est compatible avec VM Manager, vous pouvez installer l'agent OS Config manuellement.

L'agent OS Config est installé, mais n'installe pas l'agent Ops

Pour vérifier si des erreurs se produisent lorsque l'agent OS Config applique des règles, vous pouvez consulter le journal de l'agent OS Config. Vous pouvez le faire à l'aide de l'explorateur de journaux ou en utilisant SSH ou RDP pour vérifier les instances Compute Engine individuelles.

Pour afficher les journaux de l'agent OS Config dans l'explorateur de journaux, utilisez le filtre suivant :

resource.type="gce_instance"
logId(OSConfigAgent)

Pour afficher les journaux de l'agent OS Config, procédez comme suit:

CentOS, RHEL,
SLES, SUSE

Exécutez la commande suivante : 

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

Debian, Ubuntu

Exécutez la commande suivante : 

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

Windows

  1. Connectez-vous à votre instance via RDP ou un outil similaire, et connectez-vous à Windows.

  2. Ouvrez l'application Event Viewer, puis sélectionnez Windows Logs > Application (Journaux Windows > Application), et recherchez les journaux pour lesquels Source est égal à OSConfigAgent.

Si une erreur s'est produite lors de la connexion au service OS Config, assurez-vous d'exécuter le script prepare-for-ops-agents-policies.sh comme décrit dans la section Avant de commencer pour configurer les métadonnées de OS Config.

Pour vérifier que les métadonnées OS Config sont activées, exécutez la commande suivante :

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

Le résultat attendu est le suivant:

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

L'agent Ops est installé, mais ne fonctionne pas correctement

Pour en savoir plus sur le débogage des problèmes liés à l'agent Ops, consultez Résoudre les problèmes liés à l'agent Ops.

Activer les journaux de niveau débogage pour l'agent OS Config

Il peut être utile d'activer la journalisation de niveau débogage dans l'agent OS Config lorsque vous signalez un problème.

Vous pouvez définir les métadonnées osconfig-log-level: debug pour activer la journalisation au niveau du débogage pour l'agent OS Config. Les journaux collectés contiennent plus d'informations pour faciliter l'investigation.

Afin d'activer la journalisation au niveau du débogage pour l'ensemble du projet, exécutez la commande suivante :

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

Pour activer la journalisation au niveau du débogage sur une VM, exécutez la commande suivante :

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

Scripts d'aide

Cette section fournit des informations supplémentaires sur les scripts d'assistance décrits dans ce document :

Le script prepare-for-ops-agents-policies.sh

Une fois que vous avez téléchargé le script prepare-for-ops-agents-policies.sh, vous pouvez l'utiliser pour effectuer les actions suivantes, en fonction des arguments que vous fournissez :

Les exemples suivants illustrent quelques appels courants du script. Pour en savoir plus, consultez les commentaires dans le script lui-même.

Pour activer les API, attribuer les rôles nécessaires au compte de service par défaut et activer les métadonnées OS Config pour un projet, exécutez le script comme suit :

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID

Pour en plus accorder l'un des rôles OS Config à un utilisateur qui ne dispose pas du rôle Propriétaire (roles/owner) sur le projet, exécutez le script comme suit :

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

Pour en plus accorder l'un des rôles OS Config à un compte de service autre que celui par défaut, exécutez le script comme suit :

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

Le script diagnose_policies.sh

À partir d'un ID de projet, d'un ID d'instance Compute Engine, d'une zone Compute Engine et de l'ID de règle de l'agent, le script diagnose_policies.sh collecte automatiquement les informations nécessaires pour diagnostiquer les problèmes liés à la stratégie:

  • Version de l'agent OS Config
  • L'attribution des règles d'OS sous-jacentes
  • Attributions de règles d'OS applicables à cette instance Compute Engine
  • Description de cette instance Compute Engine

Pour appeler le script, exécutez la commande suivante:

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

Tarifs

Les commandes gcloud compute instances ops-agents policies sont implémentées à l'aide des ressources d'attribution de règles d'OS de VM Manager. Le script prepare-for-ops-agents-policies.sh, décrit dans Avant de commencer, configure VM Manager dans le mode de fonctionnalité limitée (OSCONFIG_B), qui suffit pour créer et gérer les règles d'agent. L'utilisation de VM Manager en mode limité est gratuite.

Si vous avez configuré VM Manager en mode complet (OSCONFIG_C), vous risquez de générer des frais.