# Folder-scoped resources

# Folder-scoped resources

Config Connector can manage your resources at the project, folder, or
organization level. In order for Config Connector to determine where to create
your resources, it first checks for a [scope-defining field](https://docs.cloud.google.com/config-connector/docs/how-to/organizing-resources/overview#scope-defining_field)
in your resource spec, if not found, then checks for a [scope-defining annotation](https://docs.cloud.google.com/config-connector/docs/how-to/organizing-resources/overview#scope-defining_annotation).

> [!NOTE]
> **Note:** The scope concept does not apply to all Config Connector resources. See [Exceptions](https://docs.cloud.google.com/config-connector/docs/how-to/organizing-resources/overview#exceptions) for more details. You can check the [resource reference page](https://docs.cloud.google.com/config-connector/docs/reference/resources) to see if a resource supports the `spec.folderRef` field or `cnrm.cloud.google.com/folder-id` annotation.

## Specify `folderRef` field

Most folder-scoped Config Connector resources support a field named `folderRef`
in its CRD spec. Use this field to specify the Google Cloud folder you
want to create the resource in.

If the Google Cloud folder is also being managed in the same cluster via
the [Folder](https://docs.cloud.google.com/config-connector/docs/reference/resource-docs/resourcemanager/folder)
CRD, you can specify the folder as a Kubernetes resource reference:

    ...
    spec:
      folderRef:
        name: FOLDER_RESOURCE_NAME
        namespace: FOLDER_RESOURCE_NAMESPACE
    ...

This approach makes it possible to use Config Connector and create a Google Cloud
folder with its child resources in one single apply operation.
The namespace field is optional if the Config Connector Folder resource is in
the same Kubernetes namespace as your folder-scoped resource.

If the Google Cloud folder is not being managed as a Kubernetes resource
in the same cluster, you can use the `external` field to directly specify the
folder ID. The exact format of the value may be different depending on the
resource type. Two most common formats are "<var translate="no">FOLDER_ID</var>" and
"folders/<var translate="no">FOLDER_ID</var>". See an example of "<var translate="no">FOLDER_ID</var>" below:

    ...
    spec:
      folderRef:
        external: "FOLDER_ID"
    ...

## Annotate resource configuration

If the Config Connector resource is folder-scoped but does not support the
`folderRef` field, you can set the folder ID to the resource configuration
using the `folder-id` annotation:

    ...
    metadata:
      annotations:
        cnrm.cloud.google.com/folder-id: FOLDER_ID
    ...

Here is an example of what a resource's YAML will look like with this annotation
in it:

    apiVersion: foo.cnrm.cloud.google.com/v1beta1
    kind: FooBar
    metadata:
      annotations:
        cnrm.cloud.google.com/folder-id: FOLDER_ID
      name: foobarname

## Annotate namespace configuration

You can set a default folder ID for newly-created resources by
annotating your Kubernetes namespace. If any of the resources in the namespace
have this annotation explicitly set in its own configuration, the resource-level
annotation overwrites the namespace-level annotation.

To annotate the namespace using command line, run the following command:

```
kubectl annotate namespace NAMESPACE_NAME cnrm.cloud.google.com/folder-id=FOLDER_ID
```

Replace the following:

- `NAMESPACE_NAME`: your namespace name
- `FOLDER_ID`: your Google Cloud folder ID

Alternatively, you can apply a YAML manifest containing the annotation.
Copy the YAML below into a file:

    apiVersion: v1
    kind: Namespace
    metadata:
      annotations:
        cnrm.cloud.google.com/folder-id: FOLDER_ID
      name: NAMESPACE_NAME

Replace the following:

- `FOLDER_ID`: your Google Cloud folder ID
- `NAMESPACE_NAME`: your namespace name

After you have created the file, apply it to your cluster.

> [!NOTE]
> **Note:** You must create the namespace and annotation before applying any resources into the namespace.