Front matter
Source Code and Example Repository
The source code for this book belongs in a public companion repository so the printed pages do not have to pretend that infrastructure code is static.
Canonical repository: https://github.com/megalithic-books/megalith-big-gcp-book
Repository goals §
The repository exists to provide:
- complete examples that are too large for the printed page;
- tested Terraform configurations;
- tested OpenTofu configurations where behavior differs;
- Ansible playbooks and roles;
- shell commands and supporting files;
- Kubernetes manifests;
- policy examples;
- CI/CD pipeline definitions;
- version information;
- corrections;
- migration notes when tooling changes.
Layout §
megalith-big-gcp-book/
├── README.md
├── LICENSE MIT, covering the code only
├── CHANGELOG.md
├── book-version
├── code/
│ ├── tf/
│ │ ├── network/ Shared VPC host network (5.28, 26.28)
│ │ ├── project-iam/ Additive-only project IAM (3.11, 26.29)
│ │ ├── org-policy-baseline/ The Appendix C constraint manifest
│ │ └── environments/prod/ Root module composing the three (26.5, 26.18)
│ ├── opentofu/
│ │ └── state-encryption/ What Terraform cannot do (27.5, 27.11)
│ ├── ansible/
│ │ ├── inventory/ Dynamic inventory, gcp_compute (28.3)
│ │ ├── playbooks/ Convergence and read-back assertions (28.12)
│ │ ├── roles/os-baseline/ The CIS-derived host baseline (28.12)
│ │ └── requirements.yml Collections, pinned
│ ├── kubernetes/ Pod Security, NetworkPolicy, Workload Identity
│ ├── policies/ Org policy, Binary Authorization, IAM deny
│ ├── cicd/ Cloud Build and GitHub Actions with WIF
│ └── scripts/ Read-back verification
└── docs/
├── errata.md
├── compatibility.md
└── migrations.md
Chapters reference code by path, and the path they print is the one in the repository:
code/tf/network/, code/ansible/roles/os-baseline/, and so on. A chapter that cites a path is the
authoritative statement of where that code lives.
The child modules configure no provider and no backend, because the root module owns both
(§26.5). code/tf/environments/prod/ is that root module: it supplies the backend, the provider,
and the composition, and it is the thing you actually run. Its terraform.tfvars.example carries
the reference estate's identifiers and address plan, all of which you replace.
Appendix A's seven estate layouts are designs, not configurations. They differ in folder structure and scale rather than in resource definitions, and the modules here are the pieces each of them is assembled from.
Versioning §
The book and repository should be versioned independently but linked explicitly.
For example:
Book edition: 1st Edition
Book version: 1.0
Repository tag: book-1.0
A later corrected printing might use:
Book version: 1.1
Repository tag: book-1.1
Readers should be able to retrieve the exact code associated with the copy of the book they are reading.
Main branch §
The default branch may contain fixes and updates newer than the printed book.
That is useful, but it also means the default branch is not necessarily identical to a particular printing.
For exact reproduction, use the repository tag associated with the book version.
Example safety §
Examples may create billable GCP resources.
Before applying an example:
- verify the active account;
- verify the active project;
- review the plan;
- understand what the configuration creates;
- know how to destroy it;
- confirm whether any data is important;
- check estimated cost where relevant.
Do not test destructive infrastructure examples in a production project.
Corrections §
If a printed example is wrong, the repository is the preferred place to publish the correction because readers can obtain the fixed configuration immediately instead of waiting for another printing.
Confirmed errata should be listed in:
docs/errata.md
with the affected edition, chapter, page or section, correction, and date.