Utiliser les règles d'agent

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les règles d'agent permettent l'installation et la maintenance automatiques des agents Google Cloud Observability sur un parc de VM Compute Engine correspondant aux critères spécifiés par l'utilisateur. Vous pouvez créer une règle pour un projet Google Cloud qui régit les VM nouvelles et existantes associées à ce projet Google Cloud, afin d'assurer l'installation, la désinstallation et la mise à niveau automatique facultative de tous les agents Google Cloud Observability sur ces VM.

Vous créez et gérez des règles d'agent à l'aide du groupe de commandes gcloud beta compute instances ops-agents policies dans la Google Cloud CLI ou du module Terraform agent-policy. Les règles d'agent 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 les agents Google Cloud Observability: l'agent Ops, l'ancien agent Monitoring et l'ancien agent Logging.

Systèmes d'exploitation compatibles

Vous pouvez appliquer une règle d'agent aux instances de VM Compute Engine exécutant les systèmes d'exploitation indiqués dans le tableau suivant:

Système d'exploitation	Agent Ops (règles DG et bêta^†)	Agent Logging (règles bêta^† uniquement)	Agent de surveillance (règles bêta^† uniquement)
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 basées sur 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

^†  Dans les règles d'agent bêta, les colonnes de l'agent correspondent à un type d'agent spécifié dans l'appel gcloud beta compute instances ops-agents policies create :

• L'agent Ops correspond au type d'agent ops-agent.
• L'agent Logging correspond au type d'agent logging.
• L'agent Monitoring correspond au type d'agent metrics.

^‡ L'agent Monitoring n'est pas compatible avec rhel-7-9-sap-ha, rhel-8-2-sap-ha ou rhel-8-4-sap-ha.

Créer une règle d'agent

Cette section explique comment utiliser Google Cloud SDK pour gérer les règles des agents. Pour en savoir plus sur l'utilisation de Terraform, consultez la section Intégration de Terraform.

Pour créer une règle d'agent à l'aide de Google Cloud CLI, procédez comme suit:

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

   Les règles d'agent décrites dans ce document utilisent le groupe de commandes beta.

2. Si vous ne l'avez pas déjà fait, installez le composant beta de gcloud CLI :

   gcloud components install beta
   

   Pour vérifier si le composant beta est installé, exécutez la commande suivante :

   gcloud components list
   

   Si vous avez déjà installé le composant beta, assurez-vous de disposer de la dernière version :

   gcloud components update
   

3. Utilisez le script suivant pour activer les API et définir les autorisations permettant d'utiliser Google Cloud CLI : set-permissions.sh.

   Pour en savoir plus sur ce script, consultez Le script set-permissions.sh.

   Remarque : Le script set-permissions.sh est conçu pour s'exécuter sous Linux. Si vous utilisez une machine disposant d'un système d'exploitation différent, exécutez le script à partir de Cloud Shell.

4. Pour créer une règle, utilisez la commande gcloud beta compute instances ops-agents policies create. Pour en savoir plus sur la syntaxe, consultez la documentation sur gcloud beta compute instances ops-agents policies create.

   Pour obtenir des exemples de formats de la commande, consultez la section Exemples de la documentation Google Cloud CLI.

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

Bonnes pratiques relatives à l'utilisation des règles d'agent

Pour contrôler l'impact du déploiement sur les systèmes de production, nous vous recommandons de spécifier des étiquettes d'instances et des zones afin de filtrer les instances auxquelles la règle s'applique.

Voici un exemple de plan de déploiement par étapes pour les VM Debian 11 dans un projet appelé my_project:

Phase 1 : créer une règle nommée ops-agents-policy-safe-rollout pour installer les anciens agents Logging et Monitoring sur toutes les VM portant les étiquettes env=test et 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

Pour en savoir plus sur la spécification du système d'exploitation, consultez la page gcloud beta compute instances ops-agents policiescreate.

Phase 2: mettre à jour cette règle pour cibler les VM d'une seule zone portant les étiquettes env=prod et 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 \

Phase 3 : mettre à jour cette règle pour effacer le filtre des zones et la déployer globalement.

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

Règles sur les VM antérieures à OS Config

Vous devrez peut-être installer et configurer manuellement l'agent OS Config sur les VM antérieures à OS Config. Pour savoir comment installer et valider manuellement l'agent OS Config, consultez la checklist de validation de VM Manager.

Résoudre les problèmes liés aux règles d'agent bêta

Cette section fournit des informations pour vous aider à résoudre les problèmes liés aux règles d'agent bêta pour l'agent Ops, l'ancien agent Monitoring et l'ancien agent Logging.

Échec des commandes ops-agents policy

Lorsqu'une commande gcloud beta 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, les erreurs suivantes peuvent s'afficher:

• Autorisation IAM insuffisante
• L'API OS Config n'est pas activée
• La règle spécifiée n'existe pas

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

Autorisation IAM insuffisante

Si une commande gcloud beta compute instances ops-agents policies échoue et affiche une erreur d'autorisation, assurez-vous d'avoir exécuté le script set-permissions.sh comme décrit dans la section Créer une règle d'agent pour configurer les rôles de règle OS Config:

• Administrateur GuestPolicy (roles/osconfig.guestPolicyAdmin) : permet d'accéder entièrement aux règles d'invité.
• Éditeur GuestPolicy (roles/osconfig.guestPolicyEditor) : permet aux utilisateurs d'obtenir, de mettre à jour et de répertorier les règles d'invité.
• Lecteur GuestPolicy (roles/osconfig.guestPolicyViewer) : permet d'obtenir et de répertorier les règles d'invité en lecture seule.

Pour en savoir plus sur le script set-permissions.sh, consultez Le script set-permissions.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 set-permissions.sh, décrit dans la section Créer une règle d'agent, afin d'accorder toutes les autorisations nécessaires. Si vous saisissez y à l'invite du message d'erreur, vous devez toujours exécuter le script set-permissions.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 existe déjà

Voici un exemple d'erreur:

ALREADY_EXISTS: Requested entity already exists

Cette erreur signifie que cette règle existe déjà avec le même nom, le même ID de projet et la même région. Vous pouvez le vérifier à l'aide de la commande describe gcloud beta compute instances ops-agents policies.

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 POLICY_ID utilisée dans une commande gcloud beta 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 list gcloud beta compute instances ops-agents policies.

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 qui n'est pas 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 manuellement l'agent OS Config.

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

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. Pour ce faire, vous pouvez utiliser l'explorateur de journaux, ou SSH ou RDP pour vérifier des 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 set-permissions.sh comme décrit dans la section Créer une règle d'agent 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'

Les agents d'observabilité sont installés, mais ne fonctionnent pas correctement

Pour en savoir plus sur le débogage d'agents spécifiques, consultez les documents suivants:

• Résoudre les problèmes liés à l'agent Ops
• Résoudre les problèmes liés à l'ancien agent Logging
• Résoudre les problèmes liés à l'ancien agent Monitoring

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 set-permissions.sh
• Le script diagnose.sh

Script set-permissions.sh

Après avoir téléchargé le script set-permissions.sh, vous pouvez l'utiliser pour effectuer les actions suivantes, en fonction des arguments que vous fournissez:

• Activez l'API Cloud Logging, l'API Cloud Monitoring et l'API OS Config pour le projet.

• Accordez les rôles Identity and Access Management Rédacteur de journaux (roles/logging.logWriter) et Rédacteur de métriques Monitoring (roles/monitoring.metricWriter) au compte de service par défaut Compute Engine afin que les agents puissent écrire des journaux et des métriques dans les API Logging and Cloud Monitoring.

• Activez les métadonnées OS Config pour le projet afin que l'agent OS Config sur chaque VM soit actif.

• Attribuez l'un des rôles IAM suivants à l'utilisateur ou au compte de service non propriétaire nécessaire pour créer et gérer des stratégies. Les propriétaires de projet disposent d'un accès complet pour créer et gérer des règles ; tous les autres utilisateurs ou comptes de service doivent disposer de l'un des rôles suivants:

  • Administrateur GuestPolicy (roles/osconfig.guestPolicyAdmin) : permet d'accéder entièrement aux règles d'invité.
  • Éditeur GuestPolicy (roles/osconfig.guestPolicyEditor) : permet aux utilisateurs d'obtenir, de mettre à jour et de répertorier les règles d'invité.
  • Lecteur GuestPolicy (roles/osconfig.guestPolicyViewer) : permet d'obtenir et de répertorier les règles d'invité en lecture seule.

  Lors de l'exécution du script, il vous suffit de spécifier la partie guestPolicy* du nom du rôle. Le script fournit la partie roles/osconfig. du nom.

Les exemples suivants illustrent certaines invocations courantes du script. Pour en savoir plus, consultez les commentaires dans le script lui-même.

Pour activer les API, accorder 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 set-permissions.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 set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[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 set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

Script diagnose.sh

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

• Version de l'agent OS Config
• Règle d'invité OS Config sous-jacente
• Règles applicables à cette instance Compute Engine
• Dépôts de packages de l'agent, qui sont extraits vers cette instance Compute Engine

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

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

Intégration de Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base. Pour en savoir plus sur le fonctionnement de Terraform, consultez la section Utiliser Terraform.

La prise en charge de Terraform pour les règles de l'agent repose sur les commandes de la Google Cloud CLI. Pour créer une règle d'agent à l'aide de Terraform, suivez les instructions du module Terraform agent-policy. Vous trouverez également des exemples de règles dans le répertoire examples.