GCP Resource Hierarchy: Organizations, Folders, and Projects

You just deployed a critical service to production. Two weeks later, a junior engineer accidentally grants roles/editor to all authenticated users on a project containing your customer database. No blast radius. No audit trail. Just a ticking time bomb. This is the reality when you skip the GCP resource hierarchy. Most teams treat projects as flat buckets—a recipe for chaos at scale. The hierarchy is your first line of defense: it enforces policy inheritance, isolates environments, and gives you granular control without duplicating effort. If you're managing more than a handful of projects, ignoring the hierarchy is a production incident waiting to happen.

The Four Levels of the Hierarchy

The GCP resource hierarchy consists of four levels: Organization, Folders, Projects, and Resources. The Organization node sits at the top and represents your company. Folders group projects under business units or environments. Projects contain the actual resources like Compute Engine instances, Cloud Storage buckets, and BigQuery datasets. Resources are the leaf nodes—individual services. Policies set at a higher level automatically cascade down, but lower-level policies can override if allowed. This structure mirrors real-world organizational charts, making it intuitive for access control and cost allocation. In production, you'll rarely touch resources directly; you'll manage at the project or folder level.

# View your organization
$ gcloud organizations list
DISPLAY_NAME          ID
example.com           123456789012

# List folders under organization
$ gcloud resource-manager folders list --organization=123456789012
DISPLAY_NAME  PARENT_NAME               ID
Engineering   organizations/123456789012 987654321
Finance       organizations/123456789012 876543210

# List projects under a folder
$ gcloud projects list --filter="parent.id=987654321"
PROJECT_ID        NAME            PROJECT_NUMBER
prod-app          Production App  111111111111
dev-app           Development App 222222222222

Organization Node: The Root of All Access

The Organization node is the top-level container. It's automatically created when you verify your domain with G Suite or Cloud Identity. Without it, you can't use folders or organization-level IAM. The Organization node is where you set company-wide policies, like restricting which services can be used or enforcing VPC Service Controls. You assign the Organization Administrator role to a small group of trusted admins. This role can manage all projects and folders, so treat it like the root keys to your kingdom. In production, limit this role to fewer than five people and require break-glass procedures for emergency access.

# Get organization ID
ORG_ID=$(gcloud organizations list --format='value(ID)')

# Grant Organization Admin to a user
gcloud organizations add-iam-policy-binding $ORG_ID \
  --member='user:admin@example.com' \
  --role='roles/resourcemanager.organizationAdmin'

# View current IAM policy
gcloud organizations get-iam-policy $ORG_ID --format=json | jq '.bindings[] | select(.role | contains("admin"))'

Folders: Grouping Projects by Environment or Team

Folders are containers for projects. They let you apply common policies to a group of projects, like setting a budget alert for all development projects or enforcing a VPC firewall rule. Folders can be nested up to 10 levels deep, but keep it shallow—three levels max in production. Common patterns: /BusinessUnit/Environment (e.g., /Engineering/Production) or /Team/ProjectType. Folders inherit policies from the Organization, and projects inherit from their parent folder. This inheritance is powerful but can be confusing when overrides happen. Always use the Policy Analyzer to verify effective permissions.

# Create a folder under organization
ORG_ID=123456789012
gcloud resource-manager folders create \
  --display-name="Production" \
  --organization=$ORG_ID

# Create a nested folder
PARENT_FOLDER=987654321
gcloud resource-manager folders create \
  --display-name="AppTeam" \
  --folder=$PARENT_FOLDER

# List folder hierarchy
gcloud resource-manager folders list --organization=$ORG_ID --recursive

Projects: The Atomic Unit of Isolation

A project is the base-level container for GCP resources. It isolates resources, billing, and permissions. Each project has a unique ID, name, and number. Resources within a project share a VPC network by default (unless using Shared VPC). Projects are the boundary for most IAM roles—you grant access to a project, not to individual resources. In production, use one project per service or microservice to limit blast radius. Avoid the 'all-in-one' project anti-pattern; it leads to permission sprawl and accidental cross-service access.

# Create a new project under a folder
FOLDER_ID=555555555
gcloud projects create my-production-app \
  --name="My Production App" \
  --folder=$FOLDER_ID

# Set billing account (required for most services)
BILLING_ACCOUNT_ID=XXXXXX-YYYYYY-ZZZZZZ
gcloud beta billing projects link my-production-app \
  --billing-account=$BILLING_ACCOUNT_ID

# List projects with hierarchy info
gcloud projects list --format="table(projectId, parent.id, parent.type)"

IAM Policy Inheritance: How Policies Flow Down

IAM policies set at a higher level (Organization, Folder) are inherited by all descendants. For example, granting roles/storage.objectViewer at the Organization level gives read access to all buckets in all projects. This is convenient but dangerous. You can override inherited policies at lower levels, but only if the higher-level policy allows it (using deny rules or conditional bindings). In production, use the principle of least privilege: set broad roles at the Organization level (e.g., Security Reviewer) and specific roles at the project level. Always use the Policy Analyzer to check effective permissions before making changes.

# Set a folder-level policy
FOLDER_ID=555555555
gcloud resource-manager folders add-iam-policy-binding $FOLDER_ID \
  --member='group:devops@example.com' \
  --role='roles/compute.admin'

# Check effective policy on a project under that folder
PROJECT_ID=my-production-app
gcloud projects get-iam-policy $PROJECT_ID --format=json | jq '.bindings[] | select(.role | contains("compute.admin"))'

Best Practices for Organizing Projects

Organize projects by environment (prod, staging, dev) and team. Use a consistent naming convention: {environment}-{team}-{service}. For example, prod-platform-auth. Apply labels to projects for cost tracking and automation. Use folders to mirror your organizational structure, but avoid deep nesting. A common pattern: Organization > Environment > Team. Each team gets a folder under their environment folder. This makes IAM management straightforward: grant team-level roles at the team folder, environment-wide roles at the environment folder.

# Add labels to a project
gcloud projects update my-production-app \
  --update-labels=environment=prod,team=platform,service=auth

# List projects with labels
gcloud projects list --format="table(projectId, labels)"

Common Pitfalls and How to Avoid Them

Pitfall 1: Flat project structure with no folders. This makes IAM management a nightmare as you scale. Solution: Use folders from day one. Pitfall 2: Overly permissive organization-level roles. Solution: Grant only read-only roles at the organization level. Pitfall 3: Ignoring policy inheritance. Solution: Use the Policy Analyzer to simulate changes. Pitfall 4: Not using Shared VPC for multi-project networking. Solution: Set up a host project with Shared VPC and attach service projects. Pitfall 5: Deleting projects without backup. Solution: Enable deletion prevention and take snapshots of critical resources.

# Enable deletion prevention on a project
gcloud resource-manager projects update my-production-app \
  --deletion-protection

# Verify
gcloud resource-manager projects describe my-production-app \
  --format='get(lifecycleState)'

Using Organization Policies for Guardrails

Organization policies let you set constraints on all resources under the hierarchy. For example, you can restrict the locations where resources can be created (e.g., only us-central1), or disable service account key creation. These policies are inherited and can be overridden at lower levels if allowed. Use them to enforce compliance and security standards. Common constraints: constraints/compute.restrictLoadBalancerCreationForTypes, constraints/iam.disableServiceAccountKeyCreation, constraints/gcp.resourceLocations. In production, start with a few critical policies and expand gradually.

# Set a location restriction policy at organization level
ORG_ID=123456789012
gcloud resource-manager org-policies set-policy \
  --organization=$ORG_ID \
  --policy-file=policy.yaml

# policy.yaml content:
# constraints:
# - constraint: constraints/gcp.resourceLocations
#   listPolicy:
#     allowedValues:
#     - us-central1
#     - us-east1

Auditing and Monitoring the Hierarchy

Audit all IAM changes using Cloud Audit Logs. Enable Data Access logs for sensitive resources. Use the Policy Analyzer to check effective permissions. Set up alerts for changes to organization-level IAM. Use Cloud Asset Inventory to get a snapshot of all resources and their policies. In production, we have a weekly job that exports the hierarchy to BigQuery for analysis. This helps detect drift and unauthorized changes.

# Enable Data Access audit logs for all services
ORG_ID=123456789012
gcloud logging buckets create audit-logs-bucket \
  --location=us-central1 \
  --organization=$ORG_ID

# Create a sink to BigQuery
gcloud logging sinks create audit-sink \
  bigquery.googleapis.com/projects/my-project/datasets/audit_logs \
  --log-filter='logName:"cloudaudit.googleapis.com"' \
  --organization=$ORG_ID

Migrating from Flat Projects to a Hierarchy

If you already have projects without a hierarchy, you can move them under folders. Use gcloud projects move to change the parent. However, moving a project can affect IAM policies if the new parent has different policies. Plan carefully: test in a non-production project first. You may need to adjust IAM bindings after the move. Also, update any automation scripts that reference the old parent. In production, we do this migration in phases: first move dev projects, then staging, then production.

# Move a project to a folder
PROJECT_ID=my-production-app
DEST_FOLDER=555555555
gcloud projects move $PROJECT_ID --folder=$DEST_FOLDER

# Verify new parent
gcloud projects describe $PROJECT_ID --format='get(parent)'

Automating Hierarchy Management with Infrastructure as Code

Use Terraform or Deployment Manager to manage the hierarchy as code. This ensures consistency and auditability. Define the organization, folders, and projects in configuration files. Use modules to standardize folder structures. For example, a module that creates a folder with a set of projects, each with predefined IAM bindings. In production, we store the hierarchy config in a Git repo and apply changes via CI/CD. This prevents manual drift and provides a change history.

provider "google" {
  project = "my-admin-project"
}

resource "google_folder" "production" {
  display_name = "Production"
  parent       = "organizations/123456789012"
}

resource "google_project" "prod_app" {
  name       = "My Production App"
  project_id = "prod-app-123"
  folder_id  = google_folder.production.id
  billing_account = "XXXXXX-YYYYYY-ZZZZZZ"
}

resource "google_project_iam_binding" "prod_app_owner" {
  project = google_project.prod_app.project_id
  role    = "roles/owner"
  members = ["group:prod-admins@example.com"]
}

Resource Manager Tags: Attribute-Based Access Control

Resource Manager Tags let you attach key-value pairs to resources (projects, folders, VMs, etc.) and use them in IAM conditions for fine-grained access control. Unlike labels, Tags are not inherited—they must be explicitly attached. But Tags support conditional IAM bindings: you can grant a role only if the resource has a specific Tag. For example, grant roles/compute.instanceAdmin only on VMs tagged with environment=production. Tags can also be used in Organization Policies for scoped constraints. Key difference from labels: Tags are IAM-evaluated and can be used in policy bindings; labels are for metadata and cost tracking only. In production, use Tags for access control and labels for cost allocation. Tags can be inherited from parent resources if you use inherited mode. This is powerful: set a Tag at the folder level and all child resources automatically inherit it, enabling policy-based access at scale.

# Create a Tag key at the organization level
ORG_ID=123456789012
gcloud resource-manager tags keys create environment \
  --parent=organizations/$ORG_ID \
  --description="Environment classification"

# Create Tag values
gcloud resource-manager tags values create prod \
  --parent=organizations/$ORG_ID/tags/environment \
  --description="Production environment"

# Attach Tag to a folder
FOLDER_ID=555555555
gcloud resource-manager tags bindings create \
  --parent=folders/$FOLDER_ID \
  --tag-value=organizations/$ORG_ID/environment/prod

# Use Tag in IAM condition
gcloud organizations add-iam-policy-binding $ORG_ID \
  --member='group:prod-admins@example.com' \
  --role='roles/compute.admin' \
  --condition="expression=resource.matchTag('organizations/$ORG_ID/environment/prod'),title=prod_only"

Deny Policies: Blocking Permissions at Scale

IAM Deny Policies let you explicitly deny permissions at any level of the hierarchy, overriding any allow policies. This is critical for defense-in-depth. For example, you can create a deny rule at the organization level that blocks all users from making resources public, even if they have project-level Owner role. Deny policies are evaluated before allow policies, so they always take precedence. Use them for mandatory controls like: preventing public bucket access, blocking service account key creation, or restricting the use of certain machine types. Deny policies support conditions, so you can deny only in specific contexts (e.g., deny storage.buckets.setIamPolicy when the request comes from outside your corporate network). In production, we use deny policies to enforce compliance requirements that must never be overridden, while using allow policies for day-to-day access control.

# Create a deny policy at the organization level
ORG_ID=123456789012
cat > deny_policy.yaml << EOF
name: organizations/$ORG_ID/denyPolicies/deny-public-access
denyPolicy:
  rules:
  - denyRule:
      deniedPrincipals:
      - principalSet://goog/public:allUsers
      - principalSet://goog/public:allAuthenticatedUsers
      denialCondition:
        expression: resource.type == "storage.googleapis.com/Bucket"
EOF

gcloud iam deny-policies create deny-public-access \
  --organization=$ORG_ID \
  --policy-file=deny_policy.yaml

# List deny policies
gcloud iam deny-policies list --organization=$ORG_ID