Configurer une stratégie à l'aide de l'API REST

Cette page explique comment configurer une stratégie d'autorisation binaire à l'aide de l'API REST. Vous pouvez également effectuer ces tâches à l'aide de Google Cloud CLI ou de Google Cloud Console. Cette étape fait partie de la configuration de l'autorisation binaire.

Aperçu

Une stratégie est un ensemble de règles régissant le déploiement d'une ou plusieurs images de conteneur.

Lorsque vous configurez une stratégie à l'aide de l'API REST, vous renseignez des valeurs dans un format JSON de structure identique à celle de la structure YAML utilisée dans les interactions gcloud avec le service. Pour en savoir plus, consultez la documentation de référence sur les fichiers YAML de stratégie.

Pour configurer une stratégie, vous devez :

  • exporter un fichier JSON de stratégie ;
  • ajouter des images exclues supplémentaires (facultatif) ;
  • définir la règle par défaut ;
  • ajouter des règles spécifiques à un cluster (facultatif) ;
  • Importer le fichier JSON de stratégie

La plupart des stratégies concrètes vérifient si tous les certificateurs requis ont validé qu'une image de conteneur est prête à être déployée. Dans un tel cas, vous devez également créer des certificateurs lorsque vous configurez la stratégie.

Définir le projet par défaut

Si ce n'est pas déjà fait, définissez le projet Google Cloud par défaut :

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

Où PROJECT_ID correspond à l'ID de votre projet.

Exporter la stratégie

Cette section s'applique à GKE, Distributed Cloud, Cloud Run et Cloud Service Mesh.

Exportez la stratégie dans un fichier JSON sur votre système local :

curl \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy" \
    -o "/tmp/policy.json"

Par défaut, ce fichier comporte les éléments suivants :

{
  "name": "projects/PROJECT_ID/policy",
  "globalPolicyEvaluationMode": "ENABLE",
  "defaultAdmissionRule": {
    "evaluationMode": "ALWAYS_ALLOW",
    "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
  }
}

Gérer les images exclues

Cette section s'applique à GKE, Distributed Cloud, Cloud Run et Cloud Service Mesh.

Une image exclue est une image de conteneur exclue des règles définies dans la stratégie. L'autorisation binaire permet toujours que les images exclues soient déployées.

Pour spécifier des images exclues, répertoriez leurs chemins de registre dans admissionWhitelistPatterns. Le chemin d'accès peut faire référence à Container Registry ou à un autre registre d'images. L'outil d'application traite les images exclues du fichier admissionWhitelistPatterns après les images exclues du mode d'évaluation de la règle système.

Pour ajouter une image exclue, ajoutez un nœud namePattern sous une liste admissionWhitelistPatterns dans le fichier JSON de la stratégie :

{
  "name": "projects/PROJECT_ID/policy",
  "admissionWhitelistPatterns": [
    {
      "namePattern": "MATCHING_PATTERN"
    }
  ],
  ...
}

Où MATCHING_PATTERN est le chemin d'accès à une image unique de votre registre en cas de correspondance exacte, ou à toute image correspondant à un modèle utilisant le caractère générique (*, **).

Cloud Run

Cette section s'applique à Cloud Run.

Vous ne pouvez pas directement spécifier des noms d'images contenant un tag. Par exemple, vous ne pouvez pas spécifier IMAGE_PATH:latest.

Si vous souhaitez spécifier des noms d'image contenant des tags, vous devez spécifier le nom de l'image à l'aide d'un caractère générique comme suit :

  • * pour toutes les versions d'une même image (par exemple, us-docker.pkg.dev/myproject/container/hello@*)
  • ** pour toutes les images d'un projet (par exemple, us-docker.pkg.dev/myproject/**)

Vous pouvez utiliser des chemins d'accès pour spécifier un condensé au format IMAGE_PATH@DIGEST.

Mode d'évaluation de la stratégie système

Cette section s'applique à GKE et Distributed Cloud.

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. Google gère la stratégie système, qui exclut une liste d'images système gérées par Google utilisées par GKE. Les images répertoriées dans la stratégie système ne sont pas bloquées par l'application de la stratégie. Si vous n'activez pas ce paramètre, vous devez gérer vous-même la liste des images exclues. Découvrez comment gérer les images exclues.

Vous pouvez afficher le contenu de la stratégie système à l'aide de la commande suivante :

gcloud alpha container binauthz policy export-system-policy

Pour activer le mode d'évaluation de la stratégie système, ajoutez le nœud de niveau supérieur suivant au fichier JSON de la stratégie :

"globalPolicyEvaluationMode": "ENABLE"

Pour désactiver le mode d'évaluation de la stratégie système, ajoutez la ligne suivante :

"globalPolicyEvaluationMode": "DISABLE"

Vous pouvez exporter la stratégie système associée à une région spécifique, comme suit :

gcloud alpha container binauthz policy export-system-policy \
  --location=REGION > /tmp/policy.yaml

Remplacez REGION par la région associée à la stratégie système que vous souhaitez exporter (ou "globale"). Voici quelques exemples : asia-east1, europe-west1, us-central1.

Si vous omettez --location ou spécifiez --location=global, la commande génère une règle système à partir d'une région du dernier groupe de régions pour recevoir des mises à jour. Comme la plupart des modifications apportées à la stratégie système sont des ajouts, la sortie affiche l'ensemble des images système actuellement autorisées dans toutes les régions.

Définir la règle par défaut

Cette section s'applique à GKE, Distributed Cloud, Cloud Run et Cloud Service Mesh.

Une règle est la partie d'une stratégie qui définit les contraintes que les images de conteneurs doivent respecter pour pouvoir être déployées. Chaque demande d'admission est associée à un cluster GKE. Si une demande ne correspond à aucune règle spécifique à un cluster, la règle par défaut est utilisée.

La règle par défaut est définie dans le nœud defaultAdmissionRule de la stratégie. Pour en savoir plus sur les éléments de cette règle, consultez la section ADMISSION_RULE dans la documentation de référence sur les fichiers YAML de stratégie. Pour obtenir des exemples de règles par défaut, consultez la page Exemples de stratégies.

Pour définir la règle par défaut, modifiez le nœud defaultAdmissionRule du fichier JSON de stratégie suivant vos besoins :

  "defaultAdmissionRule": {
    "evaluationMode": "EVAL_MODE",
    "enforcementMode": "ENFORCEMENT_MODE"
    requireAttestationsBy: [
      ATTESTOR,
      ...
    ]
  }

où :

  • EVAL_MODE spécifie le type de contrainte évaluée par l'autorisation binaire avant d'autoriser le déploiement d'une image de conteneur.
  • ENFORCEMENT_MODE spécifie l'action effectuée si une image de conteneur n'est pas conforme aux contraintes définies dans la règle.
  • ATTESTOR spécifie les certificateurs (le cas échéant) devant signer une image de conteneur avant qu'elle puisse être déployée. Utilisez le chemin d'accès complet au certificateur au format projects/PROJECT_ID/attestors/ATTESTOR_NAME.

Si votre règle vérifie que tous les certificateurs requis ont bien signé une image de conteneur, vous devez créer les certificateurs avant de conclure cette étape.

Définir des règles spécifiques à un cluster (facultatif)

Cette section s'applique à GKE et Distributed Cloud.

Une ou plusieurs règles spécifiques à un cluster peuvent également être définies pour un cluster. Ce type de règle ne s'applique qu'au cluster GKE spécifié. Si un cluster ne présente aucune règle spécifique, la règle par défaut est utilisée. Les règles spécifiques à un cluster constituent une partie facultative d'une stratégie.

Les règles spécifiques à un cluster sont définies dans des nœuds clusterAdmissionRules du fichier JSON de stratégie. Pour en savoir plus sur les éléments de cette règle, consultez la section ADMISSION_RULE dans la documentation de référence sur les fichiers YAML de stratégie. Pour obtenir un exemple, consultez la section Utiliser une règle spécifique à un cluster dans la section Exemples de stratégies.

Pour ajouter une règle spécifique à un cluster :

Dans le fichier JSON de stratégie, ajoutez un nœud clusterAdmissionRules :

"clusterAdmissionRules": {
    "us-central1-a.test-cluster": {
      "evaluationMode": "REQUIRE_ATTESTATION",
      "requireAttestationsBy": [
        "ATTESTOR",
        ...
      ],
      "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
    }
  },

où CLUSTER_SPECIFIER est l'ID de ressource du cluster auquel la règle s'applique.

  • Pour GKE, les clusters GKE associés et GKE sur AWS, le format est CLUSTER_LOCATION.CLUSTER_NAME (par exemple, us-central1-a.test-cluster).
  • Pour Google Distributed Cloud et Google Distributed Cloud, le format est FLEET_MEMBERSHIP_LOCATION.FLEET_MEMBERSHIP_ID (par exemple, global.test-membership).

Les autres propriétés sont décrites dans la section Définir la règle par défaut plus haut dans ce guide. Consultez la section Exemples de règles pour obtenir un exemple de règle spécifique à un cluster.

Si votre règle vérifie que tous les certificateurs requis ont bien signé une image de conteneur, vous devez créer les certificateurs avant de conclure cette étape.

Importer le fichier JSON de stratégie

Cette section s'applique à GKE, Distributed Cloud, Cloud Run et Cloud Service Mesh.

Importez le fichier JSON de stratégie dans l’autorisation binaire en saisissant les éléments suivants :

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    --data-binary @/tmp/policy.json  \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy"

Étapes suivantes