Documentation de référence sur les règles YAML

Remarque : Ce document ou cette section inclut des références à un ou plusieurs termes que Google considère comme irrespectueux ou choquants. Ces termes sont utilisés parce qu'ils constituent des mots clés utilisés par le logiciel décrit dans le présent document.

Liste des termes : whitelist

Cette page contient des informations de référence sur les stratégies de l'autorisation binaire, qui sont spécifiées au format YAML. Lorsque vous configurez une stratégie à l'aide de l'interface de ligne de commande, vous modifiez un fichier au format YAML conforme à cette spécification. Pour obtenir des exemples de stratégies au format YAML, consultez la page Exemples de stratégies.

Les fichiers YAML de stratégie se présentent au format suivant :

name: projects/<PROJECT_ID>/policy
admissionWhitelistPatterns:
- namePattern: <MATCHING_PATTERN>
- ...
globalPolicyEvaluationMode: <GLOBAL_EVAL_MODE>
defaultAdmissionRule:
  <ADMISSION_RULE>
clusterAdmissionRules:
  <CLUSTER_SPECIFIER>:
    <ADMISSION_RULE>
  ...

Nœuds

Le format YAML comporte les nœuds de niveau supérieur suivants :

Nœud	Description	Obligatoire
name	Nom de la stratégie	Oui
admissionWhitelistPatterns	Spécifie les images de conteneurs dont le déploiement est toujours autorisé.	Non
globalPolicyEvaluationMode	Indique s'il faut appliquer une stratégie système qui exempte les images système gérées par Google.	Non
defaultAdmissionRule	Règle à utiliser lorsqu'aucune règle spécifique ne s'applique.	Oui
clusterAdmissionRules	Spécifie les règles qui s'appliquent à des clusters spécifiques.	Non

name

Le nœud name contient le nom de la stratégie au format suivant :

name: projects/PROJECT_ID/policy

Où PROJECT_ID correspond au nom de votre projet Google Cloud dans lequel votre stratégie est définie.

Par exemple :

name: projects/example-project/policy

admissionWhitelistPatterns

Remarque : Nous vous déconseillons d'utiliser admissionWhitelistPatterns pour ajouter des images système gérées par Google à la liste d'autorisation. Les images système gérées par Google sont autorisées si globalPolicyEvaluationMode est défini sur ENABLE (paramètre par défaut). Pour en savoir plus, consultez la section consacrée à globalPolicyEvaluationMode.

admissionWhitelistPatterns spécifie une liste d'autorisation d'images de conteneurs qui sont exclues de l'application des règles. Vous spécifiez le chemin d'accès aux images de Container Registry et Artifact Registry, d'un autre registre ou d'une référence locale dans le sous-nœud namePattern :

admissionWhitelistPatterns:
  - namePattern: MATCHING_PATTERN
  - ...

Remplacez MATCHING_PATTERN par un chemin d'accès à une seule image ou un modèle correspondant contenant l'un des symboles génériques (*, **).

Notez que les caractères génériques ne sont valides qu'à la fin du modèle. Par exemple, gcr.io/my-project/nginx* est un modèle valide, mais gcr.io/my-project/n*x n'en est pas un. Le caractère générique * ne correspond qu'aux images du répertoire spécifié. Par exemple, gcr.io/my-project/nginx* correspond à gcr.io/my-project/nginx:latest, mais pas à gcr.io/my-project/nginx-images/nginx. Le caractère générique ** correspond aux images des sous-répertoires. Par exemple, le chemin d'accès gcr.io/my-project/nginx** correspond à gcr.io/my-project/nginx-1.14.2/image:latest.

Attention : Soyez prudent lorsque vous utilisez le caractère générique ** avec des ID de projet, car il correspond également aux images de différents projets. Par exemple, le chemin gcr.io/my-project** autorise le déploiement des images dans gcr.io/my-project/nginx et gcr.io/my-project-exploit/nginx-exploit.

L'exemple suivant ajoute des registres contenant des images Google Kubernetes Engine (GKE) couramment utilisées, une image située dans gcr.io/example-project/helloworld et une référence locale à une image, à la liste des images exclues de stratégie :

admissionWhitelistPatterns:
  - namePattern: gcr.io/google-containers/*
  - namePattern: k8s.gcr.io/**
  - namePattern: gke.gcr.io/**
  - namePattern: gcr.io/gke-release/asm/*
  - namePattern: gcr.io/stackdriver-agents/*
  - namePattern: gcr.io/example-project/helloworld
  - namePattern: loc-ref

Remarque : Cet exemple inclut les images dont GKE a besoin pour démarrer un cluster. Vous devez les inclure si globalPolicyEvaluationMode est désactivé.

Modèles de listes d'autorisation

Remarque : Les mêmes règles s'appliquent aux références locales aux images.

Pour ajouter à la liste d'autorisation toutes les images de conteneurs dont l'emplacement du registre correspond au chemin d'accès spécifié, exécutez la commande suivante :

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/*

Pour ajouter à la liste d'autorisation une image spécifique, procédez comme suit :

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld

Pour ajouter à la liste d'autorisation une version active avec tag, utilisez l'exemple de code ci-dessous :

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld:latest
  - namePattern: gcr.io/example-project/helloworld:my-tag
  - namePattern: gcr.io/example-project/helloworld:v1.*

Pour ajouter à la liste d'autorisation une version spécifique d'une image, identifiée par son condensé, utilisez l'exemple de code ci-dessous :

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld@sha256:77b0b75136b9bd0fd36fb50f4c92ae0dbdbbe164ab67885e736fa4374e0cbb8c

Pour ajouter des images à des listes d'autorisations dans les sous-répertoires d'un chemin d'accès donné, procédez comme suit :

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/**

globalPolicyEvaluationMode

Le mode d'évaluation de la stratégie système est un paramètre de stratégie qui permet à l'autorisation binaire d'évaluer une stratégie système avant d'évaluer la stratégie que vous configurez. La stratégie système est fournie par Google et exempte une liste d'images système gérées par Google d'une évaluation plus approfondie. Lorsque ce paramètre est activé, les images requises par GKE ne sont pas bloquées par l'application de la stratégie. La stratégie du système est évaluée avant et en plus de l'évaluation de la stratégie utilisateur, y compris admissionWhitelistPatterns.

Pour autoriser toutes les images système gérées par Google, définissez la propriété globalPolicyEvaluationMode sur ENABLE :

globalPolicyEvaluationMode: ENABLE

Pour désactiver le mode d'évaluation de la règle système :

globalPolicyEvaluationMode: DISABLE

Remarque : Nous vous recommandons de conserver le paramètre globalPolicyEvaluationMode par défaut, ENABLE. Pour que GKE fonctionne correctement, il doit exécuter un certain nombre d'images système dans votre cluster. Lorsque vous activez globalPolicyEvaluationMode, la liste d'autorisation des images système gérées par Google est automatiquement mise à jour à chaque nouvelle version de GKE. Vous pouvez gérer vous-même les images système en les répertoriant dans admissionWhitelistPatterns, mais les images système mises à jour peuvent ne pas être autorisées à s'exécuter si la liste d'autorisation n'est pas maintenue à jour.

Remarque : Si vous désactivez globalPolicyEvaluationMode, les chemins gcr.io/google-containers/*,k8s.gcr.io/**, gke.gcr.io/*, gcr.io/gke-release/someproject/* et gcr.io/stackdriver-agents/* doivent être inclus dans la liste d'autorisation admissionWhitelistPatterns, car ils contiennent les ressources Google Cloud requises par GKE pour démarrer un cluster. D'autres chemins d'accès aux images pourront être nécessaires ultérieurement. Ces chemins d'accès doivent également être inclus dans la liste blanche admissionWhitelistPatterns pour que les clusters GKE s'exécutent comme prévu.

defaultAdmissionRule

defaultAdmissionRule spécifie la règle par défaut pour la stratégie. La règle par défaut définit les contraintes qui s'appliquent à toutes les images de conteneurs non exclues, à l'exception de celles qui possèdent une règle spécifique à leur cluster. Vous spécifiez la règle par défaut à l'aide de la collection ADMISSION_RULE :

defaultAdmissionRule:
  ADMISSION_RULE

L'exemple suivant montre une règle par défaut n'autorisant que le déploiement des images de conteneurs autorisées par le certificateur spécifié. Si tous les certificateurs requis n'ont pas autorisé l'image, l'autorisation binaire bloque le déploiement et écrit dans le journal d'audit.

defaultAdmissionRule:
  evaluationMode: REQUIRE_ATTESTATION
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
  requireAttestationsBy:
  - projects/example-project/attestors/secure-build

clusterAdmissionRules

clusterAdmissionRules permet de déclarer des règles spécifiques à un cluster pour la stratégie. Les contraintes de ces règles ne s'appliquent qu'au cluster spécifié. Si l'autorisation binaire applique une règle spécifique à un cluster à un déploiement, la règle par défaut n'est pas prise en compte. Comme pour les règles par défaut, vous spécifiez des règles spécifiques à un cluster à l'aide de la collection ADMISSION_RULE :

clusterAdmissionRules:
  CLUSTER_SPECIFIER:
    ADMISSION_RULE

Où CLUSTER_SPECIFIER correspond à l'ID de ressource du cluster auquel la règle s'applique, au format location.name (par exemple, us-east1-a.prod-cluster).

Les exemples suivants montrent une règle spécifique à un cluster qui ne permet le déploiement que des images de conteneurs autorisées par les certificateurs spécifiés :

clusterAdmissionRules:
  us-east1-a.prod-cluster:
    evaluationMode: REQUIRE_ATTESTATION
    enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
    requireAttestationsBy:
    - projects/example-project/attestors/secure-build
    - projects/example-project/attestors/prod-qualified

Collections de nœuds

ADMISSION_RULE

ADMISSION_RULE est une collection de nœuds qui spécifie les contraintes de la règle au format suivant :

evaluationMode: EVAL_MODE
enforcementMode: ENFORCEMENT_MODE
requireAttestationsBy:
- ATTESTOR
- ...

defaultAdmissionRule et clusterAdmissionRule font référence à cette collection.

evaluationMode

evaluationMode spécifie l'opération effectuée par l'autorisation binaire afin de déterminer s'il convient de déployer une image de conteneur. Les valeurs possibles sont :

• ALWAYS_ALLOW : toujours autoriser le déploiement d'images évaluées par cette règle.
• ALWAYS_DENY : toujours refuser le déploiement d'images évaluées par cette règle.
• REQUIRE_ATTESTATION : un ou plusieurs certificateurs doivent autoriser la publication avant le déploiement.

Si evaluationMode est défini sur REQUIRE_ATTESTATION, vous devez fournir une référence aux certificateurs requis dans requireAttestationsBy.

enforcementMode

enforcementMode permet de spécifier l'action effectuée par l'autorisation binaire si une image de conteneur ne respecte pas les contraintes définies dans la règle. Les valeurs possibles sont :

• ENFORCED_BLOCK_AND_AUDIT_LOG : bloque le déploiement et écrit dans le journal d'audit.
• DRYRUN_AUDIT_LOG_ONLY : permet le déploiement d'images non conformes et consigne des informations sur les violations dans le journal d'audit.

La plupart des règles de production utilisent le mode d'application ENFORCED_BLOCK_AND_AUDIT_LOG. DRYRUN_AUDIT_LOG_ONLY est principalement utilisé pour tester une stratégie dans votre environnement avant son entrée en vigueur.

requireAttestationsBy

requireAttestationsBy permet de spécifier un ou plusieurs certificateurs qui doivent autoriser la version avant qu'une image de conteneur ne puisse être déployée. Cela n'est requis que pour les règles REQUIRE_ATTESTATION. Le format de ce nœud est le suivant :

requireAttestationsBy:
  - projects/PROJECT_ID/attestors/ATTESTOR_NAME
  - ...

Où PROJECT_ID correspond au nom du projet dans lequel vos certificateurs sont définis et ATTESTOR_NAME est le nom d'un certificateur devant signer la version.

L'exemple suivant montre comment spécifier des certificateurs :

requireAttestationsBy:
- projects/example-project/attestors/secure-build
- projects/example-project/attestors/prod-qualified