Use the policy evaluation service

This page shows you how to use the policy evaluation service Google Cloud CLI command to rapidly evaluate whether an image or Kubernetes resource conforms to a continuous validation check-based platform policy.

Overview

The policy evaluation service is a feature of Binary Authorization that you can use with continuous validation (CV) check-based platform policies. The policy evaluation service evaluates on demand whether a container image that you specify conforms to a CV platform policy. The policy evaluation service is available as a gcloud CLI command and the projects.platforms.gke.policies.evaluate method.

CV checks for policy violations at least once every 24 hours. As a result, it can take up to 24 hours for CV events to appear in Logging after CV is enabled or a Kubernetes resource is deployed. Additionally, CV produces log entries when it detects a policy violation. CV doesn't produce log entries when Kubernetes resources conform to the policy.

The policy evaluation service outputs a verdict that indicates whether the image is conformant with the policy or whether the image violates the policy.

By using the policy evaluation service, you can rapidly determine whether your image conforms to a policy.

When you use the service, you specify the image URL, either directly or within a Kubernetes resource, and you also specify the name of the GKE CV check-based policy.

In this way, the policy evaluation service service can help you to develop policies and debug non-conformant Kubernetes resources before you use CV.

This feature supports only GKE CV check-based policies.

Images must also specify an image digest in the form IMAGE_URL@IMAGE_DIGEST, except in the following cases:

  • Trusted directory check: The check passes if the image is located in a directory that you specify.
  • Exempt image allowlists: All other checks require an image digest in the form IMAGE_URL@IMAGE_DIGEST.

Before you begin

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

Required roles

To get the permissions that you need to use the policy evaluation service, ask your administrator to grant you the Policy Evaluator (roles/binaryauthorization.policyEvaluator) IAM role on the policy project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

If your policy uses certain checks, you might need to ask your administrator to grant the following check-specific required roles:

Evaluate check-based platform policies

The policy evaluation service can evaluate a single image URL or an image that is specified in a JSON-formatted or YAML-formatted Kubernetes resource.

Evaluate check-based platform policies with a Kubernetes resource

To evaluate a policy with a Kubernetes resource using the gcloud CLI, run the following command:

Before using any of the command data below, make the following replacements:

  • POLICY_ID: The ID of the platform policy. If the policy is in another project, you can use the full resource name: projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID.
  • POD_SPECIFICATION_PATH: The path of your Pod specification.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta container binauthz policy evaluate POLICY_ID \
    --resource=POD_SPECIFICATION_PATH

Windows (PowerShell)

gcloud beta container binauthz policy evaluate POLICY_ID `
    --resource=POD_SPECIFICATION_PATH

Windows (cmd.exe)

gcloud beta container binauthz policy evaluate POLICY_ID ^
    --resource=POD_SPECIFICATION_PATH

To evaluate a policy that specifies the platform, which must be set to gke, run the following command:

Before using any of the command data below, make the following replacements:

  • POLICY_ID: The ID of the platform policy. If the policy is in another project, you can use the full resource name: projects/POLICY_PROJECT_ID/platforms/gke/policies/POLICY_ID.
  • POD_SPECIFICATION_PATH: The path of your Pod specification.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta container binauthz policy evaluate POLICY_ID \
    --platform=gke \
    --resource=POD_SPECIFICATION_PATH

Windows (PowerShell)