Skip to content

Commit 18d5fa0

Browse files
rjerremsrjerrems
authored
refactor: add additional docs to main README (#26)
1 parent 16fc46b commit 18d5fa0

File tree

1 file changed

+129
-7
lines changed

1 file changed

+129
-7
lines changed

‎README.md‎

Lines changed: 129 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,135 @@
11
# terraform-example-foundation
2-
Example repo showing how the CFT modules can be composed to build a foundation
2+
This is an example repo showing how the CFT Terraform modules can be composed to build a secure GCP foundation.
3+
The supplied structure and code is intended to form a starting point for building your own foundation with pragmatic defaults you can customize to meet your own requirements. Currently, the code leverages Google Cloud Build for deployment of the Terraform from steps 2 onward.
4+
Cloud Build has been chosen to allow teams to quickly get started without needing to deploy a CI/CD tool, although it is worth noting the code can easily be executed by your preferred tool.
35

4-
## Steps
5-
The repo contains several distinct terraform projects which are dependent on the preceeding steps.
6+
## Overview
7+
This repo contains several distinct Terraform projects each within their own directory that must be applied seperately, but in sequence.
8+
Each of these Terraform prjects are to be layered on top of each other, running in the following order.
69

7-
1. [bootstrap](./0-bootstrap/README.md)
8-
1. [org](./1-org/README.md)
9-
1. [networks](./2-networks/README.md)
10-
1. [projects](./3-projects/README.md)
10+
### 1. [bootstrap](./0-bootstrap/README.md)
11+
12+
This stage executes the [CFT Bootstrap module](https://github.com/terraform-google-modules/terraform-google-bootstrap) which bootstraps an existing GCP organization, creating all the required GCP resources & permissions to start using the Cloud Foundation Toolkit (CFT).
13+
This includes; projects, service accounts and a Terraform state bucket. After executing this step, you will have the following structure:
14+
15+
```
16+
example-organization/
17+
├── cft-cloudbuild
18+
└── cft-seed
19+
```
20+
21+
In addition, this step uses the optional Cloud Build submodule, which sets up Cloud Build and Cloud Source Repositories for each of the stages below.
22+
A simple trigger mechanism is configured, which runs a `terraform plan` for any non master branch and `terraform apply` when changes are merged to the master branch.
23+
Usage instructions are available in the bootstrap [README](./0-bootstrap/README.md).
24+
25+
### 2. [org](./1-org/README.md)
26+
27+
The purpose of this stage is to set up top level folders used to house projects which contain shared resources such as monitoring, networking, org level logging and also to set baseline security settings through organizational policy.
28+
This will create the following folder & project structure:
29+
30+
```
31+
example-organization
32+
└── common
33+
├── logs
34+
│   ├── org-audit-logs
35+
│   └── org-billing-logs
36+
├── monitoring
37+
│   ├── org-monitoring-nonprod
38+
│   └── org-monitoring-prod
39+
└── networking
40+
├── org-shared-vpc-nonprod
41+
└── org-shared-vpc-prod
42+
```
43+
#### Logs
44+
45+
Under the logs folder, two projects are created. One for organization wide audit logs and another for billing logs.
46+
In both cases the logs are collected into BigQuery datasets which can then be used general querying, dashboarding & reporting.
47+
For the various audit log types being captured in BigQuery, this is mirroring the standard [retention periods](https://cloud.google.com/logging/quotas#logs_retention_periods) for Cloud Logging, these settings can be adjusted according to your requirements.
48+
49+
For billing data, a BigQuery dataset is created with permissions attached however you will need to configure a billing export [manually](https://cloud.google.com/billing/docs/how-to/export-data-bigquery) as there is no easy way to automate this currently.
50+
51+
#### Monitoring
52+
53+
Under the monitoring folder, a project is created per environment (prod & nonprod) which is intended to be used as a [Cloud Monitoring workspace](https://cloud.google.com/monitoring/workspaces) for all projects in that environment.
54+
Please note that creating the [workspace and linking projects](https://cloud.google.com/monitoring/workspaces/create) can currently only be completed through the Cloud Console.
55+
If you have strong IAM requirements for these monitoring workspaces, it is worth considering creating these at a more granular level such as per business unit or per application.
56+
57+
#### Networking
58+
59+
Under the networking folder, a project is created per environment (prod & nonprod) which is intended to be used as a [Shared VPC Host project](https://cloud.google.com/vpc/docs/shared-vpc) for all projects in that environment.
60+
This stage only creates the projects and enables the correct APIs, the following networks stage creates the actual Shared VPC networks.
61+
62+
#### Organization policy
63+
64+
Finally, the this step also applies a number of baseline [Organizational Policies](https://cloud.google.com/resource-manager/docs/organization-policy/overview).
65+
It is important to understand what restrictions these policies are applying within your GCP organization, so please take the time to review and update these restrictions to meet your own requirements.
66+
A full list of policies is [available here](https://cloud.google.com/resource-manager/docs/organization-policy/org-policy-constraints).
67+
68+
Usage instructions are available for the org step in the [README](./1-org/README.md).
69+
70+
### 3. [networks](./2-networks/README.md)
71+
72+
This step focuses on creating a Shared VPC per environment (prod & nonprod) in a standard configuration with a reasonable security baseline. Currently this includes:
73+
74+
- Example subnets for prod & non-prod inclusive of secondary ranges for those that want to use GKE.
75+
- Default firewall rules created to allow remote access to VMs through IAP, without needing public IPs.
76+
- `allow-iap-ssh` and `allow-iap-rdp` network tags respectively
77+
- Default firewall rule created to allow for load balancing using `allow-lb` tag.
78+
- [Private service networking](https://cloud.google.com/vpc/docs/configure-private-services-access) configured to enable private Cloud SQL and Memorystore.
79+
- [private.googleapis.com](https://cloud.google.com/vpc/docs/configure-private-google-access#private-domains) configured for private access to googleapis.com and gcr.io. Route added for VIP so no internet access is required to access APIs.
80+
- Default routes to internet removed, with tag based route `egress-internet` required on VMs in order to reach the internet.
81+
- Cloud NAT configured for all subnets with logging and static outbound IPs.
82+
- Default Cloud DNS policy applied, with DNS logging and [inbound query forwarding](https://cloud.google.com/dns/docs/overview#dns-server-policy-in) turned on.
83+
84+
Usage instructions are available for the network step in the [README](./2-networks/README.md).
85+
86+
### 4. [projects](./3-projects/README.md)
87+
88+
This step, is focused on creating service projects in a standard configuration that are attached to the Shared VPC created in the previous step.
89+
Running this code as-is should generate a structure as shown below:
90+
91+
```
92+
example-organization/
93+
└── example-business-unit
94+
└── example-team
95+
├── nonprod
96+
│   └── sample-standard-nonprod
97+
└── prod
98+
├── sample-single-prod
99+
└── sample-standard-prod
100+
```
101+
The code in this step includes two options for creating projects.
102+
The first is the standard projects module which creates a project per environment and the second creates a standalone project for one environment.
103+
If relevant for your use case, there are also two optional submodules which can be used to create a subnet per project and a dedicated private DNS zone per project.
104+
105+
Usage instructions are available for the network step in the [README](./3-projects/README.md).
106+
107+
### Final view
108+
109+
Once all steps above have been executed your GCP organization should represent the structure shown below, with projects being the lowest nodes in the tree.
110+
111+
```
112+
example-organization/
113+
├── cft-cloudbuild
114+
├── cft-seed
115+
├── common
116+
│   ├── logs
117+
│   │   ├── org-audit-logs
118+
│   │   └── org-billing-logs
119+
│   ├── monitoring
120+
│   │   ├── org-monitoring-nonprod
121+
│   │   └── org-monitoring-prod
122+
│   └── networking
123+
│   ├── org-shared-vpc-nonprod
124+
│   └── org-shared-vpc-prod
125+
└── example-business-unit
126+
└── example-team
127+
├── nonprod
128+
│   └── sample-standard-nonprod
129+
└── prod
130+
├── sample-single-prod
131+
└── sample-standard-prod
132+
```
11133

12134
## Contributing
13135

0 commit comments

Comments
 (0)