GCP - Resource Hierarchy

The Google Cloud Resource Hierarchy is the logical structure used to organize and manage resources within Google Cloud Platform (GCP).

Think of it as a digital filing cabinet or a corporate org chart. It defines how your cloud "possessions" are grouped and, more importantly, how permissions and policies flow from the top down.

The Four Levels of the Hierarchy

1. The Organization (The Root)

This is the highest level of the hierarchy. It represents your entire company.

Ownership: It is strictly tied to a Google Workspace or Cloud Identity domain (e.g., yourcompany.com).
Purpose: It provides centralized visibility and control over every resource in your company.
Key Role: The "Organization Admin" has the power to see and manage everything below this node.

2. Folders (The Departments) — Optional

Folders are used to group projects or other folders.

Purpose: They allow you to mirror your actual company structure. You might have folders for Departments (Engineering, Marketing) or Environments (Production, Development, Staging).
Nesting: You can nest folders inside other folders (up to 10 levels deep).
Benefit: You can apply a policy to the "Production" folder, and it will automatically apply to every project inside that folder.

3. Projects (The Unit of Work)

The Project is the base level where you actually "do" things.

Purpose: Resources must belong to a project. You cannot create a Virtual Machine or a Database without a project.
Boundaries: Projects act as a boundary for APIs, Billing, and Quotas.
Billing: Every project must be linked to a Billing Account (though multiple projects can share one billing account).

4. Resources (The Tools)

These are the actual services you use.

Examples: Compute Engine VMs, Cloud Storage Buckets, BigQuery Datasets, App Engine services.
Location: These live at the very bottom of the tree.

The Two Golden Rules of Hierarchy

Rule #1: Inheritance (The Waterfall)

Policies (IAM permissions and Organization Policies) flow downwards.

If you give someone "Viewer" access at the Folder level, they automatically become a "Viewer" for every Project inside that folder and every Resource inside those projects.
You cannot "block" or "remove" an inherited permission at a lower level.

Rule #2: Permissions are Additive

If a user has "Storage Admin" at the Organization level and you grant them "Compute Admin" at the Project level, they now have both. Permissions only ever expand as you move down the tree; they never shrink.

Why does the Hierarchy matter?

Feature	How the Hierarchy helps
Security	You can grant the Security Team "Security Reviewer" at the Org level so they can see everything without being manually added to 500 different projects.
Compliance	You can set an "Org Policy" at the top that says "No project in this company is allowed to have a public IP address."
Billing	You can use the hierarchy to see exactly how much the "Marketing Department" (Folder) is spending across all their various projects.
Efficiency	When a new employee joins the "Dev" team, you add them to the "Dev Folder," and they instantly get access to all the tools they need.

Visual Summary

[ Organization ]  <-- (Domain: example.com)
       |
    [ Folder ]    <-- (Department: Engineering)
       |
    [ Folder ]    <-- (Environment: Production)
       |
    [ Project ]   <-- (App: Payment-Gateway)
       |
    [ Resource ]  <-- (VMs, Databases, Buckets)

Pro Tip: Always design your hierarchy around Policy and Billing needs, not just your company's HR org chart. Group things together that need the same security rules.

Related APIs

To manage and automate the Resource Hierarchy, you will primarily interact with a small group of specialized "Manager" APIs.

The most important one is the Cloud Resource Manager API, but others handle the permissions and governance that sit on top of that hierarchy.

1. Cloud Resource Manager API (`cloudresourcemanager.googleapis.com`)

This is the "master" API for the hierarchy itself. It is used to programmatically build the "tree."

What it does: Creates, deletes, and moves Projects and Folders. It is also used to fetch Organization metadata.
Key Resources: organizations, folders, projects, and liens (which prevent accidental deletion).
Recent Addition: It also manages Tags (namespaced key-value pairs used for conditional IAM).

2. Identity and Access Management (IAM) API (`iam.googleapis.com`)

While the Resource Manager creates the "buckets," the IAM API decides who can look inside them.

Relation to Hierarchy: Every resource in the hierarchy has a getIamPolicy and setIamPolicy method. When you call these via the API, you are defining the "inheritance" rules for that node.
What it does: Manages Service Accounts, Roles, and the Allow Policies that attach to the Folders and Projects you created with the Resource Manager.

3. Organization Policy API (`orgpolicy.googleapis.com`)

This API is used to set the "guardrails" or constraints that inherit downward.

What it does: Allows you to programmatically restrict what can happen in your hierarchy (e.g., "Disable all external IPs for this Folder").
Key Concept: You use this to define Constraints at the Org or Folder level, which then automatically apply to all child Projects.

4. Essential Contacts API (`essentialcontacts.googleapis.com`)

This API manages the "who to call" settings that inherit from the Org.

What it does: Sets contact points for specific categories (Legal, Billing, Security).
Relation to Hierarchy: If you set a Security contact at the Organization level using this API, that contact is automatically "inherited" by every project, ensuring they get notified of security alerts everywhere.

5. Cloud Asset API (`cloudasset.googleapis.com`)

If the Resource Manager is for building the hierarchy, the Asset API is for searching it.

What it does: It provides an inventory of every resource in your hierarchy.
Hierarchy Feature: It has a "Search All Resources" and "Search All IAM Policies" feature that allows you to see the entire tree at once to find out exactly where a specific permission is being inherited from.

6. Cloud Billing API (`cloudbilling.googleapis.com`)

Relation to Hierarchy: Used to associate a Project (created via Resource Manager) with a Billing Account. It is also used to move projects between different billing sub-accounts.

Summary Checklist for Developers

If you are writing a script to automate a "New Department" setup:

Cloud Resource Manager API: Create the Folder and Project.
Cloud Billing API: Link the Project to the company billing account.
IAM API: Add the Department Head as an Owner.
Org Policy API: Set a constraint to keep data in a specific region.
Service Usage API: Enable the specific APIs (like Vision or BigQuery) needed for that project.

When creating a new Project, which settings will be inherited?

When you create a new Google Cloud (GCP) project within an Organization, it does not start as a "blank slate." Because of the GCP Resource Hierarchy (Organization → Folders → Projects), the project automatically adopts several "guardrails" and access rules.

Here are the specific settings that a new project inherits from the Organization (or the parent Folder):

1. IAM Policies (Permissions)

This is the most critical inheritance. IAM permissions are additive.

Inherited Roles: If a user is granted the Storage Admin role at the Organization level, they automatically have Storage Admin rights over the new project. You cannot "strip away" an inherited permission at the project level; you can only add more.
Service Accounts: If you have defined Organization-level custom roles, the new project can utilize them immediately.

2. Organization Policies (Constraints)

Organization Policies are the "governance" rules that restrict what can be done in a project.

Examples of Inherited Constraints:
- Allowed Locations: If the Org restricts resource creation to the us-east1 region, the new project cannot create a VM in europe-west1.
- Domain Restricted Sharing: Restricts the ability to add users from outside your workspace (GWS/Cloud Identity) to IAM roles.
- Disable Service Account Key Creation: Prevents users from downloading JSON keys for service accounts.
- Skip Default VPC: Prevents the project from automatically creating a "default" network upon enablement of the Compute API.

3. Essential Contacts

If you have configured Essential Contacts at the Organization level (for categories like Billing, Legal, Security, or Operations), these contacts will automatically receive notifications regarding the new project. This ensures that the security team is notified of a breach in a new project even if the project creator didn't add them.

4. Tags (Resource Manager Tags)

Tags are key-value pairs used for fine-grained access control or cost tracking.

Inheritance: If a parent Folder or the Organization has a tag like environment: production, the new project inherits that tag.
Note: This is different from Labels. Labels are metadata for filtering/billing and do not inherit; Tags are a Resource Manager feature and do inherit.

5. Shared VPC (Service Project Status)

If the Organization uses Shared VPC, the new project can be automatically (or manually) linked as a "Service Project."

While the project doesn't "inherit" the network itself by default, it inherits the permission to use subnets from a Host Project if the Org-level IAM allows it.

6. Cloud Logging Sinks (Aggregated Sinks)

If the Organization has an Aggregated Log Sink (for example, sending all "Data Access" logs to a central BigQuery dataset for compliance), the new project’s logs will automatically flow into that sink. The project owner cannot stop this from the project level.

7. Security Command Center (SCC)

If SCC is enabled at the Organization level, it will automatically start scanning the new project for vulnerabilities and misconfigurations (like open firewall ports or public buckets) the moment it is created.

What does NOT inherit?

It is equally important to know what you must set up manually for every new project:

Billing Account Linkage: While you usually choose a billing account during creation, the project is technically a separate entity that must be "associated" with a billing account.
API Enablement: By default, almost all APIs (Compute, BigQuery, Vision, etc.) are disabled in a new project. You must enable them specifically for that project.
Labels: As mentioned, labels (used for gcloud filtering and billing export) must be applied at the project level.
Quotas: Most quotas are project-specific. While the Org might have a high "Project Creation Quota," the individual project starts with its own "GPU Quota" or "Static IP Quota" (usually at the default levels).
Default Service Accounts: These are created only when you enable specific APIs (like the Compute Engine default service account).

Summary Table

Feature	Inherited?	Effect on New Project
IAM Roles	Yes	Users get the same or more power.
Org Policies	Yes	Sets strict limits on what users can do.
Tags	Yes	Used for automated policy/security.
Essential Contacts	Yes	Notifications go to the right people.
Labels	No	Must be set manually for billing.
APIs	No	Must be enabled manually.
Billing Link	Selected	Must be chosen at creation.