Gérer les stratégies d'agent

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

Systèmes d'exploitation compatibles

Vous pouvez appliquer une règle d'agent aux instances Compute Engine avec les systèmes d'exploitation suivants.

Logging agent correspond aux règles avec le type d'agent logging. Monitoring agent correspond aux règles avec le type d'agent metrics. Ops Agent correspond aux règles avec le type d'agent ops-agent.

OS Agent Logging Agent Monitoring Agent Ops
CentOS 7
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
1
RHEL 8 :
rhel-8, rhel-8-4-sap-ha, rhel-8-6-sap-ha, rhel-8-8-sap-ha
1
Debian 9 (Stretch)
Debian 10 (Buster)
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
OpenSUSE Leap 15 :
opensuse-leap (opensuse-leap-15-3-*,
opensuse-leap-15-4-*)
Windows Server :
2016, 2019, 2022, Core 2016, Core 2019, Core 2022

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

Créer une règle d'agent

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

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

    Dans la CLI gcloud, le groupe de commandes de gestion des règles d'agent est disponible en version beta.

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

    gcloud components install beta
    

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

    gcloud components list
    
    1. 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 la section Quelles sont les actions réalisées par le script set-permissions.sh ?.

  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 de la commande gcloud beta compute instances ops-agents policies create.

    Pour obtenir des exemples de formats de la commande, reportez-vous à la section Exemples de la documentation Google Cloud CLI.

    Pour plus d'informations sur les commandes et les options disponibles de la CLI gcloud, consultez la documentation de gcloud beta compute instances ops-agents policies.

Bonnes pratiques d'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.

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.

Voici un exemple de plan de déploiement par étapes pour les VM CentOS 7 :

Phase 1 : créer une règle pour installer l'agent Ops 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=ops-agent,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=centos,version=7 \
    --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 policies create.

Phase 2 : mettre à jour cette règle pour cibler env=prod et app=myproduct et une seule zone.

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

Limites

Pour qu'une règle prenne effet sur les VM antérieures à OS Config, une configuration supplémentaire est nécessaire pour s'assurer que l'agent OS Config sur lequel cette stratégie repose est installé sur les VM. Pour installer l'agent de configuration du système d'exploitation sur un parc de VM, procédez comme suit :

  1. Assurez-vous d'avoir exécuté le script set-permissions.sh dans la section Créer une règle d'agent.

  2. Déterminez les VM sur lesquelles vous souhaitez installer l'agent OS Config et répertoriez-les dans un fichier CSV.

    Pour obtenir la liste de toutes les instances non gérées par Google (par exemple par Google Kubernetes Engine ou Google App Engine) dans un fichier CSV, exécutez la commande suivante :

      gcloud compute instances list \
          --filter="-labels.list(show="keys"):goog-" \
          --format="csv(name,zone)" \
          | grep -v -x -F -f  <(gcloud compute instances os-inventory list-instances \
              --format="csv(name,zone)") \
          | sed 's/$/,update/' > instances.csv
    

    La section grep filtre les VM sur lesquelles l'agent OS Config est déjà installé et activé. L'exclusion de libellés de VM basée sur goog- filtre les VM Compute Engine gérées par GKE, App Engine, etc.

    Pour filtrer davantage les instances par zones ou par libellés, redéfinissez le --filter sur une valeur semblable à celle-ci :

      "-labels.list(show="keys"):goog- AND zone:(ZONE_1,ZONE_2) AND labels.KEY_1:VALUE_1 AND labels.KEY_2=VALUE_2"
    
  1. Téléchargez et exécutez le script mass-install-osconfig-agent.sh en suivant les instructions du script pour exécuter une commande telle que :

       bash mass-install-osconfig-agent.sh --project project-id --input-file instances.csv
    

    Ce script automatise l'installation de l'agent OS Config.

Dépannage

Échec des commandes de règle ops-agents

Si les commandes de règle ops-agents échouent, elles affichent l'erreur de validation correspondante. 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 s'afficheront peut-être :

  • Autorisation IAM insuffisante

    Voici un exemple d'erreur :

    ERROR: (gcloud.beta.compute.instances.ops-agents.policies.XXX) PERMISSION_DENIED: Caller does not have required permission to XXX
    

    Assurez-vous d'exécuter le script set-permissions.sh de la section Créer une règle d'agent pour configurer le rôle IAM spécifique osconfig.guestPolicy.

    Pour vérifier si vous disposez du rôle de règle d'invité OS Config suffisant pour le projet, vous pouvez exécuter la commande suivante. Dans cet exemple, la commande vérifie si l'utilisateur possède le rôle roles/osconfig.guestPolicyAdmin. GCLOUD_MEMBER doit être au format user:USER_EMAIL ou serviceaccount:SERVICE_ACCOUNT_EMAIL.

    gcloud projects get-iam-policy project-id \
        --filter=--member=gcloud-member \
        | grep "roles/osconfig.guestPolicyAdmin" -B 2
    

    Le résultat attendu est :

    - members:
      - gcloud-member
      role: roles/osconfig.guestPolicyAdmin
    
  • L'API OS Config n'est pas activée

    Voici un exemple d'erreur :

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

    Assurez-vous d'exécuter le script set-permissions.sh de la section Créer une règle d'agent pour accorder toutes les autorisations nécessaires.

    Pour vérifier si l'API OS Config est activée pour le projet, vous pouvez exécuter les commandes suivantes :

    gcloud services list --project project-id \
        | grep osconfig.googleapis.com
    

    Le résultat attendu est :

    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
    

    Cela indique que la règle a déjà été supprimée. Assurez-vous que l'ID de la stratégie dans la commande describe, update ou delete est mappé sur une stratégie existante.

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

L'agent OS Config n'est pas préinstallé sur les instances Compute Engine SUSE et Ubuntu. Vous devez donc suivre ces instructions pour installer l'agent OS Config sur ces instances Compute Engine.

L'agent OS Config est installé, mais il n'installe pas les agents d'exploitation

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. Cette opération s'effectue via l'explorateur de journaux ou via SSH/RDP dans des instances individuelles Compute Engine.

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

resource.type="gce_instance"
logName="projects/project-id/logs/OSConfigAgent"

Pour afficher les journaux de l'agent OS Config via SSH pour des instances Linux Compute Engine individuelles, exécutez la commande suivante :

  • CentOS/RHEL/SLES/SUSE

    gcloud compute ssh instance-id \
        --project project-id \
        -- sudo cat /var/log/messages \
           | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"
    
  • Debian/Ubuntu

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

Pour afficher les journaux de l'agent OS Config via RDP pour des instances Windows Compute Engine individuelles, procédez comme suit :

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

  2. Ouvrez l'application Event Viewer, sous Windows Logs => Application, 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 dans la section Créer une règle d'agent pour configurer les métadonnées.

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 :

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

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

Reportez-vous aux pages de dépannage de l'agent Logging et de l'agent Monitoring pour résoudre les problèmes spécifiques.

Activer les journaux de niveau "Débogage"

Il est très utile d'activer la journalisation au niveau du débogage de 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

Informations supplémentaires

Quelles sont les actions réalisées par le script set-permissions.sh ?

À partir d'un ID de projet, d'un rôle IAM (Identity and Access Management) et d'une adresse e-mail ou d'un compte de service, le script set-permissions.sh effectue les actions suivantes :

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

  • Il accorde les rôles roles/logging.logWriter et roles/monitoring.metricWriter au compte de service Compute Engine par défaut afin que les agents puissent écrire des journaux et des métriques dans les API Logging et Cloud Monitoring.

  • Il définit les métadonnées OS Config pour le projet afin que les agents OS Config soient activés sur les VM.

  • Il attribue le rôle IAM spécifié à l'utilisateur gcloud ou au compte de service. Les propriétaires de projet disposent d'un accès complet pour créer et gérer une règle. Pour tous les autres utilisateurs ou comptes de service, les propriétaires de projet doivent attribuer l'un des rôles suivants :

    • roles/osconfig.guestPolicyAdmin : fournit un accès complet à une règle.

    • roles/osconfig.guestPolicyEditor : permet aux utilisateurs d'obtenir, de mettre à jour et de répertorier une règle.

    • roles/osconfig.guestPolicyViewer : fournit un accès en lecture seule permettant d'obtenir et de répertorier une règle.

    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.

L'appel du script suivant active les API, attribue les rôles nécessaires au compte de service par défaut et active les métadonnées OS Config :

bash set-permissions.sh --project=PROJECT_ID

Pour utiliser le script afin d'accorder l'un des rôles OS Config à un utilisateur qui ne dispose pas du rôle roles/owner (Propriétaire) 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 utiliser le script afin d'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]

Pour en savoir plus, consultez le contenu du script.

Quelles sont les actions réalisées par le script diagnose.sh ?

Avec un projet, un ID d'instance Compute Engine et un ID de règle d'agent d'exploitation, le script diagnose.sh collecte automatiquement les informations nécessaires pour diagnostiquer les problèmes liés à une 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 une instance Compute Engine

Intégration de Terraform

La prise en charge de Terraform repose sur les commandes de Google Cloud CLI. Pour créer une règle d'agent à l'aide de Terraform, suivez les instructions du module Terraform.