Create an organization policy in dry-run mode

This page shows how to use a an organization policy in dry-run mode to monitor how a policy change would impact your workflows before it is enforced.

An organization policy in dry-run mode is created and enforced similarly to other organization policies, and violations of the policy are audit logged, but the violating actions aren't denied.

Before you begin

To use an organization policy in dry-run mode, you must have billing enabled for your Google Cloud project. For information about checking if billing is enabled for a project, see Verify the billing status of your projects.

For more information about what organization policies and constraints are and how they work, see Introduction to the Organization Policy Service.

Required roles

To get the permissions that you need to manage organization policies, ask your administrator to grant you the Organization policy administrator (roles/orgpolicy.policyAdmin) IAM role on the organization. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to manage organization policies. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage organization policies:

orgpolicy.constraints.list
orgpolicy.policies.create
orgpolicy.policies.delete
orgpolicy.policies.list
orgpolicy.policies.update
orgpolicy.policy.get
orgpolicy.policy.set

You might also be able to get these permissions with custom roles or other predefined roles.

Limitations

The only organization policy constraints available to be used in dry-run organization policies are:

Attempting to create an organization policy in dry-run mode using any other constraint results in an error.

Create an organization policy in dry-run mode

List constraints

You can create an organization policy in dry-run mode for a list constraint using the Google Cloud console or Google Cloud CLI. The following examples demonstrate how to create an organization policy in dry-run mode that audits the effect of the gcp.restrictServiceUsage list constraint.

Console

In the Google Cloud console, go to the Organization policies page.

Go to Organization policies
From the project picker, select the resource for which you want to set the organization policy.
Select the Restrict Resource Service Usage constraint from the list on the Organization policies page.
Select the Dry run tab.
Click Manage dry run policy.
On the Edit dry run policy page, select Override parent's policy.
Under Policy enforcement, click Replace.
Click Add rule.
From Policy values, select Custom.
From Policy type, select Deny.
In the Custom values box, enter compute.googleapis.com, and then click Done.
If this is a custom constraint, you can click Test changes to simulate the effect of this organization policy. For more information, see Test organization policy changes with Policy Simulator.
To enforce the organization policy in dry-run mode, click Set dry run policy. You can also set the live policy by clicking Set policy.

You can verify the status of your organization policy in dry-run mode by going to the Dry run tab of an organization policy constraint.

For projects that have an organization policy in dry-run mode applied to them, you can see the audit logs by clicking View rejection logs. For this organization policy, the audit logs display violations as if the Restrict Resource Service Usage constraint is enforced to deny compute.googleapis.com.

gcloud

To create an organization policy in dry-run mode, create a YAML file that defines the constraint with dryRunSpec. For example:

  name: RESOURCE_TYPE/RESOURCE_ID/policies/gcp.restrictServiceUsage
  dryRunSpec:
    rules:
    - values:
        deniedValues:
        - compute.googleapis.com

Replace the following:

RESOURCE_TYPE with organizations, folders, or projects.
RESOURCE_ID with your organization ID, folder ID, project ID, or project number, depending on the type of resource specified in RESOURCE_TYPE.

This organization policy won't enforce the gcp.restrictServiceUsage constraint, but the audit logs display violations as if it did.

You can set a live organization policy and a dry-run organization policy in the same YAML file, if you define both spec and dryRunSpec. For example:

name: RESOURCE_TYPE/RESOURCE_ID/policies/gcp.restrictServiceUsage
spec:
  rules:
  - values:
      allowedValues:
      - container.googleapis.com

dryRunSpec:
  rules:
  - values:
      allowedValues:
      - compute.googleapis.com
      - appengine.googleapis.com

To enforce an organization policy in dry-run mode, use the org-policies set policy command. To update an existing organization policy in dry-run mode with new constraints, use the --update-mask flag. For example:

gcloud org-policies set-policy POLICY_PATH \
  --update-mask=UPDATE_MASK

Replace the following:

POLICY_PATH with the full path to your organization policy YAML file.
UPDATE_MASK with spec to only update the live policy, or dryRunSpec to only update the organization policy in dry-run mode. You can also use * to update both the spec and dryRunSpec fields. If this field is not set when updating an existing organization policy, this command will result in an error and the organization policy won't update.

You can verify that the organization policy in dry-run mode is set by using the org-policies describe command. The dryRunSpec field appears only if it exists in the organization policy.

This organization policy would enforce the gcp.restrictServiceUsage constraint such that only container.googleapis.com is allowed. However, the audit logs display violations of compute.googleapis.com and appengine.googleapis.com as well.

Boolean constraints

You can create an organization policy in dry-run mode for a boolean constraint using the Google Cloud console or Google Cloud CLI. The following examples demonstrate how to create an organization policy in dry-run mode that audits the effect of a boolean custom organization policy.

Console

In the Google Cloud console, go to the Organization policies page.

Go to Organization policies
From the project picker, select the resource for which you want to set the organization policy.
Select the custom organization policy you want to enforce from the list on the Organization policies page.
Select the Dry run tab.
Click Manage dry run policy.
On the Edit dry run policy page, select Override parent's policy.
Click Add rule.
Under Enforcement, select On, and then click Done.
To enforce the organization policy in dry-run mode, click Set dry run policy. Once you verify that the organization policy in dry-run mode works as intended, you can set the live policy by clicking Set policy.

You can verify the status of your organization policy in dry-run mode by going to the Dry run tab of an organization policy constraint.

gcloud

To create an organization policy in dry-run mode, create a YAML file that defines the constraint with dryRunSpec. For example:

  name: RESOURCE_TYPE/RESOURCE_ID/policies/CONSTRAINT_NAME
  dryRunSpec:
    rules:
    - enforce: true

Replace the following:

RESOURCE_TYPE with organizations, folders, or projects.
RESOURCE_ID with your organization ID, folder ID, project ID, or project number, depending on the type of resource specified in RESOURCE_TYPE.
CONSTRAINT_NAME with the name of your custom constraint. For example, custom.disableGkeAutoUpgrade.

This organization policy won't enforce the custom constraint, but the audit logs display violations as if it did.

You can set a live organization policy and an organization policy in dry-run mode in the same same YAML file, if you define both spec and dryRunSpec. For example:

name: RESOURCE_TYPE/RESOURCE_ID/policies/CONSTRAINT_NAME
spec:
  rules:
  - enforce: false

dryRunSpec:
  rules:
  - enforce: true

gcloud org-policies set-policy POLICY_PATH \
  --update-mask=UPDATE_MASK

Replace the following:

POLICY_PATH with the full path to your organization policy YAML file.
UPDATE_MASK with spec to only update the live policy, or dryRunSpec to only update the organization policy in dry-run mode. You can also use * to update both the spec and dryRunSpec fields. If this field is not set when updating an existing organization policy, this command will result in an error and the organization policy won't update.

You can verify that an organization policy in dry-run mode is set by using the org-policies describe command. The dryRunSpec field appears only if it exists in the organization policy.

This organization policy doesn't enforce the custom constraint. However, the audit logs display violations of the custom constraint.

Create an organization policy in dry-run mode from a live policy

You can use an existing organization policy as the starting point for an organization policy in dry-run mode. You may want to do this to see what impacts a change to your existing policy would have on your environment.

You can create an organization policy in dry-run mode based on an existing policy using the Google Cloud console or Google Cloud CLI.

Console

In the Google Cloud console, go to the Organization policies page.

Go to Organization policies
From the project picker, select a resource that already has the Restrict Resource Service Usage constraint configured on it.
Select the Restrict Resource Service Usage constraint from the list on the Organization policies page.
Select the Live tab.
Click Manage policy.
Click Add rule.
From Policy values, select Custom.
From Policy type, select Deny.
In the Custom values box, enter appengine.googleapis.com.
Click Done, and then Set dry run policy.

gcloud

To create an organization policy in dry-run mode based on an existing live organization policy, get the current policy on the resource using the org-policies describe command. For example:

gcloud org-policies describe gcp.restrictServiceUsage \
  --project=PROJECT_ID

Replace PROJECT_ID with the project ID or project number of the project where this organization policy is configured.

The output should look similar to the following:

  name: projects/123456789012/policies/gcp.restrictServiceUsage
  spec:
    etag: CJy93KEGEKCJw/QB
    rules:
    - values:
        allowedValues:
        - compute.googleapis.com
  updateTime: '2023-04-12T21:11:56.512804Z'

Copy the output of this command into a temporary file. Edit this file to remove the etag and updateTime fields, and change the spec field to dryRunSpec. Make any changes to the constraint configuration that you want to test in your organization policy in dry-run mode.

The finished YAML file should look similar to the following:

  name: projects/123456789012/policies/gcp.restrictServiceUsage
  dryRunSpec:
    rules:
    - values:
        allowedValues:
        - compute.googleapis.com
        - appengine.googleapis.com

To enforce the organization policy in dry-run mode, use the org-policies set policy with the --update-mask flag. For example:

gcloud org-policies set-policy POLICY_PATH \
  --update-mask=dryRunSpec

Replace POLICY_PATH with the full path to your temporary organization policy YAML file.

Delete an organization policy in dry-run mode

You can delete an organization policy in dry-run mode using the Google Cloud console or Google Cloud CLI.

Console

In the Google Cloud console, go to the Organization policies page.

Go to Organization policies
From the project picker, select the resource for which you want to set the organization policy.
Select the Restrict Resource Service Usage constraint from the list on the Organization policies page.
Select the Dry run tab.
Click Delete dry run policy.

gcloud

To delete an organization policy in dry-run mode, create a YAML file that defines the organization policy without a dry-run specification. For example:

  name: RESOURCE_TYPE/RESOURCE_ID/policies/gcp.restrictServiceUsage
  spec:
    rules:
    - values:
        allowedValues:
        - container.googleapis.com

Replace the following:

RESOURCE_TYPE with organizations, folders or projects.
RESOURCE_ID with your organization ID, folder ID, project ID, or project number, depending on the type of resource specified in RESOURCE_TYPE.

Then, use the org-policies set policy command with the --update-mask flag set to dryRunSpec. For example:

gcloud org-policies set-policy POLICY_PATH \
  --update-mask=dryRunSpec

This updates the existing organization policy to remove the dry-run specification and ignores the live part of the specification.

To delete both live organization policies and organization policies in dry-run mode at the same time, use the org-policies delete command. For example:

gcloud org-policies delete CONSTRAINT_NAME \
  --RESOURCE_TYPE=RESOURCE_ID

Replace the following:

CONSTRAINT_NAME with the name of the constraint you want to delete. For example, gcp.restrictServiceUsage.
RESOURCE_TYPE with organizations, folders or projects.
RESOURCE_ID with your organization ID, folder ID, project ID, or project number, depending on the type of resource specified in RESOURCE_TYPE.

Effective evaluation of organization policies in dry-run mode

Organization policies in dry-run mode are inherited similarly to other organization policies. If an organization policy in dry-run mode is set on an organization resource, it is inherited by all descendant resources, unless it is overridden at a lower level in the hierarchy.

Effective policy evaluation shows the result of the organization policies that are merged on that resource. Therefore, adjustments to the live organization policy are reflected in the effective organization policy in dry-run mode, if the dry-run mode policy is inherited rather than set locally.

Modifying a project's live organization policy also modifies its effective organization policy in dry-run mode.

For example, consider an organization resource, Organization A, with a live organization policy set to enforced: false, and an organization policy in dry-run mode set to enforced: true. A child resource, Folder B, also sets the live organization policy to enforced: false, and inherits the organization policy in dry-run mode. On Folder B, the set live policy means the effective policy evaluation of the organization policy in dry-run mode is also enforce: false, overriding the organization policy in dry-run mode set in its parent organization.

A child resource of Folder B, Project X, sets the live policy to enforced: true. Similar to the behavior on Folder B, the effective evaluation of the organization policy in dry-run mode for Project X is enforced: true, because the live policy is set.

Another child resource of Folder B, Project Y, sets the organization policy in dry-run mode to enforced: true. It inherits the organization policy from its parent resource, and so the effective evaluation is enforced: false for the live policy, and enforced: true for the organization policy in dry-run mode.

Resource	Set live organization policy	Effective live organization policy	Set organization policy in dry-run mode	Effective organization policy in dry-run mode
Organization A	`enforced: false`	`enforced: false`	`enforced: true`	`enforced: true`
Folder B	`enforced: false`	`enforced: false`	None	`enforced: false`
Folder C	None	`enforced: false`	None	`enforced: true`
Project X	`enforced: true`	`enforced: true`	None	`enforced: true`
Project Y	None	`enforced: false`	`enforced: true`	`enforced: true`

Analyze the effects of an organization policy in dry-run mode

An organization policy in dry-run mode does not block any operations when enforced. To see the effect your organization policy would have, you can check the organization policy audit logs.

Organization policy audit logs for live organization policies and organization policies in dry-run mode are generated based on whether the operation is allowed or denied by the policies enforced on given resource. The following table describes the situations in which an organization policy audit log is generated:

Live organization policy	Organization policy in dry-run mode	Audit log generated
Allow	Allow	No
Allow	Deny	Audit log in dry-run mode only
Deny	Allow	Audit log in live and dry-run mode
Deny	Deny	Audit log in live and dry-run mode

Organization policy in dry-run mode violations appear alongside violations in live mode in the audit logs. For example:

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "status": {
      "code": 7,
      "message": "PERMISSION_DENIED"
    },
    "authenticationInfo": {},
    "requestMetadata": {
      "callerIp": "1.2.3.4",
      "requestAttributes": {},
      "destinationAttributes": {}
    },
    "serviceName": "appengine.googleapis.com",
    "methodName": "google.api.appengine.v1.appengine.apps.services.get",
    "resourceName": "projects/sur-project-test-3",
    "metadata": {
      "constraint": "constraints/gcp.restrictServiceUsage",
      "checkedValue": "appengine.googleapis.com",
      "liveResult": "ALLOWED",
      "@type": "type.googleapis.com/google.cloud.audit.OrgPolicyDryRunAuditMetadata",
      "dryRunResult": "DENIED"
    }
  },
  "insertId": "1f2bvoxcmg1",
  "resource": {
    "type": "audited_resource",
    "labels": {
      "project_id": "sur-project-test-3",
      "service": "appengine.googleapis.com",
      "method": "google.api.appengine.v1.appengine.apps.services.get"
    }
  },
  "timestamp": "2022-06-16T19:42:58.244990928Z",
  "severity": "WARNING",
  "logName": "projects/sur-project-test-3/logs/cloudaudit.googleapis.com%2Fpolicy",
  "receiveTimestamp": "2022-06-16T19:42:59.572025716Z"
}

You can use the Logs Explorer to query only organization policy in dry-run mode violations.

Console

In the Google Cloud console, you can use the Logs Explorer to retrieve your audit log entries for your Google Cloud project, folder, or organization:

In the Google Cloud console, go to the Logging> Logs Explorer page.

Go to Logs Explorer
Select an existing Google Cloud project, folder, or organization.
In the Query builder pane, do the following:
- In Resource type, select the Google Cloud resource whose audit logs you want to see.
- In Log name, select the policy audit log type.
- In the Query pane, enter the following: protoPayload.metadata.dryRunResult = "DENIED" AND \ protoPayload.metadata.liveResult = "ALLOWED"
If you're experiencing issues when trying to view logs in the Logs Explorer, see the troubleshooting information.

For more information about querying by using the Logs Explorer, see Build queries in the Logs Explorer.

gcloud

The Google Cloud CLI provides a command-line interface to the Logging API. Supply a valid resource identifier in each of the log names. For example, if your query includes a project ID, then the project identifier you supply must refer to the currently selected project name.

To read audit log entries for organization policy in dry-run mode violations, run the following command:

gcloud logging read protoPayload.metadata.dryRunResult = "DENIED" AND \
      protoPayload.metadata.liveResult = "ALLOWED" \
    --RESOURCE_TYPE=RESOURCE_ID \

Replace the following:

RESOURCE_TYPE with organization, folder or project.
RESOURCE_ID with your organization ID, folder ID, project ID, or project number, depending on the type of resource specified in RESOURCE_TYPE.

Add the--freshness flag to your command to read logs that are more than 1 day old.

For more information about using the gcloud CLI, see gcloud logging read.

If you have many projects under your organization, you can use aggregated sinks to aggregate and route the audit log entries from all projects under your organization to a BigQuery table. For more information about creating aggregated sinks, see Collate and route organization-level logs to supported destinations.

What's next

For more information about how to create and manage organization policy constraints, see Using constraints.