This document describes how to use deploy policies to restrict manual orautomated delivery-pipeline actions.

A deploy policy is a Cloud Deploy resource that you can use to restrictmanual or automatic actions against a selected delivery pipeline or target (orall pipelines or targets).

What behavior can be restricted?

You can create deploy policies to restrict or prevent Cloud Deployfrom performing certain actions on rollouts. For example, a policy can preventrollout creation for a given delivery pipeline during a specified time period.You might use this for seasonal restrictions, for example.

How are policies evaluated and enforced

For any manual or automated action, Cloud Deploy does the following:

1. Checks Identity and Access Management permissions.

   If the user or service account doesn't have adequate IAMpermissions, the action isn't taken and there is no need to evaluate deploypolicies.

2. Checks whether there's an applicable policy for the target or deliverypipeline, and if there is, the policy is evaluated.

   • Cloud Deploy evaluates the action being taken to see if thisrule is applicable.

     That is, does the action type and invoker match the policy?

   • Cloud Deploy checks date and time ranges defined for thepolicy to see if that policy is in effect at the time of the request.

   • If the policy is in effect and the rule does apply to the delivery pipelineor target and the action, that rule is enforced and the action is blocked.

Requirements and Limitations

• Each policy must have at least one selector.

• Each policy must have at least one rule.

  All rule IDs must be unique within a deploy policy.

• Each rule must have at least onetimeWindows, and within thattimeWindows,there must be either aoneTimeWindows or aweeklyWindows.

  SeeDates and times for more details on using time blocks.

• You can have no more than 1000 deploy policies per project/location.

Identity and Access Management roles and permissions required

In addition to the permissions you need to run any Cloud Deploy deliverypipeline, and to perform the tasks to that would be restricted by policy, thereare several permissions that are needed in order to perform certain operationson the policy resource:

• clouddeploy.deployPolicies.create
• clouddeploy.deployPolicies.delete
• clouddeploy.deployPolicies.get
• clouddeploy.deployPolicies.list
• clouddeploy.deployPolicies.update
• clouddeploy.deployPolicies.override

Those permissions are included in theroles/clouddeploy.policyAdmin role.Additionally, theroles/clouddeploy.policyOverrider role includes the.override permission.

Create a deploy policy

Creating a deploy-policy resource consists of the following steps:

1. Create a YAML file with the deploy policyconfiguration.

   The configuration includes a header, which identifies the resource as adeploy policy. Thename is required.

   apiVersion:deploy.cloud.google.com/v1kind:DeployPolicymetadata:name:description:

2. Add a reference to the delivery pipelines and targets to which the policyapplies (theselectors).

   SeeDeploy policy selectors and theConfiguration schema referencefor more information on policy selectors and how to configure them..

3. Add one or more policyrules.

   Each rule describes a restriction and the circumstances under which thatrestriction is enforced. SeeDeploy policy rules and theConfiguration schema referencefor more information on policy rules and how to configure them.

4. Apply that file to create the policy:

   gclouddeployapply--file=FILENAME\--region=REGION\--project=PROJECT_ID

   WhereFILENAME is the name of the YAML file containing yourDeployPolicy definition,REGION is the region in which you wantto create the deploy policy resource, andPROJECT_ID is project in whichyou want to create the resource.

The referenced delivery pipelines or targets are now restricted according tothe rules in the deploy-policy resource.

Deploy policy selectors

Selectors, defined in deploy policyconfigurations, determinewhat delivery pipelines and targets are affected by a given rule.

A selector is defined in aselectors stanza in the deploy policyconfiguration, as a top-level property:

selectors:-deliveryPipeline:id:labels:target:id:labels:

In this configuration YAML,deliveryPipeline.id takes the name of thedelivery pipeline, andtarget.id takes the name of the target (in both cases,metadata.name).

You can useid: * to select all delivery pipelines or all targets. Note that* is a special field value to select all—arbitrary wildcarding isn'tsupported. You can also use labels to match delivery pipelines or targets orboth.

Within a given selector, items are ANDed together. Multiple selectors are ORed.That is, for a given request to be restricted by the policy, it must apply toat least one selector. But within that selector, the request must match allitems.

Deploy policy rules

Each deploy policy includes one or more policy rules, which define what actionis restricted in the selected delivery pipeline or target. The rule also definesunder what circumstances the rule is applied.

The following rules are available:

• rolloutRestriction

TherolloutRestriction rule prevents the specified rollout actions from beingperformed on selected targets used by selected delivery pipelines. This ruleuses a time window that defineswhen a rollout can't be created for theselected delivery pipeline and target. SeeDates and times for adescription of how dates and times are specified in deploy policy rules.

The following actions can be restricted while the rule is in effect:

• ADVANCE

  Rollout phases can't beadvanced.

• APPROVE

  Rolloutpromotion can't be approved.

• CANCEL

  Rollouts can't becanceled.

• CREATE

  Rollouts can't be created. You cancreate a release if a policy is preventing this action, but that release won't spawn a rollout.

• IGNORE_JOB

  Jobs can't beignored.

• RETRY_JOB

  Jobs can't beretried.

• ROLLBACK

  Rollouts can't berolled back.

• TERMINATE_JOBRUN

  Job runs can't beterminated

  See theConfiguration schema referencefor the YAML structure for this rule.

Dates and times in arolloutRestriction rule

Youconfigure date andtime blocks to specify repeating and non-repeating time windows during which thedeploy policy is in effect.

The following are the requirements for expressing dates and time:

• Dates are expressed asyyyy-mm-dd.

• When expressing time of day, the start of the day is00:00, and the end of theday is24:00.

• ForoneTimeWindows, dates must include the time. ForweeklyWindows, youcan omit the time of day. But if you includestartTime you must includeendTime, and the other way around.

  For example, a freeze on Sundays only would be as follows:

  -daysOfWeek:[SUNDAY]startTime:"00:00"endTime:"24:00"

  You could also do this:

  -daysOfWeek:[SUNDAY]

  But not this:

  -daysOfWeek:[SUNDAY]startTime:"00:00"

• You must include a time zone, in thetimeWindows stanza.

  For example:timeZone: America/New_York.

Non-repeating time windows

A non-repeating time window starts and ends on an specific day and time. Youwould use this for any block of time for which you want to restrict rollouts.

Non-repeating time windows are configured using aoneTimeWindows stanza.

Repeating time windows

A repeating time window describes a repeating block of time during which youwant to restrict rollouts. For example, you could use this to restrict rolloutson weekends.

Repeating time windows are configured using aweeklyWindows stanza.

Examples

This section contains some examples of using dates and times to configure when adeploy policy is enforced.

Annual freeze

If there's a time of year during which you want to freeze rollouts, you canconfigure aoneTimeWindows block to do so. If the dates are predictable, fromyear to year, you still need to use multipleoneTimeWindow blocks.

The following YAML shows a one-time (non-repeating) time window to enforce adeploy policy for an annual freeze:

timeWindows:timeZone:"America/New_York"oneTimeWindows:-start:"2024-12-2217:00"end:"2025-01-0209:00"

This YAML describes a time window from December 22, 2024 at 5pm, through January2, 2025, at 9am.

Repeating weekend freeze

The following YAML shows a repeating time window to enforce a deploy policy thatrestricts rollouts on weekends, from Friday at 5pm through Monday morning at9am:

timeWindows:timeZone:"America/New_York"weeklyWindows:-daysOfWeek:[FRIDAY]startTime:"17:00"endTime:"24:00"-daysOfWeek:[SATURDAY,SUNDAY]startTime:"00:00"endTime:"24:00"-daysOfWeek:[MONDAY]startTime:"00:00"endTime:"09:00"

Update a deploy policy

Updating a deploy policy consists of the following steps:

1. Edit the policy configuration YAML.

   If you created the policy using the Google Cloud console, you can getthe YAML configuration by selecting theYAML tab on theDeploy policydetails page. Then you can copy that text into a file locally and edit itthere.

2. Apply that file to update the policy:

   gclouddeployapply--file=FILENAME\--region=REGION\--project=PROJECT_ID

   This updates the deploy policy resource with the new configuration.

Because deploy policies are evaluated when the restricted action is attempted,all such actions against all Cloud Deploy resources are subject tothe updated policy. That is, there is no remnant of the previous restrictions.For example, if you have arestrictRollouts block for the entire month ofDecember, and on December 14, you update the policy so that the restriction endson December 15, rollouts are no longer blocked after December 15.

Override a deploy policy

You can override a deploy policy, if necessary. For example, if there's aproblem with a deployment in production and you need to roll it back, butthere's a deploy policy preventing any rollouts, you can override that policy inorder to roll back the bad rollout.

In order to override a deploy policy, you must have theclouddeploy.deployPolicies.override IAM permission.

You can override the policy either from the gcloud CLI or using theGoogle Cloud console:

gclouddeployreleasespromote--release=my-release-001\--project=my-policy-testing-project\--region=us-central1\--delivery-pipeline=my-pipeline\--to-target=prod-target\--override-deploy-policies=my-deploy-policy

Delete a deploy policy

To delete a deploy policy:

gclouddeploydeploy-policiesdelete\--project=[PROJECT]\--region=[REGION]\[POLICY_NAME]

After you delete the deploy policy resource, the affected delivery pipelines andtargets are no longer subject to the policy, and won't be restricted unlessaffected by another deploy policy.

Logging of deploy policy

When a deploy policy is evaluated,platform logentries are created for the following actions:

• Policy evaluation

  Platform logs are written when a request is evaluated and violates the policy.A log is written also when the policy is violated by a request but the requestis allowed because the policy is suspended or was overridden. No log iswritten when the request is granted because the policy is not violated.

• Pub/Sub notification failure upon change of a deploy policyresource.

What's next

• See theConfiguration file schemafor details on configuring deploy policies.

• Learn aboutCloud Deploy deploy automation.