Organizing your resources


Config Connector can create and manage Google Cloud resources at the project-level, folder-level, or organization-level scope. Config Connector needs to determine:

  • Whether to create the resource at the project-level, folder-level, or organization-level.
  • Which project, folder, or organization to use.

As a result, Config Connector first checks for a scope-defining field in your resource spec, if not found, then checks for a scope-defining annotation. Most Google Cloud resources can be created at only the project-level.

Once a resource is successfully created, regardless of how the scope is set, the field or annotation becomes immutable. To change the scope of a resource, you must delete the current resource and create a new resource in a different project, folder, or organization scope.

Scope-defining field

A scope-defining resource spec field is part of the resource's spec and can be set only in the resource's configuration. It follows the naming convention of SCOPERef. Depending on the resource type, the schema of the spec may contain at least one of the following fields:

  • projectRef
  • folderRef
  • organizationRef

Scope-defining annotation

You can define a scope-defining annotation in the resource's configuration or in the Kubernetes namespace which contains the resource. There are three types of scope-defining annotations depending on the resource type:


Most Config Connector resources support scope-defining fields. We recommend fields over scope-defining annotations because a scope-defining field makes the resource spec more self-contained and enables the creation of a scope and its contained resources in one step. For resources that do not support scope-defining fields, you can either supply the scope-defining annotation in their configuration, or default the annotation for all resources in a particular namespace by annotating the namespace. The namespace annotation is ignored if the resource has the scope-defining annotation directly in its configuration.


If the scope concept does not apply to a Config Connector resource, you do not need to specify a project, folder, or organization scope. Specifically if a resource listed in the resource reference page does not have a scope-defining field or a scope-defining annotation, you do not need to add a scope.

Some resources, like BillingBudgetsBudget are bound to a Google Cloud billing account, and requires you to specify the billing account information instead.

IAM resources, including IAMPolicy, IAMPartialPolicy, IAMPolicyMember and IAMAuditConfig do not require you to provide a scope. Instead, these resources are attached to another Google Cloud resource through the spec.resourceRef field. This other Google Cloud resource can be a PubSubTopic, a SpannerInstance or even a "scope" like project, folder, organization, which are themselves modeled as a Google Cloud resource.

What's next

See how to apply the following types of scopes: