google.cloud.gcp_binaryauthorization_policy module – Manages a BinaryAuthorization.Policy resource

Note

This module is part of the google.cloud collection (version 1.15.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install google.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: google.cloud.gcp_binaryauthorization_policy.

Synopsis

  • A policy for container image binary authorization.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 3.8

  • requests >= 2.18.4

  • google-auth >= 2.25.1

Parameters

Parameter

Comments

access_token

string

The access token used to authenticate.

admission_whitelist_patterns

list / elements=dictionary

A whitelist of image patterns to exclude from admission rules.

If an image’s name matches a whitelist pattern, the image’s admission requests will always be permitted regardless of your admission rules.

name_pattern

string / required

An image name pattern to whitelist, in the form `registry/path/to/image`.

This supports a trailing * as a wildcard, but this is allowed only in text after the registry/ part.

auth_kind

string / required

The type of credential used.

Choices:

  • "accesstoken"

  • "application"

  • "machineaccount"

  • "serviceaccount"

cluster_admission_rules

list / elements=dictionary

Per-cluster admission rules.

An admission rule specifies either that all container images used in a pod creation request must be attested to by one or more attestors, that all pod creations will be allowed, or that all pod creations will be denied.

There can be at most one admission rule per cluster spec.

Identifier format: `{{location}}.{{clusterId}}`.

A location is either a compute zone (e.g.

`us-central1-a`) or a region (e.g.

`us-central1`).

cluster

string / required

The identifier for this cluster_admission_rules entry, used as the map key.

enforcement_mode

string / required

The action when a pod creation is denied by the admission rule.

Choices:

  • "ENFORCED_BLOCK_AND_AUDIT_LOG"

  • "DRYRUN_AUDIT_LOG_ONLY"

evaluation_mode

string / required

How this admission rule will be evaluated.

Choices:

  • "ALWAYS_ALLOW"

  • "REQUIRE_ATTESTATION"

  • "ALWAYS_DENY"

require_attestations_by

list / elements=string

The resource names of the attestors that must attest to a container image.

If the attestor is in a different project from the policy, it should be specified in the format `projects/*/attestors/*`.

Each attestor must exist before a policy can reference it.

To add an attestor to a policy the principal issuing the policy change request must be able to read the attestor resource.

Note: this field must be non-empty when the evaluation_mode field specifies REQUIRE_ATTESTATION, otherwise it must be empty.

default_admission_rule

dictionary / required

Default admission rule for a cluster without a per-cluster admission rule.

enforcement_mode

string / required

The action when a pod creation is denied by the admission rule.

Choices:

  • "ENFORCED_BLOCK_AND_AUDIT_LOG"

  • "DRYRUN_AUDIT_LOG_ONLY"

evaluation_mode

string / required

How this admission rule will be evaluated.

Choices:

  • "ALWAYS_ALLOW"

  • "REQUIRE_ATTESTATION"

  • "ALWAYS_DENY"

require_attestations_by

list / elements=string

The resource names of the attestors that must attest to a container image.

If the attestor is in a different project from the policy, it should be specified in the format `projects/*/attestors/*`.

Each attestor must exist before a policy can reference it.

To add an attestor to a policy the principal issuing the policy change request must be able to read the attestor resource.

Note: this field must be non-empty when the evaluation_mode field specifies REQUIRE_ATTESTATION, otherwise it must be empty.

description

string

A descriptive comment.

env_type

string

Specifies which Ansible environment you’re running this module within.

This should not be set unless you know what you’re doing.

This only alters the User Agent string for any API requests.

global_policy_evaluation_mode

string

Controls the evaluation of a Google-maintained global admission policy for common system-level images.

Images not covered by the global policy will be subject to the project admission policy.

Choices:

  • "ENABLE"

  • "DISABLE"

project

string

The Google Cloud Platform project to use.

scopes

list / elements=string

Array of scopes to be used.

service_account_contents

jsonarg

The contents of a Service Account JSON file,

either in a dictionary or as a JSON string that represents it.

service_account_email

string

An optional service account email address if machineaccount is

selected and the user does not wish to use the default email.

service_account_file

path

The path of a Service Account JSON file if serviceaccount

is selected as type.

state

string

Whether the resource should exist.

Choices:

  • "present" ← (default)

  • "absent"

Notes

Note

Examples

- name: Create Custom Policy
  google.cloud.gcp_binaryauthorization_policy:
    state: present
    admission_whitelist_patterns:
      - name_pattern: "gcr.io/google_containers/*"
    default_admission_rule:
      evaluation_mode: ALWAYS_ALLOW
      enforcement_mode: ENFORCED_BLOCK_AND_AUDIT_LOG
    cluster_admission_rules:  # enforce attestations in a given cluster
      - cluster: us-central1-a.my-cluster
        evaluation_mode: REQUIRE_ATTESTATION
        enforcement_mode: ENFORCED_BLOCK_AND_AUDIT_LOG
        require_attestations_by:
          - projects/my-project/attestors/attestor-1
          - projects/my-project/attestors/attestor-2

################################################################################

- name: Delete Custom Policy (reset to default)
  google.cloud.gcp_binaryauthorization_policy:
    state: absent
    default_admission_rule:
      evaluation_mode: ALWAYS_ALLOW
      enforcement_mode: ENFORCED_BLOCK_AND_AUDIT_LOG

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

admissionWhitelistPatterns

list / elements=dictionary

A whitelist of image patterns to exclude from admission rules.

If an image’s name matches a whitelist pattern, the image’s admission requests will always be permitted regardless of your admission rules.

Returned: when set

namePattern

string

An image name pattern to whitelist, in the form `registry/path/to/image`.

This supports a trailing * as a wildcard, but this is allowed only in text after the registry/ part.

Returned: always

changed

boolean

Whether the resource was changed.

Returned: always

clusterAdmissionRules

list / elements=dictionary

Per-cluster admission rules.

An admission rule specifies either that all container images used in a pod creation request must be attested to by one or more attestors, that all pod creations will be allowed, or that all pod creations will be denied.

There can be at most one admission rule per cluster spec.

Identifier format: `{{location}}.{{clusterId}}`.

A location is either a compute zone (e.g.

`us-central1-a`) or a region (e.g.

`us-central1`).

Returned: when set

cluster

string

The identifier for this ClusterAdmissionRules entry, used as the map key.

Returned: success

enforcementMode

string

The action when a pod creation is denied by the admission rule.

Returned: always

evaluationMode

string

How this admission rule will be evaluated.

Returned: always

requireAttestationsBy

list / elements=string

The resource names of the attestors that must attest to a container image.

If the attestor is in a different project from the policy, it should be specified in the format `projects/*/attestors/*`.

Each attestor must exist before a policy can reference it.

To add an attestor to a policy the principal issuing the policy change request must be able to read the attestor resource.

Note: this field must be non-empty when the evaluation_mode field specifies REQUIRE_ATTESTATION, otherwise it must be empty.

Returned: when set

defaultAdmissionRule

dictionary

Default admission rule for a cluster without a per-cluster admission rule.

Returned: always

enforcementMode

string

The action when a pod creation is denied by the admission rule.

Returned: always

evaluationMode

string

How this admission rule will be evaluated.

Returned: always

requireAttestationsBy

list / elements=string

The resource names of the attestors that must attest to a container image.

If the attestor is in a different project from the policy, it should be specified in the format `projects/*/attestors/*`.

Each attestor must exist before a policy can reference it.

To add an attestor to a policy the principal issuing the policy change request must be able to read the attestor resource.

Note: this field must be non-empty when the evaluation_mode field specifies REQUIRE_ATTESTATION, otherwise it must be empty.

Returned: when set

description

string

A descriptive comment.

Returned: when set

globalPolicyEvaluationMode

string

Controls the evaluation of a Google-maintained global admission policy for common system-level images.

Images not covered by the global policy will be subject to the project admission policy.

Returned: when set

state

string

The current state of the resource.

Returned: always

Authors

  • Google Inc. (@googlecloudplatform)