Manage custom constraints for projects

This page details how to create custom constraints for Cloud Runservices and jobs and enforce them at the project level. For information aboutcustom organization policies, seeCreating and managing custom organization policies.

If you've created or deployed Cloud Run functions usinggcloud functions commands or theCloud Functions v2 APIs, seeManage function resources using custom constraints.

Google Cloud Organization Policy gives you centralized, programmaticcontrol over your organization's resources. As theorganization policy administrator, you can define an organization policy,which is a set of restrictions calledconstraints that apply toGoogle Cloud resources and descendants of those resources in theGoogle Cloud resource hierarchy. You can enforce organization policies atthe organization, folder, or project level.

Organization Policy providespredefined constraints for variousGoogle Cloud services. However, if you want more granular, customizablecontrol over the specific fields that are restricted in your organizationpolicies, you can also create custom organization policies.

Benefits

  • Cost management: use organization policies to restrict the VMinstance and disk sizes and types that can be used in your organization.You can also restrict the machine family that is used for the VM instance.
  • Security, compliance, and governance:
    • To enforce security requirements, you can require specificfirewall port rules on VMs.
    • To support hardware isolation or licensing compliance, you canrequire all VMs within a specific project or folder to run onsole-tenant nodes.
    • To govern automation scripts, you can use custom organizationpolicies to verify that labels match the necessary expressions.

Cloud Run lets you write any number of custom constraints usingmost user-configured fields in the Cloud Run Admin API. For example, you cancreate a custom constraint specifying that a service be set to internal orthat prevents non-GA launch stages.

Once applied, requests that violate a policy that enforces a custom constraintshow an error message in the gcloud CLI and inCloud Run logs. The error message contains the constraint IDand description of the violated custom constraint.

Tip: Use thepolicy simulatorto check whether existing services or jobs in your organization are in violationof a new custom organization policy.

Policy inheritance

By default, organization policies are inherited by the descendants of theresources that you enforce the policy on. For example, if you enforce a policyon a folder, Google Cloud enforces the policy on all projects in thefolder. To learn more about this behavior and how to change it, refer toHierarchy evaluation rules.

Pricing

The Organization Policy Service, including predefined and custom organization policies, isoffered at no charge.

Limitations

Before you begin

Required roles

To get the permissions that you need to manage organization policies, ask your administrator to grant you theOrganization policy administrator (roles/orgpolicy.policyAdmin) IAM role on the organization resource. For more information about granting roles, seeManage 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 theRequired 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 withcustom roles or otherpredefined roles.

Create a custom constraint

A custom constraint is defined in a YAML file by the resources, methods,conditions, and actions that are supported by the service that you areenforcing the organization policy on. Conditions for your custom constraints aredefined usingCommon Expression Language (CEL). For more information about how to buildconditions in custom constraints using CEL, see the CEL section ofCreating and managing custom constraints.

To create a YAML file for a Cloud Run custom constraint, refer tothe following example:

name:organizations/ORGANIZATION_ID/customConstraints/CONSTRAINT_NAMEresourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"CONDITION"actionType:ACTIONdisplayName:DISPLAY_NAMEdescription:DESCRIPTION

Replace the following:

  • ORGANIZATION_ID: your organization ID, such as123456789.

  • CONSTRAINT_NAME: the name you want for your newcustom constraint. A custom constraint must start withcustom., and canonly include uppercase letters, lowercase letters, or numbers, forexample, custom.ingressInternal. The maximum length of this field is 70characters, not counting the prefix, for example,organizations/123456789/customConstraints/custom.

  • CONDITION: aCEL condition that is written againsta representation of a supported service resource. Thisfield has a maximum length of 1000 characters. For example,condition: "'run.googleapis.com/ingress' in resource.metadata.annotations && resource.metadata.annotations['run.googleapis.com/ingress'] == 'internal'".

  • ACTION: the action to take if thecondition ismet. This can be eitherALLOW orDENY.

  • DISPLAY_NAME: a human-friendly name for theconstraint. This field has a maximum length of 200 characters.

  • DESCRIPTION: a human-friendly description of theconstraint to display as an error message when the policy is violated, forexample, "Require ingress to be set to internal." This field has a maximumlength of 2000 characters.

For more information about how to create a custom constraint, seeDefining custom constraints.

Set up a custom constraint

After you have created the YAML file for a new custom constraint, you must set it up to makeit available for organization policies in your organization. To set up a custom constraint, usethegcloud org-policies set-custom-constraint command:
gcloudorg-policiesset-custom-constraintCONSTRAINT_PATH
ReplaceCONSTRAINT_PATH with the full path to yourcustom constraint file. For example,/home/user/customconstraint.yaml.Once completed, your custom constraints are available as organization policiesin your list of Google Cloud organization policies.To verify that the custom constraint exists, use thegcloud org-policies list-custom-constraints command:
gcloudorg-policieslist-custom-constraints--organization=ORGANIZATION_ID
ReplaceORGANIZATION_ID with the ID of your organization resource.For more information, seeViewing organization policies.

Enforce a custom constraint

You can enforce a constraint by creating an organization policy that references it, and thenapplying that organization policy to a Google Cloud resource.

Console

  1. In the Google Cloud console, go to theOrganization policies page.

    Go to Organization policies

  2. From the project picker, select the project for which you want to set the organization policy.
  3. From the list on theOrganization policies page, select your constraint to view thePolicy details page for that constraint.
  4. To configure the organization policy for this resource, clickManage policy.
  5. On theEdit policy page, selectOverride parent's policy.
  6. ClickAdd a rule.
  7. In theEnforcement section, select whether enforcement of this organization policy is on or off.
  8. Optional: To make the organization policy conditional on a tag, clickAdd condition. Note that if you add a conditional rule to an organization policy, you must add at least one unconditional rule or the policy cannot be saved. For more information, seeSetting an organization policy with tags.
  9. ClickTest changes to simulate the effect of the organization policy. Policy simulation isn't available for legacy managed constraints. For more information, see Test organization policy changes with Policy Simulator.
  10. To finish and apply the organization policy, clickSet policy. The policy requires up to 15 minutes to take effect.

gcloud

To create an organization policy with boolean rules, create a policy YAML file that references the constraint:

name:projects/PROJECT_ID/policies/CONSTRAINT_NAMEspec:rules:-enforce:true

Replace the following:

  • PROJECT_ID: the project on which you want to enforce your constraint.
  • CONSTRAINT_NAME: the name you defined for your custom constraint. For example,custom.ingressInternal.

To enforce the organization policy containing the constraint, run the following command:

gcloudorg-policiesset-policyPOLICY_PATH

ReplacePOLICY_PATH with the full path to your organization policy YAML file. The policy requires up to 15 minutes to take effect.

Test the custom constraint

To test the example that restricts ingress settings, try to deploy aCloud Run service in the project with ingress set toall:

gcloudrundeployorg-policy-test\--project=PROJECT_ID\--region=REGION_ID\--ingress=all

The output is the following:

Operation denied by custom org policies: ["customConstraints/custom.ingressConstraint": "Require ingress to be set to internal."]

Example custom organization policies for common use cases

The following table provides examples of custom constraints that you might finduseful with Cloud Run services and jobs:

DescriptionConstraint syntax
Require that a Cloud Run service be set to internal.
name:organizations/ORGANIZATION_ID/customConstraints/custom.ingressInternalresourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"'run.googleapis.com/ingress'inresource.metadata.annotations&&resource.metadata.annotations['run.googleapis.com/ingress']=='internal'"actionType:ALLOWdisplayName:IngressInternaldescription:Require ingress to be set to internal.
DescriptionConstraint syntax
Require a custom memory limit for all containers of a Cloud Run service.
name:organizations/ORGANIZATION_ID/customConstraints/custom.memoryLimitresourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"resource.spec.template.spec.containers.all(container,'memory'incontainer.resources.limits&&container.resources.limits['memory']<='MEMORY_LIMIT')"actionType:ALLOWdisplayName:memoryLimitCapdescription:Require the container memory limit to be set to<=MEMORY_LIMIT.
DescriptionConstraint syntax
Prevent the Cloud Runlaunch stage from being changed from default GA to a non-GA launch stage.
name:organizations/ORGANIZATION_ID/customConstraints/custom.launchStageresourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"!('run.googleapis.com/launch-stage'inresource.metadata.annotations)||resource.metadata.annotations['run.googleapis.com/launch-stage']=='GA'"actionType:ALLOWdisplayName:launchStagedescription:Only allow users to create and update Cloud Run services with either an unset launch stage (default is GA) or a launch stage explicitly set to GA.
DescriptionConstraint syntax
RequireBinary Authorization to be set to default.
name:organizations/ORGANIZATION_ID/customConstraints/custom.binaryAuthorizationresourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"'run.googleapis.com/binary-authorization'inresource.metadata.annotations&&resource.metadata.annotations['run.googleapis.com/binary-authorization']=='default'"actionType:ALLOWdisplayName:binaryAuthorizationdescription:Require binaryAuthorization to be set to default.
DescriptionConstraint syntax
Require that services have aliveness probe for every container.
name:organizations/ORGANIZATION_ID/customConstraints/custom.livenessProberesourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"resource.spec.template.spec.containers.all(container,has(container.livenessProbe.initialDelaySeconds))"actionType:ALLOWdisplayName:livenessProbedescription:Require all containers to have a liveness probe configured with initialDelaySeconds.
DescriptionConstraint syntax
Require that a service has at least onesidecar container that uses an image beginning with a specified prefix and a port equal to a specified number.
name:organizations/ORGANIZATION_ID/customConstraints/custom.requireSidecarresourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"resource.spec.template.spec.containers.exists(container,container.image.startsWith('us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/')&&container.ports.exists(port,port.containerPort==8081))"actionType:ALLOWdisplayName:requireSidecardescription:Require at least one container with an image that starts with "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/" and uses port 8081.
DescriptionConstraint syntax
Only allows the creation and editing of functions.
name:organizations/ORGANIZATION_ID/customConstraints/custom.allowcrfresource_types:run.googleapis.com/Servicemethod_types:-CREATE-UPDATEcondition:"resource.spec.template.spec.containers.exists(container,container.image.startsWith('gcr.io/cloudrun/placeholder'))||(has(resource.metadata.annotations)&&'run.googleapis.com/build-function-target'inresource.metadata.annotations)"action_type:ALLOWdisplay_name:runFunctionsOnlydescription:Only allow the creation and editing of Cloud Run functions
DescriptionConstraint syntax
Require that thedefaultrun.app URL be disabled for Cloud Run services.
name:organizations/ORGANIZATION_ID/customConstraints/custom.disableRunAppresourceTypes:-run.googleapis.com/ServicemethodTypes:-CREATE-UPDATEcondition:"'run.googleapis.com/default-url-disabled'inresource.metadata.annotations&&resource.metadata.annotations['run.googleapis.com/default-url-disabled']=='true'"actionType:ALLOWdisplayName:disableRunAppdescription:Require services to disablerun.app URL.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-24 UTC.