The Cloud Resource Manager API lets you discover and catalog every folder and project
across your Google Cloud
[resource hierarchy](https://docs.cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy.md.txt).
This visibility helps you conduct audit checks and build custom management
tools. Standard list operations can omit resources when users have restricted
[custom roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt). You can filter your queries by
parent references to get consistent search results and identify nodes that
least-privilege permissions might otherwise hide.

## List all resource nodes

When you scan your resource hierarchy to list every resource, you need strongly
consistent results. If your scan misses resources or provides outdated results,
it can be hard to tell that something has gone wrong. To make sure that you
always get the most accurate and complete results, use a service account and
perform a scan in the following way:

1. Grant a service account the `list` and `get` permissions for Organizations, Folders, and Projects on the Organization resource.
2. If you are listing Project and Folder resources, specify the parent resource in the filter string.
3. Run the [`projects.list()`](https://docs.cloud.google.com/resource-manager/reference/rest/v3/projects/list.md.txt) method with this service account for each type of resource you want to find, and for any intermediate resources such as Folders.

### Example to list all resource nodes

The following pseudocode demonstrates how to list every resource node in your
Organizations:

    organizations = organizations.search()
    projects = emptyList()

    parentsToList = queueOf(organizations)
    while (parent = parentsToList.pop()) {
      // TODO: Iterate over paginated results as needed.
      // TODO: Handle PERMISSION_DENIED appropriately.
      projects.addAll(projects.list(parent.type, parent.id))
      parentsToList.addAll(folders.list(parent))
    }

When building a custom user experience, you may also want to mix in search
results and load the parent resources as needed (while also catching the
`PERMISSION_DENIED` exception).

## Reduce latency on gcloud projects list

If your `gcloud projects list` query fails or takes too long, the number of
Google Cloud projects to return might be too large. To fix this, apply the
`filter` and `page-size` flags to your `gcloud projects list` command.

To learn more about the flags you can add to your `gcloud projects list` command,
see [gcloud projects list](https://docs.cloud.google.com/sdk/gcloud/reference/projects/list).

### Exclude Apps Script projects example

The most common cause of query failures or latency is a high number of Apps
Script projects within an organization. The following command shows how to exclude
Apps Script projects from the projects list and limit the number of resources
returned per page.

    gcloud projects list --filter="NOT parent.id: 'APPS_SCRIPT_FOLDER_ID' "--page-size='30'

#### Get the Apps Script folder ID

To find your Apps Script folder ID, take the following steps.

1. In the toolbar of the Google Cloud console, click
   **Search for resources, docs, products, and more** and type `apps-script`.

   [Go to Google Cloud console](https://console.cloud.google.com/welcome)
2. Under **Resources** select the **apps-script** folder.

3. Under **Folder ID** copy the folder ID.

## Search resources

If your scan is intended to search for a resource that was created some time
ago, you can perform a faster scan that has eventual consistency rather than
strong consistency. Note that this search method may omit some resources from
the search result, particularly any resources that have been changed recently.
To search for resources:

1. Use a service account that has the `get` permission for the resource you are searching for.
2. Run the [`projects.search()`](https://docs.cloud.google.com/resource-manager/reference/rest/v3/projects/search.md.txt) method with this service account.

## Troubleshooting omitted resources

If you are developing a scanning tool, we recommend that you use `list` and
`get` permissions granted at the Organization level. This avoids issues caused
by the user having partial permissions, which results in some resources being
omitted from the list.

If you are designing a custom user experience that checks user permissions,
there is no straightforward solution. If a user does not have Organization-level
permissions, they will need certain permissions on every resource for it to
appear. If a user is missing permissions on a resource somewhere in the
hierarchy, some resources may not appear.

If a user has the `list` permission but not the `get` permission for a
particular resource, that resource won't be visible at all in the
Google Cloud console. However, the resource will be returned in a search using the
API or Google Cloud CLI that specifies the resource's parent. This disparity
between the Google Cloud console and other methods is a common source of confusion
when trying to scan the resource hierarchy.

The following diagrams demonstrate some common configurations of permissions,
and how they change what resources are visible to a user running a search.

![Listing all resources](https://docs.cloud.google.com/resource-manager/img/list-all.svg "Listing all resources")

In this example, all required permissions are granted in the Organization
resource. Therefore, the entire hierarchy is visible when performing a list or
search.

![Missing organization permissions](https://docs.cloud.google.com/resource-manager/img/list-no-org.svg "Missing organization permissions")

The user in this example has all required permissions except for
`resourcemanager.organizations.get`, but they are granted those permissions at
the Folder level. This permissions gap gives them full visibility on list or
search of that part of the hierarchy, but not the other half.

![Project get permission only](https://docs.cloud.google.com/resource-manager/img/list-project-get.svg "Project get permission only")

This example shows the experience of a user with only the
`resourcemanager.projects.get` permission granted at the Folder resource level.
They are able to see the Projects underneath that Folder in the hierarchy, but
only by searching. Using the list functionality won't return any results.

![Folder get permission only](https://docs.cloud.google.com/resource-manager/img/list-folder-get.svg "Folder get permission only")

This example illustrates a similar scenario where the granted permissions only
let you find your Folder resources by searching. The list operation does not
return any results.

![Mixed permissions](https://docs.cloud.google.com/resource-manager/img/list-mixed.svg "Mixed permissions")

The user in this example has a mix of permissions throughout their Organization.
They can list folders from the Organization level, which allows them to find
them with searches that specify the parent resource throughout the hierarchy.
They can list Project resources for one Folder, but not the other, and they have
`resourcemanager.projects.get` permission on one Project at the bottom of the
hierarchy.

The result is that they aren't able to return the Projects on the left side of
this resource hierarchy. They can list the Projects on the right side only by
using a search that specifies the parent resource, and only one Project is
visible when viewed in the Google Cloud console.

![Undiscoverable resources](https://docs.cloud.google.com/resource-manager/img/list-undiscoverable.svg "Undiscoverable resources")

In this example, you can get the Organization resource and list Project
resources by specifying the parent throughout the hierarchy. However, you don't
have permission to list or search any intermediate Folders. Your Projects are
searchable if you know the ID of their parent Folder. The Folders are not
visible to you, so you can't discover the ID if you don't already have it. The
only resource that appears in the Google Cloud console is the Organization.

When designing your custom user experience, it's important to be aware of
situations similar to these situations. You can use a combination of listing and
searching to render the resource hierarchy. You should also consider how to
communicate to users that they are missing permissions that would allow them to
see the whole resource hierarchy.