This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Before you begin

• Create a policy library.

Constraint Framework

gcloud beta terraform vet usesConstraint Frameworkpolicies, which consist ofconstraints andconstraint templates. Thedifference between the two is as follows:

• A constraint template is like a function declaration; it defines a rule inRego and optionally takes input parameters.
• A constraint is a file that references a constraint template and defines theinput parameters to pass to it and the resources covered by the policy.

This allows you to avoid repetition. You can write a constraint template with ageneric policy, then write any number of constraints that provide differentinput parameters or different resource matching rules.

CAI Assets vs Terraform resources

Cloud Asset Inventory Assets are a standard Google data export format that isavailablefor many Google Cloud resources.CAI data is only usually available after a resource has been created or updated.However, by converting Terraform resource changes to CAI Asset data,gcloud beta terraform vet allows you to write a policy one time and use it bothbefore apply and as an audit check with compatible tools.

Compatible tools

The following tools are not official Google products and are not supported.However, they might be compatible with policies written forgcloud beta terraform vet:

• CFT Scorecard
• Forseti

Create a constraint template

Before you develop your constraint template, verify that the Asset you want towrite a policy for is supported by bothCloud Asset Inventoryand bygcloud beta terraform vet.

Creating a constraint template takes the following steps:

1. Collect sample data.
2. WriteRego.
3. Test your Rego.
4. Set up a constraint template skeleton.
5. Inline your Rego.
6. Set up a constraint.

Collect sample data

In order to write a constraint template, you need to have sample data to operateon. CAI-based constraints operate onCAI Asset data. Gather sample data bycreating resources of the appropriate type and exporting those resources asJSON, as described in theCAI quickstart.

Here is an example JSON export for a Compute Address:

[{"name":"//compute.googleapis.com/projects/789/regions/us-central1/addresses/my-internal-address","asset_type":"compute.googleapis.com/Address","ancestors:["organization/123","folder/456","project/789"],"resource":{"version":"v1","discovery_document_uri":"https://www.googleapis.com/discovery/v1/apis/compute/v1/rest","discovery_name":"Address","parent":"//cloudresourcemanager.googleapis.com/projects/789","data":{"address":"10.0.42.42","addressType":"INTERNAL","name":"my-internal-address","region":"projects/789/global/regions/us-central1"}}},]

Write Rego

After you have sample data, you can write the logic for your constraint templateinRego.Your Rego must have aviolations rule. The asset being reviewed is availableasinput.review. Constraint parameters are available asinput.parameters.For example, to require thatcompute.googleapis.com/Address assets have anallowedaddressType, write:

# validator/gcp_compute_address_address_type_allowlist_constraint_v1.regopackagetemplates.gcp.GCPComputeAddressAddressTypeAllowlistConstraintV1violation[{"msg":message,"details":metadata,}]{asset:=input.reviewasset.asset_type=="compute.googleapis.com/Address"allowed_address_types:=input.parameters.allowed_address_typescount({asset.resource.data.addressType} &allowed_address_types)>=1message:=sprintf("Compute address %s has a disallowed address_type: %s",[asset.name,asset.resource.data.addressType])metadata:={"asset":asset.name}}

Name your constraint template

The previous example uses the nameGCPComputeAddressAddressTypeAllowlistConstraintV1. This is a unique identifierfor each constraint template. We recommend following these naming guidelines:

• General format:GCP{resource}{feature}Constraint{version}. Use CamelCase.(In other words, capitalize each new word.)
• For single-resource constraints, followgcloud group names for resourcenaming. For example, use "compute" instead of "gce", "sql" instead of"cloud-sql", and "container-cluster" instead of "gke".
• If a template applies to more than one type of resource, omit the resourcepart and only include the feature (example:"GCPAddressTypeAllowlistConstraintV1").
• The version number does not follow semver form; it is just a single number.This effectively makes every version of a template an unique template.

We recommend using a name for your Rego file that matches the constrainttemplate name, but using snake_case. In other words, convert the name tolowercase separate words with_. For the previous example, the recommendedfilename isgcp_compute_address_address_type_allowlist_constraint_v1.rego

Test your Rego

You can test your Rego manually with theRego Playground. Make sure touse non-sensitive data.

We recommend writingautomated tests.Put your collected sample data invalidator/test/fixtures/<constraintfilename>/assets/data.json and reference it in your test file like this:

# validator/gcp_compute_address_address_type_allowlist_constraint_v1_test.regopackagetemplates.gcp.GCPComputeAddressAddressTypeAllowlistConstraintV1importdata.test.fixtures.gcp_compute_address_address_type_allowlist_constraint_v1_test.assetsasassetstest_violation_with_disallowed_address_type{parameters:={"allowed_address_types":"EXTERNAL"}violations:=violationwithinput.reviewasassets[_]withinput.parametersasparameterscount(violations)==1}

Place your Rego and your test in thevalidator folder in your policy library.

Set up a constraint template skeleton

After you have a working and tested Rego rule, you must package it as aconstraint template. Constraint Framework uses Kubernetes Custom ResourceDefinitions as the container for the policy Rego.

The constraint template also defines what parameters are allowed as inputs fromconstraints, using theOpenAPI V3 schema.

Use the same name for the skeleton as you used for your Rego. In particular:

• Use the same filename as for your Rego. Example:gcp_compute_address_address_type_allowlist_constraint_v1.yaml
• spec.crd.spec.names.kind must contain the template name
• metadata.name must contain the template name, but lower-cased

Place the constraint template skeleton inpolicies/templates.

For the example above:

# policies/templates/gcp_compute_address_address_type_allowlist_constraint_v1.yamlapiVersion:templates.gatekeeper.sh/v1beta1kind:ConstraintTemplatemetadata:name:gcpcomputeaddressaddresstypeallowlistconstraintv1spec:crd:spec:names:kind:GCPComputeAddressAddressTypeAllowlistConstraintV1validation:openAPIV3Schema:properties:allowed_address_types:description:"A list of address_types allowed, for example: ['INTERNAL']"type:arrayitems:type:stringtargets:-target:validation.gcp.forsetisecurity.orgrego:|            #INLINE("validator/gcp_compute_address_address_type_allowlist_constraint_v1.rego")            #ENDINLINE

Inline your Rego

At this point, following the previous example, your directory layout looks likethis:

|policy-library/|-validator/||-gcp_compute_address_address_type_allowlist_constraint_v1.rego||-gcp_compute_address_address_type_allowlist_constraint_v1_test.rego|-policies||-templates|||-gcp_compute_address_address_type_allowlist_constraint_v1.yaml

If you cloned theGoogle-provided policy-library repository,you can runmake build to automatically update your constraint templates inpolicies/templates with the Rego defined invalidator.

Set up a constraint

Constraints contain three pieces of information thatgcloud beta terraform vet needsto properly enforce and report violations:

• severity:low,medium, orhigh
• match: parameters for determining if a constraint applies to a particularresource. The following match parameters are supported:
  • ancestries: A list of ancestry paths to include using glob-stylematching
  • excludedAncestries: (Optional) A list of ancestry paths to excludeusing glob-style matching.
• parameters: Values for the constraint template's input parameters.

Make sure thatkind contains the constraint template name. We recommendsettingmetadata.name to a descriptive slug.

For example, to only allowINTERNAL address types using the previous exampleconstraint template, write:

# policies/constraints/gcp_compute_address_internal_only.yamlapiVersion:constraints.gatekeeper.sh/v1beta1kind:GCPComputeAddressAddressTypeAllowlistConstraintV1metadata:name:gcp_compute_address_internal_onlyspec:severity:highmatch:ancestries:-"**"parameters:allowed_address_types:-"INTERNAL"

Matching examples:

If a resource address matches values inancestries andexcludedAncestries,it is excluded.

Limitations

Terraform plan data gives the best available representation of actual stateafter apply. However, in many cases, the state after apply might not be knownbecause it is calculated on the server side. In these cases, the data is notavailable in the converted CAI Assets either.

Building CAI ancestry paths is part of the process when validating policies. Ituses the default project provided to get around unknown project IDs. In thecase where a default project is not provided, the ancestry path defaults toorganizations/unknown.

You can disallow unknown ancestry by adding the following constraint:

apiVersion:constraints.gatekeeper.sh/v1beta1kind:GCPAlwaysViolatesConstraintV1metadata:name:disallow_unknown_ancestryannotations:description:|Unknownancestryisnotallowed;use--project=<project>tosetadefaultancestryspec:severity:highmatch:ancestries:-"organizations/unknown"parameters:{}

Supported resources

If you wantgcloud beta terraform vet to add support for a resource that is not onthis list, open anenhancement request and considercontributing code.

The list of supported resources depends on which version ofgcloud beta terraform vetis installed. The current list of supported resources follows: