google-cloud-recipe-foundation-builder

Google Cloud Recipe: Foundation Builder

> [!WARNING] This skill is currently in a preview state. It will deploy a secure

> foundation, but does not have all advanced features. Users who want more

> options should visit

> Google Cloud Setup.

This skill guides the setup of a secure, enterprise-grade Google Cloud landing

zone foundation. It establishes baseline security controls, organizes the

initial resource hierarchy, and configures centralized audit logging and

cross-environment monitoring.

Overview

The recipe provisions the following core components at the organization root:

• Security Guardrails: Enforces 17 baseline Google Cloud Organization

Policies to secure the environment (13 Boolean, 4 List constraints).

• Resource Hierarchy: Establishes 4 folders (Common, Production,

Non-Production, Development) and provisions corresponding projects

sequentially with globally unique ID prefixes (logging-, prod-,

non-prod-, dev- followed by a shared suffix).

• Billing & API Enablement: Links all projects to your billing account and

activates critical logging/monitoring services.

• Centralized Logging & Monitoring: Deploys a global, centralized log

bucket with 30-day retention, configures an organization-wide audit log

sink, and sets up a cross-environment metrics scope.

--------------------------------------------------------------------------------

Clarifying Questions

Before executing this recipe, the agent must gather the following details:

1. Organization ID: Run gcloud organizations list to retrieve the

available organizations, present them to the user, and ask them to select

the target Organization ID.

1. Billing Account ID: Run `gcloud billing accounts list

--filter=open=true` to retrieve only the active (open) billing accounts,

present them to the user, and ask them to select the active **Billing

Account ID**.

1. Project ID Suffix: Ask if the user has a preferred prefix or target

suffix for Project IDs (default uses prefix + a shared random 8-character

string, e.g., prod-ab12cd34).

1. Log Bucket Region: Ask for the target region for resources if they want

to override the default global log bucket location.

--------------------------------------------------------------------------------

Prerequisites

Ensure the following prerequisites are met before beginning the deployment:

• GCP Identity: You must have a Google Cloud Organization resource set up.
• Administrative IAM Roles: The identity executing these commands must

hold the required administrative permissions. If any step fails with a

Permission Denied error, the agent will attempt to self-remediate by

granting the corresponding recommended role as detailed in **Phase 2: Error

Recovery & Lazy Role Remediation Strategy**.

• Tools: The gcloud CLI must be installed, authorized with the above

identity, and configured for use.

--------------------------------------------------------------------------------

Steps to Complete the Recipe

Phase 1: Pre-flight Confirmation

Identify the target organization and obtain explicit user approval before making

changes.

1. Identify and Discover Organization: Verify the target organization. If

only the display name is known, list organizations to find the ID. Then,

retrieve the organization metadata to dynamically calculate the **Directory

Customer ID and Domain Name**:

    # List to find ID if needed
    gcloud organizations list

    # Describe the organization to retrieve metadata
    gcloud organizations describe [ORGANIZATION_ID]

Calculate values:

• Domain Name ([ORG_NAME] / [YOUR_DOMAIN]): Use the displayName

value from the output (e.g., my-business.com).

• Customer ID ([DIRECTORY_CUSTOMER_ID]): Use the

owner.directoryCustomerId value from the output (e.g., C01234567).

1. Present Blueprint Summary: Present the exact details of the blueprint to

the user and request confirmation to proceed:

> **Proposed Foundation Deployment Summary for Organization: [ORG_NAME]

> ([ORGANIZATION_ID])**

>

> * Security: Enforce 17 baseline Organization Policies (13 Boolean, 4

> List).

> * Folders: Create 4 folders sequentially (Common, Production,

> Non-Production, Development).

> * Projects: Create 4 projects sequentially with unique IDs

> (logging-[SUFFIX], prod-[SUFFIX], non-prod-[SUFFIX],

> dev-[SUFFIX]).

> * Billing: Link all projects to Billing Account

> [BILLING_ACCOUNT_ID].

> * APIs: Enable Logging and Monitoring APIs on the central project.

> * Centralized Logging: Deploy a global log bucket

> [ORG_NAME]-logging (30-day retention), configure an

> organization-level sink

> [ORGANIZATION_ID]-logbucketsink-[RANDOM_HEX], and establish

> cross-project metrics scopes.

>

> Do you wish to proceed with this deployment? (Yes/No)

> [!IMPORTANT] Pause execution and wait for explicit user approval before

> moving to Phase 2. If the user declines, abort the operation.

Phase 2: Error Recovery & Lazy Role Remediation Strategy

To ensure deployment continues smoothly on clean organizations without requiring

complex upfront permission checks (which require a quota project), the agent

must adopt a "lazy recovery" approach.

Instead of testing permissions in advance, the agent will attempt to execute

each step in the recipe. If a step fails with a Permission Denied error, the

agent will attempt to self-remediate by granting the corresponding recommended

administrative group of roles to the deployment identity and retrying the

operation.

> [!IMPORTANT] When asked about pre-deployment readiness, prerequisites, or

> checks to run, the agent must explicitly explain that the landing zone

> deployment adopts a lazy role remediation strategy rather than upfront

> testing, detailing all of the following in its response: 1. Confirm it will

> execute deployment commands directly, catching any Permission Denied

> errors. 2. Confirm it will attempt to self-remediate on failure by running the

> exact commands gcloud organizations add-iam-policy-binding or `gcloud

> billing accounts add-iam-policy-binding` to grant the entire administrative

> group of roles to the active identity, and then retry the failed deployment

> command. 3. List the core administrative groups that it will attempt to grant

> (Organization Admin Group, Billing Admin Group, and Security Admin Group)

> mapped to their key roles. 4. Confirm it will halt execution and request

> manual administrator intervention if the self-remediation grant command fails.

Remediation Protocol

For any command that fails due to missing permissions:

1. Identify Required Admin Group: Determine which administrative group is

responsible for the failed action. Refer to the

[Administrative IAM Reference](references/admin-iam.md#core-administrative-groups--roles)

for details.

1. Attempt Self-Remediation: Grant all roles belonging to that

administrative group to the active authenticated account sequentially. Refer

to the

[Administrative IAM Reference Remediation Guide](references/admin-iam.md#remediation)

for the copy-pasteable script commands:

• **For Organization/Folder level failures (Org Admin Group or Security

Admin Group)**: Run gcloud organizations add-iam-policy-binding

sequentially for each role in the group.

• For Billing level failures (Billing Admin Group): Run `gcloud

billing accounts add-iam-policy-binding` sequentially for each role in

the group.

1. Halt on Remediation Failure:

• If the grant commands succeed, immediately retry the failed deployment

command.

• If any of the grant commands fail (e.g., due to lack of setIamPolicy

admin rights), halt execution and instruct the user to ask their

Organization/Billing Administrator to manually grant the entire

administrative group of roles.

Phase-Specific Remediation Mapping

• Phase 3: Security Guardrails (Org Policies):
• If gcloud org-policies set-policy fails: Attempt to grant the entire

Organization Admin Group (9 roles) at the organization level.

• Phase 4: Resource Hierarchy (Folders & Projects):
• If gcloud resource-manager folders create or gcloud projects create

fails: Attempt to grant the entire Organization Admin Group (9

roles) at the organization level.

• Phase 4: Billing Link:
• If gcloud billing projects link fails: Attempt to grant the entire

Billing Admin Group (3 roles) at the billing account level, and

ensure the active identity is granted the Organization Admin Group

(which contains roles/billing.user) at the organization level.

• Phase 5: Centralized Logging & Monitoring:
• If gcloud logging sinks create fails at org level: Attempt to grant

the entire Logging/Monitoring Admin Group (2 roles:

roles/logging.admin, roles/monitoring.admin) and the **Security

Admin Group** (9 roles) at the organization level.

Phase 3: Security Guardrails (Org Policies)

Apply 17 baseline security controls at the organization root.

> [!CAUTION] Applying iam.allowedPolicyMemberDomains first can lock out the

> deployment identity if it resides in an unallowed domain. Ensure the

> deployment identity is safe before enforcing this policy.

1. Generate the YAML configuration files for the 17 policies. Refer to the

[Organization Policies Reference](references/org-policies.md) for the exact

YAML templates for both Boolean and List constraints.

1. Apply each organization policy sequentially using the gcloud org-policies

tool:

    gcloud org-policies set-policy [POLICY_FILE_NAME].yaml

Phase 4: Resource Hierarchy

1. Folder Creation

Check if target folders exist to avoid duplication. The agent must check for all

4 folders: for any folder that already exists (e.g., if Common or Production

are already present), the agent must locate and reuse them; for any folder that

is missing (e.g., if Non-Production or Development are not present), the

agent must proceed to sequentially create them:

> [!IMPORTANT] When explaining how existing resources (folders and projects) are

> handled to prevent duplication, the agent must explicitly name the

> remaining missing folders (Non-Production and Development) and confirm

> that it will proceed to sequentially create only these missing folders and

> projects.

# Check and Create "Common" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Common"
# If not present:
gcloud resource-manager folders create --display-name="Common" --organization=[ORGANIZATION_ID]

# Check and Create "Production" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Production"
# If not present:
gcloud resource-manager folders create --display-name="Production" --organization=[ORGANIZATION_ID]

# Check and Create "Non-Production" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Non-Production"
# If not present:
gcloud resource-manager folders create --display-name="Non-Production" --organization=[ORGANIZATION_ID]

# Check and Create "Development" Folder
gcloud resource-manager folders list --organization=[ORGANIZATION_ID] --filter="display_name=Development"
# If not present:
gcloud resource-manager folders create --display-name="Development" --organization=[ORGANIZATION_ID]

2. Project Creation and Billing Link

Check if target projects already exist in the folders by matching their display

names. If not present, generate a shared 8-character random suffix (e.g.,

ab12cd34) and create the projects sequentially, linking billing and enabling

APIs immediately:

# Check if "central-logging-monitoring" project exists in Common folder
gcloud projects list --filter="parent.id=[COMMON_FOLDER_ID] AND parent.type=folder AND name=central-logging-monitoring"

# If not present: Create, link billing, and enable APIs
gcloud projects create logging-[SUFFIX] --name="central-logging-monitoring" --folder=[COMMON_FOLDER_ID]
gcloud billing projects link logging-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com logging.googleapis.com monitoring.googleapis.com --project=logging-[SUFFIX]

# Check if "production" project exists in Production folder
gcloud projects list --filter="parent.id=[PRODUCTION_FOLDER_ID] AND parent.type=folder AND name=production"

# If not present: Create, link billing, and enable APIs
gcloud projects create prod-[SUFFIX] --name="production" --folder=[PRODUCTION_FOLDER_ID]
gcloud billing projects link prod-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com run.googleapis.com container.googleapis.com artifactregistry.googleapis.com firestore.googleapis.com pubsub.googleapis.com aiplatform.googleapis.com cloudaicompanion.googleapis.com apphub.googleapis.com designcenter.googleapis.com discoveryengine.googleapis.com iam.googleapis.com config.googleapis.com cloudbuild.googleapis.com cloudasset.googleapis.com cloudkms.googleapis.com cloudresourcemanager.googleapis.com --project=prod-[SUFFIX]

# Check if "non-production" project exists in Non-Production folder
gcloud projects list --filter="parent.id=[NON_PRODUCTION_FOLDER_ID] AND parent.type=folder AND name=non-production"

# If not present: Create, link billing, and enable APIs
gcloud projects create non-prod-[SUFFIX] --name="non-production" --folder=[NON_PRODUCTION_FOLDER_ID]
gcloud billing projects link non-prod-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com run.googleapis.com container.googleapis.com artifactregistry.googleapis.com firestore.googleapis.com pubsub.googleapis.com aiplatform.googleapis.com cloudaicompanion.googleapis.com apphub.googleapis.com designcenter.googleapis.com discoveryengine.googleapis.com iam.googleapis.com config.googleapis.com cloudbuild.googleapis.com cloudasset.googleapis.com cloudkms.googleapis.com cloudresourcemanager.googleapis.com --project=non-prod-[SUFFIX]

# Check if "development" project exists in Development folder
gcloud projects list --filter="parent.id=[DEVELOPMENT_FOLDER_ID] AND parent.type=folder AND name=development"

# If not present: Create, link billing, and enable APIs
gcloud projects create dev-[SUFFIX] --name="development" --folder=[DEVELOPMENT_FOLDER_ID]
gcloud billing projects link dev-[SUFFIX] --billing-account=[BILLING_ACCOUNT_ID]
gcloud services enable compute.googleapis.com run.googleapis.com container.googleapis.com artifactregistry.googleapis.com firestore.googleapis.com pubsub.googleapis.com aiplatform.googleapis.com cloudaicompanion.googleapis.com apphub.googleapis.com designcenter.googleapis.com discoveryengine.googleapis.com iam.googleapis.com config.googleapis.com cloudbuild.googleapis.com cloudasset.googleapis.com cloudkms.googleapis.com cloudresourcemanager.googleapis.com --project=dev-[SUFFIX]

> [!NOTE] Agentic Parallelism Option: While the manual runbook enforces

> sequential project execution to avoid terminal race conditions, an AI agent

> with multi-agent orchestration capability may optionally spawn subagents to

> provision the 4 projects in parallel once folder IDs are resolved.

Phase 5: Centralized Logging and Monitoring

Configure centralized audit logging and cross-project monitoring scope in the

logging-[SUFFIX] project.

Refer to the

[Centralized Logging and Monitoring Reference](references/logging-monitoring.md)

for the detailed step-by-step commands to:

1. Create the central log bucket.
2. Create the organization-wide log sink.
3. Grant required IAM permissions to the log sink.
4. Configure the cross-project monitoring metrics scope.

--------------------------------------------------------------------------------

Validation Logic & Checklist

Evaluate the deployment against the following verification checks:

• [ ] Security Policies: Run `gcloud org-policies list

--organization=[ORGANIZATION_ID]` and verify all 17 target policies are

enforced or correctly configured.

• [ ] Resource Folders: Verify folders Common, Production,

Non-Production, and Development exist under the organization root.

• [ ] Billing Linkage: Run gcloud billing projects list and assert that

all 4 newly created projects are linked to your billing account.

• [ ] Log Bucket & Retention: Verify the log bucket [ORG_NAME]-logging

exists in project logging-[SUFFIX], is located in global, and has a

retention period of exactly 30 days.

• [ ] Log Sink Routing: Run gcloud logging sinks describe at the

organization level and confirm the sink routes cloud audit logs to the

global bucket and holds standard writerIdentity credentials.

• [ ] Metrics Scope Linkage: Run `gcloud beta monitoring metrics-scopes

describe and assert that the dev, non-prod, and prod` projects appear

in the monitored list of the central logging project.

--------------------------------------------------------------------------------

Links

• Google Cloud Resource Hierarchy Documentation
• Google Cloud Organization Policies Overview
• Centralized Audit Logging Best Practices
• Cloud Monitoring Metrics Scopes Configuration
• Gcloud Logging Sinks CLI Reference
• Google Cloud Landing Zones Guide
• Google Cloud Security Foundations Blueprint