📋 In This Post
Lab Overview
The problem. I had six Google Cloud projects before this lab
started, accumulated over years of coursework and API experiments, and not one of
them could ever have a policy applied to it. They had no parent
— they sat directly under a personal account with nothing above them. That
is not a configuration mistake to fix. A project owned by a
@gmail.com account structurally cannot have a parent, because an
organization hangs off a domain you administer, and nobody administers
gmail.com.
Folders, organization policy and VPC Service Controls all require an organization resource, which requires Cloud Identity, which requires a domain you own. So the real first task of a landing zone is not Terraform.
Objective. Obtain an organization, then build the hierarchy underneath it in code: four folders that policy can attach to, and three platform projects separated by blast radius.
Expected outcome. Fifteen resources, every project with a parent, no default network anywhere, and remote state living outside Google Cloud entirely.
| Difficulty | Beginner in Terraform terms; the hard parts are IAM and a manual prerequisite |
|---|---|
| Deployment | Terraform with HCP Terraform state, local execution — remote runs need federation, which is Week 2 |
| Reproduce it | Lab guide — the manual first step, the two IAM grants, the billing boundary |
| Cost | $0 — organizations, folders, projects, IAM and API enablement are all free |
Cloud Services and Concepts
| Service | Purpose here | What it is |
|---|---|---|
| Cloud Identity Free | Brings the organization into existence | The identity layer tied to a domain you administer. Verifying a domain here is what causes an organization to exist. Not Workspace — Workspace is paid and adds nothing needed. |
| Resource Manager | Creates the folders and projects the lab is built on | Owns the three node types: organization, folder, project. Also the API that lists them — in two versions that disagree, which matters. |
| Cloud IAM | Grants the roles every later week narrows | Grants roles on any node. Crucially, a grant inherits downward. |
| Service Usage | Turns on only the APIs each project needs | APIs are opt-in per project. Nothing is enabled until you say so. |
| Cloud Billing | Funds the projects, separately from the hierarchy | Funds projects, and sits outside the hierarchy entirely. |
| Terraform + HCP Terraform | Declares the hierarchy and holds its state | Builds the hierarchy and holds its state. HCP needs nothing to pre-exist inside Google Cloud, which turns out to matter at the bootstrap layer. |
A folder is a policy attachment point; that is what it is for.
An organization policy or IAM binding set on workloads/prod applies
to every project beneath it — including projects that do not exist yet.
This is why dev and prod are folders in this lab rather
than labels on a project. A label describes; a folder constrains.
A project is the unit that owns IAM, quota, API enablement and billing attribution — and it is free, and it appears in minutes. Those two facts together are the design input for the whole hierarchy: if separation is cheap, separate. Three platform projects for network, logging and key management cost exactly what one would, and give three independent IAM surfaces.
Billing is not a node in the tree. One billing account funds projects across any folder, and moving a project between folders does not change who pays. Cost separation comes from per-project budgets and labels — and a billing account can belong to an identity your organization roles do not reach at all.
Architecture and Workflow
Four folders, four projects, and a state backend that lives outside Google Cloud entirely.
The flow
- Sign up for Cloud Identity Free on a domain you administer, and sign in to the console as an account from that domain — which is what makes the organization appear.
- Grant yourself
organizationAdminandfolderCreator, because neither is granted automatically. - Cross the billing boundary, if the billing account belongs to an older identity.
- Create a seed project to anchor the lab, and point state at HCP Terraform.
- Build four folders and three platform projects through a reusable project-factory module.
- Verify against Google Cloud rather than against Terraform state.
The decision worth naming
Three platform projects, not one. Network, logging and key management each get a project, because whoever can rotate a key should not thereby be able to rewrite the network, and whoever can read every log line in the estate should not be able to do either.
Prerequisites
- A domain you own and administer. Not optional and not substitutable — everything above a project depends on it.
- Cloud Identity Free. Note that if the domain has no MX records, the super-admin address cannot receive mail, so there is no password-reset path. Set a recovery address you actually read during sign-up and enrol a second factor immediately.
- A billing account with a free project slot.
roles/resourcemanager.organizationAdminandroles/resourcemanager.folderCreatoron yourself. Organization Administrator lets you manage folders but does not includeresourcemanager.folders.create; this week fails without the second role.- Terraform 1.9+ with
hashicorp/google~> 6.0, and an HCP Terraform workspace.
The exact grants and the billing-boundary command are in the lab guide.
Implementation
Fifteen resources, all free. Commands are in the lab guide.
Step 1 — Obtain an organization, which no API will do
Why it is manual: there is no gcloud organizations
create. The subcommands are list, describe and
three IAM verbs — no create, no delete — and there is no Resource
Manager API for it either. An organization is not provisioned; it
appears when a domain is verified in Cloud Identity and an
account from that domain signs in to the console and accepts the terms.
Checkpoint: gcloud organizations describe returns
a resource in state ACTIVE. Because the domain used here was
registered with Google, verification was automatic and no TXT record was needed.
Step 2 — Grant yourself access to your own organization
Why: when an organization is created, Google grants the whole
domain exactly two roles — billing.creator and
projectCreator. Neither lets you see or administer the organization.
Being Cloud Identity super admin does not make you a Google Cloud organization
admin; they are different systems.
gcloud organizations add-iam-policy-binding $ORG_ID \
--member="user:me@example.com" \
--role="roles/resourcemanager.organizationAdmin"
Then folderCreator, separately.
Checkpoint: gcloud organizations list returns one
item. Before the grant it returned zero, which cost twenty minutes — see
Troubleshooting.
Step 3 — Cross the billing boundary
Why: the billing account here belonged to an older personal
identity. The new organization admin is a different principal and inherits
nothing from it, and no organization-level role reaches a billing account
that sits outside the organization. Signed in as the old identity,
grant roles/billing.user to the new one.
Checkpoint: without this,
google_project creation fails on the billing association — and
the error does not obviously point at a cross-identity permission problem.
Step 4 — Folders, because policy attaches to them
resource "google_folder" "workloads" {
display_name = "workloads"
parent = "organizations/${var.org_id}"
}
resource "google_folder" "prod" {
display_name = "prod"
parent = google_folder.workloads.name
}
Why folders and not labels: an organization policy on
workloads/prod constrains every project beneath it, including ones
that do not exist yet. A label constrains nothing.
Checkpoint: folders created in 11–12 seconds, measured on the apply.
Step 5 — A project factory every later week reuses
resource "google_project" "this" {
name = var.display_name
project_id = var.project_id
folder_id = var.folder_id
billing_account = var.billing_account
# The default network ships with permissive firewall rules nobody chose.
auto_create_network = false
labels = local.labels
}
Why a module: so projects are never created ad hoc, and so
two defaults hold everywhere — no default network, and
activate_apis defaulting to an empty list.
Checkpoint: projects took 3m15s, 3m50s and 5m33s. Nothing was wrong — that is how long project creation takes, and it is worth knowing before concluding an apply has hung.
auto_create_network = false holding — the default network
and its permissive firewall rules were never created, so there is nothing to
find and remove later.Step 6 — Verify against the cloud, not against state
Why: state can be confidently wrong. The field that matters is
parent.id — the difference between a project that is
in the hierarchy and one that merely exists.
terraform plan -detailed-exitcode # 0 = no changes, 2 = drift
gcloud projects describe my-lab-seed \
--format="value(projectId,lifecycleState,parent.id)"
Validation and Evidence
| Test | Expected | Actual | Status |
|---|---|---|---|
| Infrastructure deployed | 15 resources | 15 added, 0 changed, 0 destroyed | Pass |
| Terraform agrees with itself | plan -detailed-exitcode returns 0 | 0 — no drift | Pass |
| The folder tree exists and nests correctly | 4 folders | 4, correct nesting | Pass |
| Each project has a parent | the folder, not nothing | correct for all three | Pass |
| No default network anywhere | auto_create_network = false honoured | no network in any project | Pass |
| API enablement is minimal | only what each project uses | 2–3 APIs per project | Pass |
| Creation timings | measured, not assumed | folders 11–12 s; projects 3m15s, 3m50s, 5m33s | Pass |
| The console shows the hierarchy | organization, folders, projects | shown | Pass |
Policy actually constrains the prod folder | a constraint takes effect | not tested this week — no organization policy exists yet; Week 3 | Unverified |
The last row is the honest limit of this week. The folders
were created precisely so they could carry different constraints, and then no
constraints were added. An empty prod folder that enforces nothing
is a false sense of separation — it is a place to attach policy, not policy.
Security and Cost
Security decisions
| Control | Decision and trade-off |
|---|---|
| No service account keys | Not one, in the whole lab. Local runs use Application Default Credentials; CI moves to Workload Identity Federation in Week 2. If something appears to need a key, that is a signal to redesign. |
| No default network | auto_create_network = false everywhere, so the permissive default firewall rules never exist to be forgotten about. |
| Least API enablement | Two or three APIs per project, explicit in code, rather than whatever accumulates. An old personal project had 38. |
| Blast-radius separation | Network, logging and key management in three projects with three IAM surfaces. Free, so there is no reason not to. |
prevent_destroy on the seed project | The project anchoring the lab should not be removable by a mistyped command. Week 2 finds the hole in this — a Terraform guard protects one configuration, not the resource. |
| No account identifiers in the repository | Organization ID, billing account ID and project numbers live only in a gitignored terraform.tfvars, and the staged tree is swept for them before every push. Gitignoring the obvious files is not enough on its own — prose leaks too, so the sweep greps everything staged rather than a filename list. |
| Screenshots captured by a script | capture_gcp.py masks organization IDs, billing account IDs and project numbers in the live page, then refuses to write the file if any identifier survives redaction. |
| Accepted gap | One identity holds both Cloud Identity super-admin and organizationAdmin. That is one account away from total compromise, and it is flagged rather than quietly left. |
Cost
$0. Not "a few cents" — actually nothing. Cloud Identity Free at this user count, the organization resource, folders, projects, IAM bindings and API enablement are all free, and HCP Terraform's free tier covers the runs. Set a budget alert anyway, before anything with a per-hour price arrives: a landing zone costs nothing, but it is the thing every future week bills through.
Troubleshooting and Lessons
gcloud organizations list reported zero items for an organization that existed
Problem: the organization was ACTIVE and the CLI
reported Listed 0 items for several minutes, which sent me looking for a
provisioning delay that was not the problem.
Root cause: gcloud queries the v3
Resource Manager API, which returns only organizations you hold
resourcemanager.organizations.get on. A raw v1
organizations:search call with the same credentials returned it
immediately.
Lesson: zero items is not evidence of absence — it is evidence of a missing permission, and the two are indistinguishable from the CLI. This recurs throughout the series, in both directions.
Terraform ignored the credentials I had just created
Problem: gcloud auth login succeeded and the
provider still could not authenticate.
Root cause: two separate credential stores.
gcloud auth login authenticates the CLI; the provider reads
Application Default Credentials. Two logins, two token files,
and only the second is what Terraform uses.
And a second trap inside it: the ADC consent screen's checkboxes are not ticked by default. Clicking through produced a confident-looking success followed by "cloud-platform scope is required but not consented". The page looks complete when nothing is selected.
Cleanup and Key Takeaways
Cleanup
There is none, deliberately. This is permanent infrastructure — every later week sits inside the hierarchy it creates, so tearing it down orphans the entire lab. The cleanup script refuses to run without an explicit flag:
if [[ "${1:-}" != "--i-really-mean-it" ]]; then
echo "Refusing: week 01 is permanent infrastructure." >&2
exit 1
fi
Ongoing charges: none.
Key takeaways
- You cannot script your way to an organization. No API, no Terraform resource. It appears when a domain is verified and someone from that domain signs in. Plan for a manual first step at the very bottom of the stack.
- An empty CLI result is not proof of absence.
organizations listreturning zero meant "you lack a permission", not "nothing exists". Two API versions, two answers, one command. - A folder is a policy attachment point. Use folders wherever policy needs to differ — a folder constrains every project beneath it, including projects that do not exist yet, and a label constrains nothing.
- Separation is free here, so separate. A project owns IAM, quota, API enablement and billing attribution, and costs nothing. Three platform projects cost what one does.
What production would do differently
Keep the super admin as break-glass and put Organization Administrator on a
separate identity — one account holding both is one account away from total
compromise. Use remote execution and federated credentials before the first
apply, not in a later week, so a plan is reviewable rather than something read on
one laptop. Write organization policy in the same change as the folders, so a
prod folder means something the day it exists. Set the budget alert
first, precisely because nothing here costs money and the guardrail is therefore
easy to defer. And bind to groups rather than users, so access survives people
joining and leaving.
References
- Lab guide — the manual first step, the two IAM grants, the billing boundary, known limitations
- Resource hierarchy
- Creating and managing organizations
- IAM policy inheritance
- Set up Cloud Identity
- Source repository
Comments