A walk-through of CircleCI’s Binary Authorization orb

At Next ‘19, Google announced the general-availability release of Binary Authorization, a security control for container images deployed on Google Kubernetes Engine, with CircleCI as a launch partner. Our Binary Authorization orb simplifies the process of validating images built, tested, and deployed using CircleCI, ensuring only those images that have been signed by trusted authorities during the CI/CD process can be run on GKE.

Binary Authorization, like Grafeas’ Kritis, its open source, cloud-agnostic counterpart, employs a set of distinct RESTful resources to manage and certify the software release process:

  • Policies: sets of rules describing which container images may be deployed to particular Kubernetes clusters, after being authorized by specific attestors;
  • Attestors: named parties, machine or human, that verify container images’ readiness for deployment by creating and signing attestations;
  • Attestations: statements by attestors certifying that individual images have met all the conditions required for deployment.

These concepts dovetail with CircleCI features like restricted contexts, which gate collections of secrets and environment variables to particular user groups, and manual approval jobs. Together, these resources allow developer-operations teams to craft comprehensive software supply chain security processes, tailored to their needs and specifications, using combinations of automated and manual checks as desired to balance time-to-deploy and reliability/security.

CircleCI’s orb makes it easy to get started with Binary Authorization. A single job, create-attestation, can walk you through the entire process of creating policies, attestors, and attestations. Spin up a brand-new GKE cluster using the orb, or drop in a reference to a pre-existing cluster. Define a policy on the fly, or bring your own. The orb will even generate and store a PGP keypair, used by attestors to sign attestations (support for asymmetric keys via Google’s Cloud Key Management Service is up next on the orb’s roadmap). The only prerequisite is a single project in Google Cloud Platform, or, for a multi-project setup, three separate GCP projects (deployer, attestor, attestation).

Paired with CircleCI’s Google Container Registry orb, the Binary Authorization orb can provide a complete deployment solution in a few lines of YAML, as seen in this simple-deploy-attested-image example:

version: 2.1

orbs:
  gcp-gcr: circleci/gcp-gcr@x.y.z
  bin-authz: circleci/gcp-binary-authorization@x.y.z

workflows:
  push_sign_deploy:
    jobs:
      - gcp-gcr/build_and_push_image:
          context: your-context # context containing any required env vars
          image: your-image # your image name
          registry-url: gcr.io # default value, here for clarity
          tag: your-tag # default value

      - bin-authz/create-attestation:
          context: your-context
          attestor: $CIRCLE_USERNAME # default value
          keypair-email: email.address@used.to.generate.keypair.com
          gke-cluster-name: your-GKE-cluster-name
          use-note-file: true
          note-filepath: your-container-analysis-note.json
          use-policy-file: true
          policy-filepath: your-binauthz-policy-file.yaml
          image-path: gcr.io/$GOOGLE_PROJECT_ID/your-image
          image-tag: your-tag
          requires: [gcp-gcr/build_and_push_image]
          deployment-steps:
            - run: |
                kubectl run your-server \
                  --image gcr.io/$GOOGLE_PROJECT_ID/your-image@$YOUR_IMAGE_DIGEST \
                  --port 8080

The Binary Authorization orb has a large number of parameters, but don’t be overwhelmed—they have been designed with sensible defaults, minimizing boilerplate in most use cases. For further guidance, see the orb’s other usage examples (its GitHub repository also has additional instructions).

Finally, since all CircleCI orbs are open source, if there’s something else you’d like to see in this orb, we always welcome issues and pull requests — and our active community of orb developers and users can help address any questions about this or any other of our orbs.