Afficher les données personnalisées des règles d'OS pour votre organisation

Ce document explique comment utiliser VM Manager, l'inventaire des éléments cloud et BigQuery pour afficher les données personnalisées et les messages d'erreur d'application des règles d'OS dans votre organisation. Utilisez ce workflow lorsque vous avez besoin de générer des rapports à l'échelle de l'organisation sur les configurations de VM personnalisées, les sorties de script ou les échecs d'exécution des règles que les états de conformité standards ne capturent pas.

Pour collecter des données personnalisées, vous configurez un outputFilePath dans votre règle de système d'exploitation. Il s'agit du chemin d'accès local sur la VM où votre script de règle écrit du texte personnalisé ou une sortie JSON. VM Manager lit le résultat de ce chemin d'accès et le stocke dans le rapport d'attribution de règles d'OS. Vous pouvez ensuite exporter ces rapports vers BigQuery en utilisant l'inventaire des éléments cloud pour interroger les résultats sur l'ensemble de votre parc de VM.

Avant de commencer

Rôles requis

Pour obtenir les autorisations nécessaires pour exporter des données de ressources vers BigQuery et interroger des données de règles personnalisées du système d'exploitation, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet, le dossier ou l'organisation :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour exporter les données de ressources vers BigQuery et interroger les données personnalisées sur les règles du système d'exploitation. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour exporter les données de ressources vers BigQuery et interroger les données personnalisées des règles du système d'exploitation :

  • cloudasset.assets.exportOSInventories
  • cloudasset.assets.exportResource
  • bigquery.datasets.get
  • bigquery.tables.create
  • bigquery.tables.update
  • bigquery.tables.get
  • bigquery.jobs.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Exemples de règles d'OS

Avant de pouvoir exporter et interroger des données personnalisées dans BigQuery, vous devez créer et attribuer une règle OS qui collecte les sorties personnalisées de vos VM. Pour en savoir plus, consultez Créer une attribution de règles d'OS.

Pour collecter des données personnalisées, définissez une règle d'OS avec une ressource exec qui inclut les sections suivantes :

  • validate : vérifie si la VM correspond à l'état sélectionné. Dans les exemples de règles suivants, le script validate se termine avec le code 101 pour indiquer que la ressource ne correspond pas à l'état sélectionné. Ce code de sortie déclenche le script enforce à chaque évaluation.
  • enforce : spécifie le champ outputFilePath, exécute la commande personnalisée, écrit le résultat dans le chemin d'accès spécifié et quitte avec le code 100 pour indiquer que l'application a réussi.

Règle d'OS qui génère une chaîne

L'exemple suivant de résultat de la stratégie OS génère une chaîne contenant la version du noyau de l'instance de VM :

id: return-kernel-version-policy
mode: ENFORCEMENT
resourceGroups:
  - resources:
      id: return-kernel-version
      exec:
        validate:
          interpreter: SHELL
          script: exit 101
        enforce:
          interpreter: SHELL
          outputFilePath: policy-output.txt
          script: uname -r > policy-output.txt && exit 100

Règle du système d'exploitation qui génère un fichier JSON

L'exemple de règle de système d'exploitation suivant génère un objet JSON contenant le nom du système d'exploitation et la version du noyau :

id: return-kernel-version-js-policy
mode: ENFORCEMENT
resourceGroups:
  - resources:
      id: return-kernel-version-js
      exec:
        validate:
          interpreter: SHELL
          script: exit 101
        enforce:
          interpreter: SHELL
          outputFilePath: policy-output.json
          script: |-
            k=$(uname -r)
            o=$(uname -a)
            echo "{ \"name\": \""$o"\", \"kernel\": \""$k"\" }" > policy-output.json
            exit 100

Exporter les données VM Manager vers BigQuery

Une fois que VM Manager a appliqué votre règle d'OS, inventaire des éléments cloud collecte les rapports d'inventaire d'OS et d'attribution de règles d'OS résultants dans votre organisation. Lorsque vous exportez ces données vers BigQuery avec l'indicateur --per-asset-type, inventaire des éléments cloud crée une table distincte pour chaque type d'actif. La table <prefix>_osconfig_googleapis_com_OSPolicyAssignmentReport résultante stocke les résultats de vos règles personnalisées et les messages d'erreur liés à l'application.

Pour exporter les données d'inventaire et de ressources de l'OS vers BigQuery, procédez comme suit :

  1. Pour identifier l'ID d'organisation, exécutez la commande suivante :

    gcloud projects get-ancestors PROJECT_ID

    Remplacez PROJECT_ID par l'ID du projet.

  2. Pour exporter les données d'inventaire du système d'exploitation que VM Manager collecte à partir de vos instances de VM, exécutez la commande suivante :

    gcloud asset export \
    --content-type=os-inventory \
    --organization=ORGANIZATION_ID \
    --per-asset-type \
    --bigquery-table="projects/BQ_PROJECT_ID/datasets/DATASET_ID/tables/os"

    Remplacez les espaces réservés suivants par vos valeurs :

    • ORGANIZATION_ID : ID de votre organisation.
    • BQ_PROJECT_ID : ID du projet contenant votre ensemble de données BigQuery.
    • DATASET_ID : ID de votre ensemble de données BigQuery (par exemple, cai_exp).

  3. Pour exporter les métadonnées de ressources, y compris les rapports d'attribution de règles d'OS, vers BigQuery, exécutez la commande suivante :

    gcloud asset export \
    --content-type=resource \
    --organization=ORGANIZATION_ID \
    --per-asset-type \
    --bigquery-table="projects/BQ_PROJECT_ID/datasets/DATASET_ID/tables/res"

    Remplacez les espaces réservés suivants par vos valeurs :

    • ORGANIZATION_ID : votre ID d'organisation.
    • BQ_PROJECT_ID : ID du projet contenant votre ensemble de données BigQuery.
    • DATASET_ID : ID de votre ensemble de données BigQuery (par exemple, cai_exp).

    Une fois l'exportation terminée, l'inventaire des éléments cloud crée la table res_osconfig_googleapis_com_OSPolicyAssignmentReport dans votre ensemble de données BigQuery. Pour en savoir plus, consultez Exporter un instantané d'asset.

Interroger les données de règles d'OS personnalisées dans BigQuery

Une fois que vous avez exporté vos données d'éléments vers BigQuery, vous pouvez interroger la table res_osconfig_googleapis_com_OSPolicyAssignmentReport pour afficher les résultats personnalisés et les messages d'erreur d'application de vos règles OS.

Pour exécuter une requête dans BigQuery, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans l'éditeur de requête, collez l'une des requêtes SQL suivantes :

    • Sortie du texte de la requête :

      La requête suivante renvoie la version du noyau que la règle d'OS collecte pour chaque instance de VM :

      SELECT
  resource.data.instance as instance,
  ANY_VALUE(
    SAFE_CONVERT_BYTES_TO_STRING(FROM_BASE64(REPLACE(REPLACE(
      resource_compliances.execResourceOutput.enforcementOutput
      , '-', '+'), '_', '/')))
    HAVING MAX updateTime) as compliance_results
FROM
  `DATASET_ID.res_osconfig_googleapis_com_OSPolicyAssignmentReport`,
  UNNEST(resource.data.osPolicyCompliances[OFFSET(0)].osPolicyResourceCompliances) as resource_compliances,
  UNNEST(resource_compliances.configSteps) as config_steps
WHERE
  resource.data.osPolicyCompliances[OFFSET(0)].osPolicyId = "return-kernel-version-policy"
  AND resource_compliances.osPolicyResourceId = "return-kernel-version"
  AND config_steps.type = "VALIDATION"
GROUP BY
  instance

      Remplacez DATASET_ID par l'ID de votre ensemble de données BigQuery (par exemple, cai_exp).

      Le résultat de la requête se présente comme suit :

      instance compliance_results
      ubuntu-1 5.15.0-1036-gcp
      ubuntu-2 5.15.0-1044-gcp
      rhel9-1 5.14.0-162.18.1.el9_1.x86_64

    • Sortie JSON de la requête :

      La requête suivante extrait les champs name et kernel de la sortie JSON et les renvoie sous forme de colonnes distinctes pour chaque instance de VM :

      WITH compliance_history AS (
  SELECT
    updateTime,
    resource.data.instance,
    SAFE_CONVERT_BYTES_TO_STRING(
      FROM_BASE64(
        REPLACE(
          REPLACE(
            resource_compliances.execResourceOutput.enforcementOutput, '-', '+'
          ), '_', '/'
        )
      )
    ) as compliance_results
  FROM
    `DATASET_ID.res_osconfig_googleapis_com_OSPolicyAssignmentReport`,
    UNNEST(resource.data.osPolicyCompliances[OFFSET(0)].osPolicyResourceCompliances) as resource_compliances,
    UNNEST(resource_compliances.configSteps) as config_steps
  WHERE
    resource.data.osPolicyCompliances[OFFSET(0)].osPolicyId = "return-kernel-version-js-policy"
    AND resource_compliances.osPolicyResourceId = "return-kernel-version-js"
    AND config_steps.type = "VALIDATION"
),
compliance_latest AS (
  SELECT
    instance,
    ANY_VALUE(compliance_results HAVING MAX updateTime) as compliance_results
  FROM compliance_history
  GROUP BY instance
)
SELECT
  instance,
  JSON_EXTRACT_SCALAR(compliance_results, "$.name") as os_name,
  JSON_EXTRACT_SCALAR(compliance_results, "$.kernel") as kernel_version
FROM compliance_latest

      Remplacez DATASET_ID par l'ID de votre ensemble de données BigQuery (par exemple, cai_exp).

      Le résultat de la requête se présente comme suit :

      instance os_name kernel_version
      ubuntu-1 Linux ubuntu-1 5.15.0-1036-gcp #39-Ubuntu SMP 5.15.0-1036-gcp
      rhel9-1 Linux rhel9-1 5.14.0-162.18.1.el9_1.x86_64 #1 SMP 5.14.0-162.18.1.el9_1.x86_64

  3. Pour exécuter la requête, cliquez sur Exécuter.

Pour en savoir plus, consultez Exécuter une requête.

Examiner les messages d'erreur liés à l'application des règles

Lorsqu'une ressource de règle d'OS échoue à la validation ou à l'application, VM Manager enregistre le message d'erreur dans le champ configSteps.errorMessage de la table res_osconfig_googleapis_com_OSPolicyAssignmentReport. Vous pouvez interroger ce champ dans BigQuery pour résoudre les échecs d'exécution des règles dans votre organisation.

La requête suivante renvoie les derniers messages d'erreur de validation ou d'application pour chaque instance de VM :

SELECT
  resource.data.instance AS instance,
  resource.data.osPolicyCompliances[OFFSET(0)].osPolicyId AS policy_id,
  resource_compliances.osPolicyResourceId AS resource_id,
  config_steps.type AS step_type,
  ANY_VALUE(config_steps.errorMessage HAVING MAX updateTime) AS error_message
FROM
  `DATASET_ID.res_osconfig_googleapis_com_OSPolicyAssignmentReport`,
  UNNEST(resource.data.osPolicyCompliances[OFFSET(0)].osPolicyResourceCompliances) AS resource_compliances,
  UNNEST(resource_compliances.configSteps) AS config_steps
WHERE
  config_steps.errorMessage IS NOT NULL
  AND config_steps.errorMessage != ""
GROUP BY
  instance,
  policy_id,
  resource_id,
  step_type

Remplacez DATASET_ID par l'ID de votre ensemble de données BigQuery (par exemple, cai_exp).

Le résultat de la requête se présente comme suit :

instance policy_id resource_id step_type error_message
ubuntu-2 return-kernel-version-policy return-kernel-version DESIRED_STATE_ENFORCEMENT Error running enforce script: exit status 1

Étapes suivantes

Pour en savoir plus sur la gestion des règles du système d'exploitation et l'analyse des données de conformité, consultez les ressources suivantes :