Referenz zu YAML-Richtlinien

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 globale Richtlinie angewendet wird, mit der Systemimages von Google ausgenommen werden.	Nein
defaultAdmissionRule	Gibt Regeln an, die für alle Cluster gelten, für die es keine clusterspezifische Regel gibt.	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 Platform-Projekts (GCP), in dem Ihre Richtlinie definiert ist.

Beispiel:

name: projects/example-project/policy

admissionWhitelistPatterns

Hinweis: Von Google verwaltete System-Images sollten nicht mit admissionWhitelistPatterns auf die Zulassungsliste gesetzt werden. Wenn Sie von Google verwaltete Systemimages auf die Zulassungsliste setzen möchten, muss für globalPolicyEvaluationMode der Wert ENABLE festgelegt sein. Weitere 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 oder in einer anderen Registry im Unterknoten namePattern fest:

admissionWhitelistPatterns:
  - namePattern: MATCHING_PATTERN
  - ...

Dabei ist MATCHING_PATTERN der Pfad zu einem einzelnen Image mit exakter Übereinstimmung oder zu allen Images, die einem Muster mit dem Platzhaltersymbol (*) entsprechen. Beachten Sie, dass Platzhalter nur am Ende und nicht an anderer Stelle im Muster angegeben werden. gcr.io/n*x ist also nicht zulässig, gcr.io/nginx* dagegen schon. Außerdem beinhalten Platzhalter nicht das Pfadzeichen /. gcr.io/nginx* entspricht also gcr.io/nginx@latest, aber nicht gcr.io/nginx/image.

Im folgenden Beispiel werden Registries mit häufig verwendeten Google Kubernetes Engine-Images (GKE) sowie ein Image in gcr.io/example-project/helloworld zur Liste der für die Richtlinie ausgenommenen Images hinzugefügt:

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

Zulassungslistenmuster

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

globalPolicyEvaluationMode

Der Auswertungsmodus für globale Richtlinien ist eine Richtlinieneinstellung, bei der die Binärautorisierung erst eine Systemrichtlinie auswertet, bevor die Richtlinie, die Sie als Nutzer konfigurieren, 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 globalen Richtlinie 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 globale Richtlinien:

globalPolicyEvaluationMode: DISABLE

Hinweis: Es wird empfohlen, für globalPolicyEvaluationMode den Wert ENABLE festzulegen. 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 von System-Images automatisch mit jedem GKE-Release aktualisiert. Sie können System-Images auch selbst verwalten, indem Sie sie in der admissionWhitelistPatterns-Liste aufnehmen. Allerdings werden aktualisierte System-Images unter Umständen nicht ausgeführt, wenn die Zulassungsliste nicht aktuell ist.

Hinweis: Der Standardwert für globalPolicyEvaluationMode ist derzeit DISABLE, wird in Zukunft aber in ENABLE geändert. Deshalb wird empfohlen, den Wert explizit auf das von Ihnen bevorzugte Verhalten festzulegen.

Hinweis: Wenn Sie den Pfad globalPolicyEvaluationMode deaktivieren möchten, müssen gcr.io/google_containers/*, gcr.io/google-containers/*, k8s.gcr.io/*, gke.gcr.io/* und gcr.io/stackdriver-agents/* in der Zulassungsliste admissionWhitelistPatterns enthalten sein, da sie für den erfolgreichen Start eines GKE-Clusters erforderliche Google Cloud-Ressourcen enthalten. Möglicherweise sind in Zukunft zusätzliche Image-Pfade erforderlich. Diese Pfade müssen außerdem in die Zulassungsliste admissionWhitelistPatterns aufgenommen werden, damit GKE-Cluster wie erwartet ausgeführt werden können.

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