Referenz zu YAML-Richtlinien

Hinweis: Dieses Dokument bzw. dieser Abschnitt enthält Verweise auf einen oder mehrere Begriffe, die Google als respektlos oder anstößig erachtet. Die Begriffe werden verwendet, da es sich um Suchbegriffe der Software handelt, die im Dokument beschrieben wird.

Die Begriffe: whitelist

Diese Seite enthält Referenzinformationen zu Richtlinien für die Binärautorisierung im YAML-Format. Wenn Sie eine Richtlinie über die Befehlszeile konfigurieren möchten, bearbeiten Sie dafür eine YAML-formatierte Datei, die dieser Spezifikation entspricht. Beispiele für Richtlinien im YAML-Format finden Sie unter Beispielrichtlinien.

YAML-Richtliniendateien haben folgendes Format:

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

Knoten

Das YAML-Format hat die folgenden Knoten auf der obersten Ebene:

Knoten	Beschreibung	Erforderlich
name	Name der Richtlinie.	Ja
admissionWhitelistPatterns	Gibt Container-Images an, die immer bereitgestellt werden dürfen.	Nein
globalPolicyEvaluationMode	Legt fest, ob eine Systemrichtlinie angewendet wird, mit der Systemimages von Google ausgenommen werden.	Nein
defaultAdmissionRule	Die Regel, die verwendet werden soll, wenn keine bestimmte Regel zutrifft.	Ja
clusterAdmissionRules	Gibt Regeln an, die für bestimmte Cluster gelten.	Nein

name

Der Knoten name enthält den Namen der Richtlinie im folgenden Format:

name: projects/PROJECT_ID/policy

Dabei ist PROJECT_ID der Name Ihres Google Cloud-Projekts, in dem Ihre Richtlinie definiert ist.

Beispiel:

name: projects/example-project/policy

admissionWhitelistPatterns

Hinweis: Wir empfehlen, admissionWhitelistPatterns nicht zu verwenden, um von Google verwaltete System-Images auf die Zulassungsliste zu setzen. Von Google verwaltete System-Images sind zulässig, wenn globalPolicyEvaluationMode auf ENABLE gesetzt ist (Standardeinstellung). Ausführliche Informationen finden Sie unter globalPolicyEvaluationMode.

admissionWhitelistPatterns gibt eine Zulassungsliste der Container-Images an, die von der Richtliniendurchsetzung ausgenommen sind. Sie legen den Pfad zu den Images in Container Registry und Artifact Registry, in einer anderen Registry oder in einer lokalen Referenz im Unterknoten namePattern fest:

admissionWhitelistPatterns:
  - namePattern: MATCHING_PATTERN
  - ...

Ersetzen Sie MATCHING_PATTERN entweder durch einen Pfad zu einem einzelnen Image oder ein Übereinstimmungsmuster mit einem der Platzhaltersymbole (*, **).

Beachten Sie, dass Platzhalter nur am Ende des Musters gültig sind. Beispiel: gcr.io/my-project/nginx* ist ein gültiges Muster, gcr.io/my-project/n*x jedoch nicht. Der Platzhalter * entspricht nur Images im angegebenen Verzeichnis. Beispiel: gcr.io/my-project/nginx* stimmt mit gcr.io/my-project/nginx:latest überein, aber nicht mit gcr.io/my-project/nginx-images/nginx. Der Platzhalter ** gleicht Images in Unterverzeichnissen ab. Der Pfad gcr.io/my-project/nginx** stimmt beispielsweise mit gcr.io/my-project/nginx-1.14.2/image:latest überein.

Achtung: Gehen Sie vorsichtig vor, wenn Sie den Platzhalter ** mit Projekt-IDs verwenden, da dies auch für Images in verschiedenen Projekten gilt. Mit dem Pfad gcr.io/my-project** können beispielsweise Images in gcr.io/my-project/nginx und gcr.io/my-project-exploit/nginx-exploit bereitgestellt werden.

Das folgende Beispiel fügt Registries mit häufig verwendeten GKE-Images (Google Kubernetes Engine), ein Image unter gcr.io/example-project/helloworld und einen lokalen Verweis auf ein Image zur Liste der ausgenommenen Images für die Richtlinie hinzu:

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

Hinweis: Dieses Beispiel enthält Images, die GKE zum Starten eines Clusters benötigt. Sie müssen sie angeben, wenn globalPolicyEvaluationMode deaktiviert ist.

Zulassungslistenmuster

Hinweis: Für lokale Verweise auf Images gelten die gleichen Regeln.

So lassen Sie alle Container-Images zu, deren Registry-Speicherort mit dem angegebenen Pfad übereinstimmt:

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

So lassen Sie ein bestimmtes Image zu:

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

So lassen Sie eine derzeit getaggte Version zu:

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

So lassen Sie eine bestimmte Image-Version anhand ihres Digests zu:

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

So lassen Sie Images in Unterverzeichnissen eines bestimmten Pfads zu:

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

globalPolicyEvaluationMode

Der Auswertungsmodus für Systemrichtlinien ist eine Richtlinieneinstellung, bei der die Binärautorisierung erst eine Systemrichtlinie auswertet, bevor die von Ihnen konfigurierte Richtlinie ausgewertet wird. Die Systemrichtlinie wird von Google bereitgestellt und schließt eine Liste der von Google verwalteten Systemimages von der weiteren Richtlinienauswertung aus. Ist diese Einstellung aktiviert, werden für GKE erforderliche Images durch die Richtlinienerzwingung nicht blockiert. Die Auswertung der Systemrichtlinie erfolgt vor der Auswertung der Nutzerrichtlinien und ergänzend, einschließlich admissionWhitelistPatterns.

Um alle von Google verwalteten Systemimages zuzulassen, legen Sie für das Attribut globalPolicyEvaluationMode den Wert ENABLE fest:

globalPolicyEvaluationMode: ENABLE

So deaktivieren Sie den Auswertungsmodus für Systemrichtlinien:

globalPolicyEvaluationMode: DISABLE

Hinweis: Es wird empfohlen, für die Einstellung globalPolicyEvaluationMode die Standardeinstellung ENABLE beizubehalten. Damit GKE ordnungsgemäß funktioniert, muss in Ihrem Cluster eine Reihe von Systemimages ausgeführt werden. Wenn Sie globalPolicyEvaluationMode aktivieren, wird die von Google verwaltete Zulassungsliste der Systemimages mit jedem GKE-Release automatisch aktualisiert. Sie können System-Images selbst verwalten, indem Sie sie in admissionWhitelistPatterns eintragen, allerdings werden aktualisierte System-Images unter Umständen nicht ausgeführt, wenn die Zulassungsliste nicht aktuell ist.

Hinweis: Wenn Sie globalPolicyEvaluationMode deaktivieren, müssen die Pfade gcr.io/google-containers/*, k8s.gcr.io/**, gke.gcr.io/*, gcr.io/gke-release/someproject/* und gcr.io/stackdriver-agents/* in der Zulassungsliste admissionWhitelistPatterns stehen, da sie Google Cloud-Ressourcen enthalten, die von GKE für den erfolgreichen Start eines Clusters benötigt werden. Möglicherweise sind in Zukunft zusätzliche Image-Pfade erforderlich. Diese Pfade müssen ebenfalls in die Zulassungsliste admissionWhitelistPatterns aufgenommen werden, damit GKE-Cluster wie erwartet ausgeführt werden.

defaultAdmissionRule

defaultAdmissionRule legt die Standardregel für die Richtlinie fest. Die Standardregel definiert die Einschränkungen, die für alle nicht ausgenommenen Container-Images gelten, außer für diejenigen, die eine eigene clusterspezifische Regel haben. Die Standardregel legen Sie mit der Sammlung ADMISSION_RULE fest:

defaultAdmissionRule:
  ADMISSION_RULE

Das folgende Beispiel zeigt eine Standardregel, mit der nur diejenigen Container-Images bereitgestellt werden können, die vom angegebenen Attestierer autorisiert wurden. Für den Fall, dass nicht alle erforderlichen Attestierer das Image autorisiert haben, blockiert die Binärautorisierung das Deployment und schreibt in das Audit-Log.

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

clusterAdmissionRules

clusterAdmissionRules deklariert clusterspezifische Regeln für die Richtlinie. Die Einschränkungen in diesen Regeln gelten nur für den angegebenen Cluster. Wenn die Binärautorisierung eine clusterspezifische Regel auf ein Deployment anwendet, wird die Standardregel nicht berücksichtigt. Wie bei Standardregeln geben Sie clusterspezifische Regeln mithilfe der Sammlung ADMISSION_RULE an:

clusterAdmissionRules:
  CLUSTER_SPECIFIER:
    ADMISSION_RULE

Dabei ist CLUSTER_SPECIFIER die Ressourcen-ID des Clusters, auf den die Regel im Format location.name angewendet wird (z. B. us-east1-a.prod-cluster).

Die folgenden Beispiele zeigen eine clusterspezifische Regel, die nur das Deployment von Container-Images zulässt, die von den angegebenen Attestierern autorisiert wurden:

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

Knotensammlungen

ADMISSION_RULE

ADMISSION_RULE ist eine Sammlung von Knoten, die die Einschränkungen für die Regel im folgenden Format angeben:

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

Sowohl defaultAdmissionRule als auch clusterAdmissionRule verweisen auf diese Sammlung.

evaluationMode

evaluationMode legt den Vorgang fest, der von der Binärautorisierung ausgeführt wird, um zu ermitteln, ob ein Container-Image bereitgestellt werden soll. Die möglichen Werte sind:

• ALWAYS_ALLOW: Das Deployment von Images, die von dieser Regel ausgewertet werden, wird immer zugelassen.
• ALWAYS_DENY: Die Deployment von Images, die von dieser Regel ausgewertet werden, wird immer abgelehnt.
• REQUIRE_ATTESTATION: Mindestens ein Attestierer ist erforderlich, um den Release vor dem Deployment zu autorisieren.

Wenn für evaluationMode der Wert REQUIRE_ATTESTATION festgelegt ist, müssen Sie in requireAttestationsBy einen Verweis auf die erforderlichen Attestierer angeben.

enforcementMode

enforcementMode legt die Aktion fest, die von der Binärautorisierung ausgeführt wird, wenn ein Container-Image nicht den in der Regel definierten Einschränkungen entspricht. Die möglichen Werte sind:

• ENFORCED_BLOCK_AND_AUDIT_LOG: Blockiert das Deployment und schreibt in das Audit-Log.
• DRYRUN_AUDIT_LOG_ONLY: Ermöglicht das Deployment nicht konformer Images und schreibt Details zum Verstoß in das Audit-Log.

Die meisten Produktionsregeln verwenden den Erzwingungsmodus ENFORCED_BLOCK_AND_AUDIT_LOG. Der Modus DRYRUN_AUDIT_LOG_ONLY wird hauptsächlich zum Testen einer Richtlinie in der Umgebung verwendet, bevor sie in Kraft tritt.

requireAttestationsBy

requireAttestationsBy gibt einen oder mehrere Attestierer an, die den Release autorisieren müssen, bevor ein Container-Image bereitgestellt werden kann. Dies ist nur für REQUIRE_ATTESTATION-Regeln erforderlich. Das Format für diesen Knoten lautet:

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

Dabei ist PROJECT_ID der Name des Projekts, in dem die Attestierer definiert sind, und ATTESTOR_NAME der Name eines Attestierers, der zum Signieren des Release erforderlich ist.

Das folgende Beispiel zeigt, wie Attestierer angegeben werden:

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