> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt) # circleci/gcp-binary-authorization Configure Google's Binary Authorization service to sign and certify container images for deployment. For more information, see orb source: https://github.com/CircleCI-Public/gcp-binary-authorization-orb ## Commands ### configure-policy Configure a Binary Authorization deployment policy. See the following: https://cloud.google.com/binary-authorization/docs/key-concepts#policies https://cloud.google.com/binary-authorization/docs/configuring-policy-cli https://cloud.google.com/binary-authorization/docs/policy-yaml-reference | Parameter | Type | Default | Description | |---|---|---|---| | `admission-whitelist-patterns` | string | gcr.io/google_containers/*,k8s.gcr.io/*,gcr.io/stackdriver-agents/* | Whitelist of container images that are exempt from the attestation requirements in the policy. Supply a comma-separated string list (e.g., see default value) of paths to images in Google's, or any other, container registry. For details, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admissionwhitelistpatterns | | `attestor-project-id` | env_var_name | ATTESTOR_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `cluster-specific-eval-mode` | enum | REQUIRE_ATTESTATION | For the specified cluster, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `cluster-specific-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, for cluster- specific rulesets? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`, as described here: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `cluster-specific-rules` | boolean | false | Specify distinct sets of deployment rules for individual GKE clusters? If so, pass the requisite values to any additional cluster-specific parameters. Currently, only a single set of cluster- specific rules can be specified. For details, see the following: https://cloud.google.com/binary-authorization/docs/key-concepts#cluster-specific_rules | | `cluster-specific-specifier` | env_var_name | CLUSTER_SPECIFIER_LOCATION_NAME | If specifying a set of cluster-specific rules, what is the name of the GKE cluster to which these rules will apply? Supply an environment variable storing a GKE cluster name in the `location.name` format (e.g., `us-east1-a.prod-cluster`) | | `default-evaluation-mode` | enum | REQUIRE_ATTESTATION | By default, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `default-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, by default? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `deployer-project-id` | env_var_name | DEPLOYER_PROJECT_ID | Name of environment variable storing the Google project ID for the deployer project. Only required if using a multi-project setup. | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | | `policy-filepath` | string | /tmp/policy.yaml | Path to a Binary Authorization policy YAML file. Should be an existing file if `use-policy-file` is `true`; otherwise, a policy file will be created at this path. | | `use-policy-file` | boolean | false | Use an existing Binary Authorization policy YAML file instead of creating one via this command's parameters? | ### create-attestation Create a Binary Authorization attestation authorizing a container image for deployment. See Google's Binary Authorization documentation: https://cloud.google.com/binary-authorization/docs/key-concepts#attestations https://cloud.google.com/binary-authorization/docs/making-attestations | Parameter | Type | Default | Description | |---|---|---|---| | `attestation-project-id` | env_var_name | ATTESTATION_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor` | string | $CIRCLE_USERNAME | Name of the attestation authority for the container analysis note. If the attestor does not yet exist, it will be created. Defaults to the value of the `$CIRCLE_USERNAME` environment variable (VCS user who triggered the CircleCI job). | | `attestor-project-id` | env_var_name | ATTESTOR_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `create-new-gke-cluster` | boolean | false | Create a new GKE cluster to use with Binary Authorization? Defaults to `false` Passed to setup command. | | `enable-apis` | boolean | false | Do required APIs (container.googleapis.com, containeranalysis.googleapis.com, binaryauthorization.googleapis.com) need to be enabled? Passed to setup command. | | `gke-cluster-name` | string | | Name of the GKE cluster for which to enable Binary Authorization Passed to setup command. | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `image-path` | string | | Path in Google's, or any other, container registry to the image being deployed (e.g., `gcr.io/example-project/quickstart-image`) | | `image-tag` | string | latest | Specific tag of image that will be deployed, used to generate a full SHA-256 for attestation. | | `keypair-email` | string | | Email address attached to PGP keypair | | `keypair-passphrase` | env_var_name | BIN_AUTHZ_KEYPAIR_PASSPHRASE | Name of environment variable storing the passphrase used to generate PGP keypair | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | | `payload-filepath` | string | /tmp/generated_payload.json | Path at which to generate an attestation payload | | `private-key` | env_var_name | BIN_AUTHZ_PRIVATE_KEY | Name of environment variable storing the private portion of the keypair with which to sign the attestation. Unless `use-existing-keypair` is set to `false`, store the private key in Contexts or as a project-level environment variable, as a single-line string, with newlines replaced with the newline string literal `\n`. Use an RSA-2048-type key. See Google's documentation for details: https://cloud.google.com/binary-authorization/docs/creating-attestors-cli#create_a_pgp_key_pair | | `public-key` | env_var_name | BIN_AUTHZ_PUBLIC_KEY | Name of environment variable storing the public portion of the keypair with which to sign the attestation. Not required if `use-existing-keypair` is set to `false`. Store the public key in Contexts or as a project-level environment variable, as a single-line string, with newlines replaced with the newline string literal `\n`. Use an RSA-2048-type key. See Google's documentation for details: https://cloud.google.com/binary-authorization/docs/creating-attestors-cli#create_a_pgp_key_pair | | `run-setup` | boolean | false | Set to `true` to handle setup through this command. Helpful if an attestor has not been created before this step. | | `use-existing-keypair` | boolean | true | Use an existing PGP keypair? Only select `false` if a keypair was generated on-the-fly in the `create-attestor` command | | `use-passphrase` | boolean | false | If `use-existing-keypair` is set to `false`: does the existing PGP keypair have a passphrase? If `use-existing-keypair` is set to `true`: was the newly generated PGP keypair created with a passphrase? | ### create-attestor Create an attestor in Binary Authorization. For details, see: https://cloud.google.com/binary-authorization/docs/key-concepts#attestors | Parameter | Type | Default | Description | |---|---|---|---| | `attestor` | string | $CIRCLE_USERNAME | Name of the attestation authority for the container analysis note. If the attestor does not yet exist, it will be created. Defaults to the value of the `$CIRCLE_USERNAME` environment variable (VCS user who triggered the CircleCI job). | | `attestor-project-id` | env_var_name | ATTESTOR_PROJECT_ID | Name of environment variable storing the Google project ID for the`` attestor project. Only required if using a multi-project setup. | | `circle-token` | env_var_name | CIRCLE_TOKEN | Name of environment variable storing a CircleCI API token, for authenticating calls to store project environment variables. Only required if `use-existing-keypair` is set to `false` and `store-generated-keypair` is set to true. | | `deployer-service-account` | env_var_name | DEPLOYER_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the deployer Google project. Only required if using a multi-project setup. | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `keypair-email` | string | | Email address to attach to PGP keypair. Only required here if `use-existing-keypair` is set to `false` (required by subsequent commands either way). | | `keypair-name` | string | | Name to attach to PGP keypair. Only required if `use-existing-keypair` is set to `false`. | | `keypair-passphrase` | env_var_name | BIN_AUTHZ_KEYPAIR_PASSPHRASE | Name of environment variable storing a passphrase to use when generating a PGP keypair. Only required if `use-existing-keypair` is set to `false`. | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | | `note-id` | string | $CIRCLE_USERNAME-note-$CIRCLE_JOB-$CIRCLE_BUILD_NUM | Name of the container analysis note. Defaults to a combination of values from the attestor parameter, and CircleCI job name and number environment variables. | | `private-key` | env_var_name | BIN_AUTHZ_PRIVATE_KEY | Name of environment variable under which to store the private portion of the keypair generated to use with Binary Authorization. Only required here if `use-existing-keypair` is set to `false` and `store-generated-keypair` is set to true (required by subsequent commands either way). | | `public-key` | env_var_name | BIN_AUTHZ_PUBLIC_KEY | Name of environment variable storing the public portion of the keypair with which to sign the attestation. If `use-existing-keypair` is set to `false` and `store-generated-keypair` is set to true, the public key will be stored in CircleCI as a project environment variable under this name. Otherwise, please store the public key in Contexts or as a project-level environment variable, as a single-line string, with newlines replaced with the newline string literal `\n`. Use an RSA- 2048-type key. See Google's PGP key documentation for details: https://cloud.google.com/binary-authorization/docs/creating-attestors-cli#create_a_pgp_key_pair | | `store-generated-keypair` | boolean | true | Store public and private portions of generated keypair as CircleCI environment variables? | | `use-existing-keypair` | boolean | true | Use an existing PGP keypair? If `false`, a keypair will be created on-the-fly | | `use-passphrase` | boolean | false | Generate a PGP keypair with a passphrase? Only required if `use-existing-keypair` is set to `false` | ### create-note Create a Container Analysis note. For details, see the following: https://cloud.google.com/container-registry/docs/container-analysis#note | Parameter | Type | Default | Description | |---|---|---|---| | `attestor` | string | $CIRCLE_USERNAME | Name of the attestation authority for the container analysis note. If the attestor does not yet exist, it will be created. Defaults to the value of the `$CIRCLE_USERNAME` environment variable (VCS user who triggered the CircleCI job). | | `attestor-hint` | string | CircleCI username | A human-readable name for this attestation authority (e.g., QA) | | `attestor-project-id` | env_var_name | ATTESTOR_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor-service-account` | env_var_name | ATTESTOR_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the attestor Google project. Only required if using a multi-project setup. | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `google-service-account` | env_var_name | GOOGLE_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the Google project. Not required if using a multi-project setup. | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | | `note-description-long` | string | | Longer, more detailed description of this note. This will be evaluated. | | `note-description-short` | string | Container analysis note from CircleCI job $CIRCLE_JOB, number $CIRCLE_BUILD_NUM, triggered by $CIRCLE_USERNAME | One-sentence description of this note. This will be evaluated. | | `note-expiration-time` | string | | Timestamp-formatted expiration time for this note (empty if the note does not expire). For details, see the following: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp | | `note-filepath` | string | /tmp/note_payload.json | Path to your container analysis note file. Should be an existing file if `use-note-file` is `true`; otherwise, note will be created at this path. | | `note-id` | string | $CIRCLE_USERNAME-note-$CIRCLE_JOB-$CIRCLE_BUILD_NUM | Name of the container analysis note. Defaults to a combination of values from the attestor parameter, and CircleCI job name and number environment variables. | | `note-related-url` | string | $CIRCLE_BUILD_URL | Any URL related to the note. This will be evaluated. | | `related-note-names` | string | | Names of any notes relevant or related to this note | | `use-note-file` | boolean | false | Upload an existing container analysis note file instead of creating one via this command's parameters? | ### generate-keypair Generate an RSA-2048-type PGP keypair to use with Google's Binary Authorization and optionally store its public and private portions as CircleCI environment variables. | Parameter | Type | Default | Description | |---|---|---|---| | `circle-token` | env_var_name | CIRCLE_TOKEN | Name of environment variable storing a CircleCI API token, for authenticating calls to store project environment variables | | `keypair-email` | string | | Email address to attach to PGP keypair | | `keypair-name` | string | | Name to attach to PGP keypair | | `keypair-passphrase` | env_var_name | BIN_AUTHZ_KEYPAIR_PASSPHRASE | Name of environment variable storing a passphrase to use when generating a PGP keypair (only required if `use-passphrase` is set to `true`) | | `private-key` | env_var_name | BIN_AUTHZ_PRIVATE_KEY | Name of environment variable under which to store the private portion of the keypair generated to use with Binary Authorization | | `public-key` | env_var_name | BIN_AUTHZ_PUBLIC_KEY | Name of environment variable under which to store the public portion of the keypair generated to use with Binary Authorization | | `store-generated-keypair` | boolean | true | Store public and private portions of generated keypair as CircleCI environment variables? | | `use-passphrase` | boolean | false | Generate a PGP keypair with a passphrase? | ### get-gke-credentials Get Google Kubernetes Engine credentials and update a local kubeconfig file to enable further Binary Authorization commands on that cluster. Generally does not need to be run on its own, as it is run as part of both the `run-setup` and `create-attestation` jobs. | Parameter | Type | Default | Description | |---|---|---|---| | `deployer-project-id` | env_var_name | DEPLOYER_PROJECT_ID | Name of environment variable storing the Google project ID for the deployer project. Only required if using a multi-project setup. | | `gke-cluster-name` | string | | Name of the GKE cluster for which to enable Binary Authorization | | `google-compute-zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to use by default when running commands with the gcloud CLI | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | ### setup Get set up to use Google's Binary Authorization on CircleCI. This command is designed to be run once to initialize Binary Authorization for a particular CircleCI project. It will enable all required APIs, optionally create a GKE cluster, create a Container Analysis note and an attestor, optionally generate and store a PGP keypair, and optionally create and store a Binary Authorization policy YAML file. After running this command successfully, it can be removed from your config.yml file. To use this command, at least one existing Google project is required; if using a multi-project Binary Authorization setup, three separate Google projects (deployer, attestor, attestation) are required. For easier execution, this command is also available as an orb job, also called `setup`. For additional information, see Google's Binary Authorization documentation: https://cloud.google.com/binary-authorization/docs/overview | Parameter | Type | Default | Description | |---|---|---|---| | `admission-whitelist-patterns` | string | gcr.io/google_containers/*,k8s.gcr.io/*,gcr.io/stackdriver-agents/* | Whitelist of container images that are exempt from the attestation requirements in the policy. Supply a comma-separated string list (e.g., see default value) of paths to images in Google's, or any other, container registry. For details, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admissionwhitelistpatterns | | `attestation-project-id` | env_var_name | ATTESTATION_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor` | string | $CIRCLE_USERNAME | Name of the attestation authority for the container analysis note. If the attestor does not yet exist, it will be created. Defaults to the value of the `$CIRCLE_USERNAME` environment variable (VCS user who triggered the CircleCI job). | | `attestor-hint` | string | CircleCI username | A human-readable name for this attestation authority (e.g., QA) | | `attestor-project-id` | env_var_name | ATTESTOR_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor-service-account` | env_var_name | ATTESTOR_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the attestor Google project. Only required if using a multi-project setup. | | `circle-token` | env_var_name | CIRCLE_TOKEN | Name of environment variable storing a CircleCI API token, for authenticating calls to store project environment variables | | `cluster-specific-eval-mode` | enum | REQUIRE_ATTESTATION | For the specified cluster, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `cluster-specific-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, for cluster- specific rulesets? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`, as described here: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `cluster-specific-rules` | boolean | false | Specify distinict sets of deployment rules for individual GKE clusters? If so, pass the requisite values to any additional cluster-specific parameters. Currently, only a single set of cluster- specific rules can be specified. For details, see the following: https://cloud.google.com/binary-authorization/docs/key-concepts#cluster-specific_rules | | `cluster-specific-specifier` | env_var_name | CLUSTER_SPECIFIER_LOCATION_NAME | If specifying a set of cluster-specific rules, what is the name of the GKE cluster to which these rules will apply? Supply an environment variable storing a GKE cluster name in the `location.name` format (e.g., `us-east1-a.prod-cluster`) | | `configure-policy` | boolean | true | Configure a Binary Authorization policy as part of setup? Choose `true` if a single policy will most likely persist across future deployments; choose `false` if a new policy will be generated for each deployment. | | `create-new-gke-cluster` | boolean | false | Create a new GKE cluster to use with Binary Authorization? Defaults to `false` | | `default-evaluation-mode` | enum | REQUIRE_ATTESTATION | By default, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `default-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, by default? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `deployer-project-id` | env_var_name | DEPLOYER_PROJECT_ID | Name of environment variable storing the Google project ID for the deployer project. Only required if using a multi-project setup. | | `deployer-service-account` | env_var_name | DEPLOYER_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the deployer Google project. Only required if using a multi-project setup. | | `enable-apis` | boolean | true | Do required APIs (container.googleapis.com, containeranalysis.googleapis.com, binaryauthorization.googleapis.com) need to be enabled? | | `gke-cluster-name` | string | | Name of the GKE cluster for which to enable Binary Authorization | | `google-compute-zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to use by default when running commands with the gcloud CLI | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `google-service-account` | env_var_name | GOOGLE_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the Google project. Not required if using a multi-project setup. | | `keypair-email` | string | | Email address to attach to PGP keypair. Only required here if `use-existing-keypair` is set to `false` (required by subsequent commands either way). | | `keypair-name` | string | | Name to attach to PGP keypair. Only required if `use-existing-keypair` is set to `false`. | | `keypair-passphrase` | env_var_name | BIN_AUTHZ_KEYPAIR_PASSPHRASE | Name of environment variable storing a passphrase to use when generating a PGP keypair. Only required if `use-existing-keypair` is set to `false`. | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | | `note-description-long` | string | | Longer, more detailed description of this note | | `note-description-short` | string | Container analysis note from CircleCI job $CIRCLE_JOB, number $CIRCLE_BUILD_NUM, triggered by $CIRCLE_USERNAME | One-sentence description of this note | | `note-expiration-time` | string | | Timestamp-formatted expiration time for this note (empty if the note does not expire). For details, see the following: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp | | `note-filepath` | string | /tmp/note_payload.json | Path to your container analysis note file. Should be an existing file if `use-note-file` is `true`; otherwise, note will be created at this path. | | `note-id` | string | $CIRCLE_USERNAME-note-$CIRCLE_JOB-$CIRCLE_BUILD_NUM | Name of the container analysis note. Defaults to a combination of values from the attestor parameter, and CircleCI job name and number environment variables. | | `note-related-url` | string | $CIRCLE_BUILD_URL | Any URL related to the note | | `policy-filepath` | string | /tmp/policy.yaml | Path to a Binary Authorization policy YAML file. Should be an existing file if `use-policy-file` is `true`; otherwise, a policy file will be created at this path. | | `private-key` | env_var_name | BIN_AUTHZ_PRIVATE_KEY | Name of environment variable under which to store the private portion of the keypair generated to use with Binary Authorization. Only required here if `use-existing-keypair` is set to `false` and `store-generated-keypair` is set to true (required by subsequent commands either way). | | `public-key` | env_var_name | BIN_AUTHZ_PUBLIC_KEY | Name of environment variable storing the public portion of the keypair with which to sign the attestation. If `use-existing-keypair` is set to `false` and `store-generated-keypair` is set to true, the public key will be stored in CircleCI as a project environment variable under this name. Otherwise, please store the public key in Contexts or as a project-level environment variable, as a single-line string, with newlines replaced with the newline string literal `\n`. Use an RSA- 2048-type key. See Google's PGP key documentation for details: https://cloud.google.com/binary-authorization/docs/creating-attestors-cli#create_a_pgp_key_pair | | `related-note-names` | string | | Names of any notes relevant or related to this note | | `store-generated-keypair` | boolean | true | Store public and private portions of generated keypair as CircleCI environment variables? | | `use-existing-keypair` | boolean | true | Use an existing PGP keypair? If `false`, a keypair will be created on-the-fly | | `use-note-file` | boolean | false | Upload an existing container analysis note file instead of creating one via this command's paramaters? | | `use-passphrase` | boolean | false | Generate a PGP keypair with a passphrase? Only required if `use-existing-keypair` is set to `false` | | `use-policy-file` | boolean | false | Use an existing Binary Authorization policy YAML file instead of creating one via this command's paramaters? | ## Jobs ### create-attestation Sign/authorize a specific tag of a container image stored in a Google container registry for deployment to Google Kubernetes Engine. For details, see Google's Binary Authorization documentation: https://cloud.google.com/binary-authorization/docs | Parameter | Type | Default | Description | |---|---|---|---| | `admission-whitelist-patterns` | string | gcr.io/google_containers/*,k8s.gcr.io/*,gcr.io/stackdriver-agents/* | Whitelist of container images that are exempt from the attestation requirements in the policy. Supply a comma-separated string list (e.g., see default value) of paths to images in Google's, or any other, container registry. For details, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admissionwhitelistpatterns | | `attach-workspace` | boolean | false | Attach to an existing workspace? Default is `false` | | `attestation-project-id` | env_var_name | ATTESTATION_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor` | string | $CIRCLE_USERNAME | Name of the attestation authority for the container analysis note. If the attestor does not yet exist, it will be created. Defaults to the value of the `$CIRCLE_USERNAME` environment variable (VCS user who triggered the CircleCI job). | | `attestor-hint` | string | CircleCI username | A human-readable name for this attestation authority (e.g., QA) | | `attestor-project-id` | env_var_name | ATTESTOR_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor-service-account` | env_var_name | ATTESTOR_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the attestor Google project. Only required if using a multi-project setup. | | `checkout` | boolean | false | Checkout as a first step? Default is `false` | | `circle-token` | env_var_name | CIRCLE_TOKEN | Name of environment variable storing a CircleCI API token, for authenticating calls to store project environment variables | | `cluster-specific-eval-mode` | enum | REQUIRE_ATTESTATION | For the specified cluster, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `cluster-specific-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, for cluster- specific rulesets? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`, as described here: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `cluster-specific-rules` | boolean | false | Specify distinict sets of deployment rules for individual GKE clusters? If so, pass the requisite values to any additional cluster-specific parameters. Currently, only a single set of cluster- specific rules can be specified. For details, see the following: https://cloud.google.com/binary-authorization/docs/key-concepts#cluster-specific_rules | | `cluster-specific-specifier` | env_var_name | CLUSTER_SPECIFIER_LOCATION_NAME | If specifying a set of cluster-specific rules, what is the name of the GKE cluster to which these rules will apply? Supply an environment variable storing a GKE cluster name in the `location.name` format (e.g., `us-east1-a.prod-cluster`) | | `configure-policy` | boolean | false | Configure a new Binary Authorization policy for this attestation? Choose `false` to use the existing policy stored in Binary Authorization | | `create-new-gke-cluster` | boolean | false | Create a new GKE cluster to use with Binary Authorization? Default is `false` | | `default-evaluation-mode` | enum | REQUIRE_ATTESTATION | By default, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `default-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, by default? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `deployer-project-id` | env_var_name | DEPLOYER_PROJECT_ID | Name of environment variable storing the Google project ID for the deployer project. Only required if using a multi-project setup. | | `deployer-service-account` | env_var_name | DEPLOYER_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the deployer Google project. Only required if using a multi-project setup. | | `deployer-service-key` | env_var_name | DEPLOYER_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the deployer Google project. Only required if using a multi- project setup. | | `deployment-steps` | steps | | Optional deployment steps to run after signing an image for release. See the `deploy-attested-image` usage example for one possible implementation. | | `enable-apis` | boolean | true | Do required APIs (container.googleapis.com, containeranalysis.googleapis.com, binaryauthorization.googleapis.com) need to be enabled? | | `executor` | executor | default | Executor to use for this job, defaults to Google's official Docker image with the gcloud CLI preinstalled | | `gke-cluster-name` | string | | Name of the GKE cluster for which to enable Binary Authorization | | `google-compute-zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to use by default when running commands with the gcloud CLI | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `google-service-account` | env_var_name | GOOGLE_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the Google project. Not required if using a multi-project setup. | | `google-service-key` | env_var_name | GOOGLE_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the Google project. Not required if using a multi-project setup. | | `image-path` | string | | Path in Google's, or any other, container registry to the image being deployed (e.g., `gcr.io/example-project/quickstart-image`) | | `image-tag` | string | latest | Specific tag of image that will be deployed, used to generate a full SHA-256 for attestation. | | `keypair-email` | string | | Email address attached to existing PGP keypair, or to attach to newly created keypair. | | `keypair-name` | string | | Name to attach to PGP keypair. Only required if `use-existing-keypair` is set to `false`. | | `keypair-passphrase` | env_var_name | BIN_AUTHZ_KEYPAIR_PASSPHRASE | Name of environment variable storing the passphrase used to generate PGP keypair | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | | `note-description-long` | string | | Longer, more detailed description of container analysis note | | `note-description-short` | string | Container analysis note from CircleCI job $CIRCLE_JOB, number $CIRCLE_BUILD_NUM, triggered by $CIRCLE_USERNAME | One-sentence description of this note | | `note-expiration-time` | string | | Timestamp-formatted expiration time for this note (empty if the note does not expire). For details, see the following: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp | | `note-filepath` | string | /tmp/note_payload.json | Path to your container analysis note file. Should be an existing file if `use-note-file` is `true`; otherwise, note will be created at this path. | | `note-id` | string | $CIRCLE_USERNAME-note-$CIRCLE_JOB-$CIRCLE_BUILD_NUM | Name of the container analysis note. Defaults to a combination of values from the attestor parameter, and CircleCI job name and number environment variables. | | `note-related-url` | string | $CIRCLE_BUILD_URL | Any URL related to the container analysis note | | `payload-filepath` | string | /tmp/generated_payload.json | Path at which to generate an attestation payload | | `policy-filepath` | string | /tmp/policy.yaml | Path to a Binary Authorization policy YAML file. Should be an existing file if `use-policy-file` is `true`; otherwise, a policy file will be created (`configure-policy`) or imported (`import-existing- policy`) at this path. | | `private-key` | env_var_name | BIN_AUTHZ_PRIVATE_KEY | Name of environment variable storing (or under which to store, if `use-existing-keypair` is false and `store-generated-keypair` is true) the private portion of the keypair with which to sign the attestation. If `use-existing-keypair` is true, store the private key in Contexts or as a project-level environment variable, as a single- line string, with newlines replaced with the newline string literal `\n`. Use an RSA-2048-type key. For details, see the following documentation: https://cloud.google.com/binary-authorization/docs/creating-attestors-cli#create_a_pgp_key_pair | | `public-key` | env_var_name | BIN_AUTHZ_PUBLIC_KEY | Name of environment variable storing (or under which to store, if `use-existing-keypair` is false and `store-generated-keypair` is true) the public portion of the keypair with which to sign the attestation. If `use-existing-keypair` is true, store the public key in Contexts or as a project-level environment variable, as a single- line string, with newlines replaced with the newline string literal `\n`. Use an RSA-2048-type key. For details, see the following documentation: https://cloud.google.com/binary-authorization/docs/creating-attestors-cli#create_a_pgp_key_pair | | `related-note-names` | string | | Names of any notes relevant or related to this note | | `run-setup` | boolean | false | Run Binary Authorization setup steps? Setup steps are designed to be run once to initialize Binary Authorization for a particular CircleCI project. | | `store-generated-keypair` | boolean | true | Store public and private portions of generated keypair as CircleCI environment variables? | | `use-existing-keypair` | boolean | true | Use an existing PGP keypair? If `false`, a keypair will be created on-the-fly | | `use-note-file` | boolean | false | Upload an existing container analysis note file instead of creating one via this command's paramaters? | | `use-passphrase` | boolean | false | If `use-existing-keypair` is set to `false`: does the existing PGP keypair have a passphrase? If `use-existing-keypair` is set to `true`: generate a PGP keypair with a passphrase? | | `use-policy-file` | boolean | false | Use a locally stored Binary Authorization policy YAML file instead of creating one via this command's paramaters (`configure-policy`) or using an existing policy already stored in Binary Authorization? | | `workspace-root` | string | workspace | Workspace root path that is either an absolute path or a path relative to the working directory. | ### run-setup Get set up to use Google's Binary Authorization on CircleCI. This job is designed to be run once to initialize Binary Authorization for a particular CircleCI project. It will enable all required APIs, optionally create a GKE cluster, create an attestor, optionally generate and store a PGP keypair, and optionally create and store a Binary Authorization policy YAML file. After running this job successfully, it can be removed from your config.yml file. To use this job, at least one existing Google project is required; if using a multi-project Binary Authorization setup, three separate Google projects (deployer, attestor, attestation) are required. This job is also available as an orb command, also called `setup`, if more control over its mode of execution is desired. For further information, see Google's Binary Authorization documentation: https://cloud.google.com/binary-authorization/docs/overview | Parameter | Type | Default | Description | |---|---|---|---| | `admission-whitelist-patterns` | string | gcr.io/google_containers/*,k8s.gcr.io/*,gcr.io/stackdriver-agents/* | Whitelist of container images that are exempt from the attestation requirements in the policy. Supply a comma-separated string list (e.g., see default value) of paths to images in Google's, or any other, container registry. For details, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admissionwhitelistpatterns | | `attach-workspace` | boolean | false | Attach to an existing workspace? Default is `false` | | `attestation-project-id` | env_var_name | ATTESTATION_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor` | string | $CIRCLE_USERNAME | Name of the attestation authority for the container analysis note. If the attestor does not yet exist, it will be created. Defaults to the value of the `$CIRCLE_USERNAME` environment variable (VCS user who triggered the CircleCI job). | | `attestor-hint` | string | CircleCI username | A human-readable name for this attestation authority (e.g., QA) | | `attestor-project-id` | env_var_name | ATTESTOR_PROJECT_ID | Name of environment variable storing the Google project ID for the attestor project. Only required if using a multi-project setup. | | `attestor-service-account` | env_var_name | ATTESTOR_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the attestor Google project. Only required if using a multi-project setup. | | `checkout` | boolean | false | Checkout as a first step? Default is `false` | | `circle-token` | env_var_name | CIRCLE_TOKEN | Name of environment variable storing a CircleCI API token, for authenticating calls to store project environment variables. Only required if generating and storing a new keypair. | | `cluster-specific-eval-mode` | enum | REQUIRE_ATTESTATION | For the specified cluster, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `cluster-specific-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, for cluster- specific rulesets? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`, as described here: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `cluster-specific-rules` | boolean | false | Specify distinict sets of deployment rules for individual GKE clusters? If so, pass the requisite values to any additional cluster-specific parameters. Currently, only a single set of cluster- specific rules can be specified. For details, see the following: https://cloud.google.com/binary-authorization/docs/key-concepts#cluster-specific_rules | | `cluster-specific-specifier` | env_var_name | CLUSTER_SPECIFIER_LOCATION_NAME | If specifying a set of cluster-specific rules, what is the name of the GKE cluster to which these rules will apply? Supply an environment variable storing a GKE cluster name in the `location.name` format (e.g., `us-east1-a.prod-cluster`) | | `configure-policy` | boolean | true | Configure a Binary Authorization policy as part of setup? Choose `true` if a single policy will most likely persist across future deployments; choose `false` if a new policy will be generated for each deployment. | | `create-new-gke-cluster` | boolean | false | Create a new GKE cluster to use with Binary Authorization? Defaults to `false` | | `default-evaluation-mode` | enum | REQUIRE_ATTESTATION | By default, how should Binary Authorization evaluate deployment requests? For details on these options, see the following: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#evaluationmode | | `default-required-attestors` | string | projects/$GOOGLE_PROJECT_ID/attestors/$CIRCLE_USERNAME | What attestors will be required to sign releases, by default? Specify attestors in the form `project/PROJECT_ID/attestors/ATTESTOR_NAME`: https://cloud.google.com/binary-authorization/docs/policy-yaml-reference#admission_rule To specify multiple attestors, use a comma-separated string. | | `deployer-project-id` | env_var_name | DEPLOYER_PROJECT_ID | Name of environment variable storing the Google project ID for the deployer project. Only required if using a multi-project setup. | | `deployer-service-account` | env_var_name | DEPLOYER_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the deployer Google project. Only required if using a multi-project setup. | | `deployer-service-key` | env_var_name | DEPLOYER_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the deployer Google project. Only required if using a multi- project setup. | | `enable-apis` | boolean | true | Do required APIs (container.googleapis.com, containeranalysis.googleapis.com, binaryauthorization.googleapis.com) need to be enabled? | | `executor` | executor | default | Executor to use for this job, defaults to Google's official Docker image with the gcloud CLI preinstalled | | `gke-cluster-name` | string | | Name of the GKE cluster for which to enable Binary Authorization | | `google-compute-zone` | env_var_name | GOOGLE_COMPUTE_ZONE | Name of environment variable storing the Google compute zone to use by default when running commands with the gcloud CLI | | `google-project-id` | env_var_name | GOOGLE_PROJECT_ID | Name of environment variable storing the Google project ID. Not required if using a multi-project setup. | | `google-service-account` | env_var_name | GOOGLE_SERVICE_ACCOUNT | Name of environment variable storing the service account address for the Google project. Not required if using a multi-project setup. | | `google-service-key` | env_var_name | GOOGLE_SERVICE_KEY | Name of environment variable storing the full service key JSON file for the Google project. Not required if using a multi-project setup. | | `keypair-email` | string | | Email address to attach to PGP keypair. Only required here if `use-existing-keypair` is set to `false` (required by subsequent commands either way). | | `keypair-name` | string | | Name to attach to PGP keypair. Only required if `use-existing-keypair` is set to `false`. | | `keypair-passphrase` | env_var_name | BIN_AUTHZ_KEYPAIR_PASSPHRASE | Name of environment variable storing a passphrase to use when generating a PGP keypair. Only required if `use-existing-keypair` is set to `false`. | | `multi-project-setup` | boolean | false | Set to `true` if a multi-GCP project Binary Authorization setup is being used. See the following for details: https://cloud.google.com/binary-authorization/docs/multi-project-setup-cli | | `note-description-long` | string | | Longer, more detailed description of this note | | `note-description-short` | string | Container analysis note from CircleCI job $CIRCLE_JOB, number $CIRCLE_BUILD_NUM, triggered by $CIRCLE_USERNAME | One-sentence description of this note | | `note-expiration-time` | string | | Timestamp-formatted expiration time for this note (empty if the note does not expire). For details, see the following: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp | | `note-filepath` | string | /tmp/note_payload.json | Path to your container analysis note file. Should be an existing file if `use-note-file` is `true`; otherwise, note will be created at this path. | | `note-id` | string | $CIRCLE_USERNAME-note-$CIRCLE_JOB-$CIRCLE_BUILD_NUM | Name of the container analysis note. Defaults to a combination of values from the attestor parameter, and CircleCI job name and number environment variables. | | `note-related-url` | string | $CIRCLE_BUILD_URL | Any URL related to the note | | `policy-filepath` | string | /tmp/policy.yaml | Path to a Binary Authorization policy YAML file. Should be an existing file if `use-policy-file` is `true`; otherwise, a policy file will be created at this path. | | `private-key` | env_var_name | BIN_AUTHZ_PRIVATE_KEY | Name of environment variable under which to store the private portion of the keypair generated to use with Binary Authorization. Only required here if `use-existing-keypair` is set to `false` and `store-generated-keypair` is set to true (required by subsequent commands either way). | | `public-key` | env_var_name | BIN_AUTHZ_PUBLIC_KEY | Name of environment variable storing or under which to store the public portion of the keypair with which to sign the attestation. Not required if `use-existing-keypair` is set to `false`. Store the public key in Contexts or as a project-level environment variable, as a single-line string, with newlines replaced with the newline string literal `\n`. Use an RSA-2048-type key. See Google's documentation: https://cloud.google.com/binary-authorization/docs/creating-attestors-cli#create_a_pgp_key_pair | | `related-note-names` | string | | Names of any notes relevant or related to this note | | `store-generated-keypair` | boolean | true | Store public and private portions of generated keypair as CircleCI environment variables? | | `use-existing-keypair` | boolean | true | Use an existing PGP keypair? If `false`, a keypair will be created on-the-fly | | `use-note-file` | boolean | false | Upload an existing container analysis note file instead of creating one via this command's paramaters? | | `use-passphrase` | boolean | false | Generate a PGP keypair with a passphrase? Only required if `use-existing-keypair` is set to `false` | | `use-policy-file` | boolean | false | Use an existing Binary Authorization policy YAML file instead of creating one via this command's paramaters? | | `workspace-root` | string | workspace | Workspace root path that is either an absolute path or a path relative to the working directory. | ## Executors ### default The official Google Docker container with the gcloud SDK pre-installed | Parameter | Type | Default | Description | |---|---|---|---| | `resource-class` | enum | medium | The resource_class with which this job should be run: https://circleci.com/docs/2.0/configuration-reference/#resource_class | | `tag` | string | latest | Version of the Google Cloud SDK Docker image to use. For full list, see https://hub.docker.com/r/google/cloud-sdk/tags | ### machine CircleCI's VM image, often useful for working with Docker images | Parameter | Type | Default | Description | |---|---|---|---| | `image-tag` | string | ubuntu-2204:2022.04.2 | Version of CircleCI's machine executor to use. For full list, see https://circleci.com/docs/2.0/configuration-reference/#machine | ## Examples ### setup-and-create-keypair Get set up to use Binary Authorization on CircleCI. The `run-setup` job will enable all required GCP APIs; enable Binary Authorization for a given GKE cluster (and first create that cluster, if necessary); create a container analysis note; create an attestor; and, optionally, create a Binary Authorization policy. This example also creates a new PGP keypair and stores it in CircleCI as environment variables for future attestation signing, and otherwise uses the minimum required parameters that do not have default values. ```yaml version: '2.1' orbs: bin-authz: circleci/gcp-binary-authorization@x.y.z workflows: setup_binary_authorization: jobs: - bin-authz/run-setup: gke-cluster-name: your-cluster keypair-email: email-for-your-keypair keypair-name: name-for-your-keypair use-existing-keypair: false workflows: null ``` ### setup-and-run-binary-authorization Get set up to use Binary Authorization on CircleCI, and complete an attestation signing for a particular container image, all at once. The `create-attestation` job will run all required setup commands, then create and sign an attestation allowing the container image to be successfully deployed. This example uses the minimum required parameters and thus assumes the following: there is an existing GKE cluster to use with Binary Authorization, and there is an existing PGP keypair stored in CircleCI. A container analysis note, attestor, Binary Authorization policy, and attestation are created on-the-fly. Although not shown in this example, a Docker image would likely be built and deployed to a staging/test environment in a previous job, and then deployed to a production cluster in a subsequent job. ```yaml version: '2.1' orbs: bin-authz: circleci/gcp-binary-authorization@x.y.z workflows: setup_and_run_binary_authorization: jobs: - bin-authz/create-attestation: configure-policy: true deployment-steps: - run: > echo "your deployment logic can live here" echo "or in a subsequent workflow job" echo "see `simple-deploy-attested-image` example for sample kubectl deployment syntax" gke-cluster-name: your-gke-cluster image-path: e.g., gcr.io/your-project/your-image image-tag: tag-that-will-be-deployed keypair-email: email-address@used-to-generate-keypair.com note-description-long: | Longform description of container analysis note run-setup: true ``` ### setup-only-simple Get set up to use Binary Authorization on CircleCI. The `run-setup` job will enable all required GCP APIs; enable Binary Authorization for a given GKE cluster (and first create that cluster, if necessary); create a container analysis note; create an attestor; and, optionally, create a Binary Authorization policy. This simple example uses the minimum required parameters that do not have default values. ```yaml version: '2.1' orbs: bin-authz: circleci/gcp-binary-authorization@x.y.z workflows: setup_binary_authorization: jobs: - bin-authz/run-setup: gke-cluster-name: your-cluster workflows: null ``` ### simple-deploy-attested-image In the first job, use the GCP GCR Orb to push an image to a Google Container Registry. In the second job, use the Binary Authorization Orb to sign the image for release, then deploy the image to Google Kubernetes Engine. ```yaml version: '2.1' orbs: bin-authz: circleci/gcp-binary-authorization@x.y.z gcp-gcr: circleci/gcp-gcr@x.y.z workflows: push_sign_deploy: jobs: - gcp-gcr/build_and_push_image: context: your-context image: your-image registry-url: gcr.io tag: your-tag - bin-authz/create-attestation: attestor: $CIRCLE_USERNAME context: your-context deployment-steps: - run: | kubectl run your-server \ --image gcr.io/$GOOGLE_PROJECT_ID/your-image@$YOUR_IMAGE_DIGEST \ --port 8080 gke-cluster-name: your-GKE-cluster-name image-path: gcr.io/$GOOGLE_PROJECT_ID/your-image image-tag: your-tag keypair-email: email.address@used.to.generate.keypair.com note-filepath: your-container-analysis-note.json policy-filepath: your-binauthz-policy-file.yaml requires: - gcp-gcr/build_and_push_image use-note-file: true use-policy-file: true ```