Documentation de référence sur les fichiers YAML de stratégie

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 globale qui exempte les images système gérées par Google.	Non
defaultAdmissionRule	Spécifie les règles qui s'appliquent à tous les clusters pour lesquels il n'existe pas de règle spécifique à un cluster.	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 Platform (GCP) où votre stratégie est définie.

Exemple :

name: projects/example-project/policy

admissionWhitelistPatterns

Remarque : L'utilisation de admissionWhitelistPatterns pour ajouter des images système gérées par Google à la liste d'autorisation n'est pas recommandée. Pour ajouter des images système gérées par Google à la liste d'autorisation, globalPolicyEvaluationMode doit être défini sur ENABLE. 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 ou d'un autre registre dans le sous-nœud namePattern :

admissionWhitelistPatterns:
  - namePattern: MATCHING_PATTERN
  - ...

Où MATCHING_PATTERN correspond au chemin d'accès à une seule image par correspondance exacte, ou à toute image correspondant à un modèle utilisant le caractère générique (*). Notez que les caractères génériques ne peuvent figurer qu'à la fin du modèle. Ainsi, gcr.io/n*x n'est pas autorisé, contrairement à gcr.io/nginx*. En outre, les caractères génériques n'englobent pas le caractère /. Ainsi, gcr.io/nginx* correspond à gcr.io/nginx@latest, mais pas à gcr.io/nginx/image.

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

admissionWhitelistPatterns:
  - namePattern: gcr.io/google_containers/*
  - namePattern: gcr.io/google-containers/*
  - namePattern: k8s.gcr.io/*
  - namePattern: gke.gcr.io/*
  - namePattern: gcr.io/stackdriver-agents/*
  - namePattern: gcr.io/example-project/helloworld

Modèles de listes d'autorisation

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

globalPolicyEvaluationMode

Le mode d'évaluation de la stratégie globale 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 en tant qu'utilisateur. 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 globale 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 stratégie globale, exécutez la commande suivante :

globalPolicyEvaluationMode: DISABLE

Remarque : Nous vous recommandons de définir globalPolicyEvaluationMode sur 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. Bien que vous puissiez gérer vous-même les images système en les répertoriant dans la liste d'autorisation admissionWhitelistPatterns, les images système mises à jour peuvent ne pas être autorisées à s'exécuter si la liste d'autorisation n'est pas à jour.

Remarque : La valeur par défaut de globalPolicyEvaluationMode est actuellement DISABLE, mais elle sera sera prochainement ENABLE. Par conséquent, il est recommandé de définir explicitement la valeur en fonction du comportement que vous préférez.

Remarque : Si vous désactivez globalPolicyEvaluationMode , les chemins d'accès gcr.io/google_containers/*, gcr.io/google-containers/*, k8s.gcr.io/*, gke.gcr.io/* 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 avec succès. 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 d'autorisation 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