chore: Update release 4.0 docs (#1072)

ERRATA.md

@@ -1,6 +1,13 @@
 # Errata Summary
 This is an overview of the delta between the example foundation repository and the [Google Cloud security foundations guide](https://services.google.com/fh/files/misc/google-cloud-security-foundations-guide.pdf), including code discrepancies and notes on future automation. This document will be updated as new code is merged.
 
+## 4.x [WIP]
+
+### Code Discrepancies
+
+#### Notes
+- The "Alerting on log-based metrics and performance metrics" described in Section "Architecture/Detective controls" will be integrated in a future release.
+
 ## 3.x [WIP]
 
 ### Code Discrepancies

docs/GLOSSARY.md

@@ -3,19 +3,19 @@
 Defined terms in the documentation for Terraform Example Foundation are capitalized and have
 specific meaning within the domain of knowledge.
 
-## Terraform Service Account
+## Terraform Service Accounts
 
-The email for the privileged service account created in the seed project of the step 0-bootstrap.
-This service account is used to run Terraform by Cloud Build and Jenkins. When using Jenkins, the service account of the Jenkins Agent uses impersonation over this Terraform Service Account.
+The email for the privileged service accounts created in the seed project of the step 0-bootstrap.
+This service accounts are used to run Terraform by Cloud Build and Jenkins. When using Jenkins, the service account of the Jenkins Agent uses impersonation over this Terraform Service Accounts. A Terraform service account is created for each one of the steps.
 
 ## Seed Project
 
-Seed Project created in the 0-bootstrap step. It is the project where the Terraform Service Account (`terraform_service_account`) is created and hosts the GCS bucket used to store Terraform state of each environment in subsequent phases.
+Seed Project created in the 0-bootstrap step. It is the project where the Terraform Service Accounts (`terraform_service_account`) are created and hosts the GCS bucket used to store Terraform state of each environment in subsequent phases.
 
 ## Foundation CI/CD Pipeline
 
 A project created in step 0-bootstrap to manage infrastructure **within the organization**.
-The pipeline can use either **Cloud Build** or **Jenkins** depending or your context and Terraform is executed using the seed project service account.
+The pipeline can use either **Cloud Build**, **Github Actions**, **GitLab pipeline**, **Terraform Cloud** or **Jenkins** depending on your context and Terraform is executed using the seed project service account.
 Also known as the CI/CD project.
 It is located under folder `bootstrap`.
 

docs/upgrading_to_v4.0.md

@@ -0,0 +1,32 @@
+# Upgrade Guidance
+Before moving forward with adopting components of v4, review the list of breaking changes below. You can find a complete list of features, bug fixes and other updates in the [Changelog](https://github.com/terraform-google-modules/terraform-example-foundation/blob/master/CHANGELOG.md).
+
+**Important:** There is no in-place upgrade path from v3 to v4.
+
+## Breaking Changes
+
+- The BigQuery log destination was removed from the centralized logging created in step 1-org and replaced with the Log bucket destination with support for Log Analytics enabled and associated a BigQuery dataset.
+- Customer-managed encryption keys (CMEK) were enabled for the Terraform state buckets create in 0-bootstrap.
+- The configuration of Budget Alerts for the projects was changed from alarm by **spent** value to alarm by **forecast** value
+- `compute.disableGuestAttributesAccess` organization policy was removed
+-  Cloud Platform Resource Hierarchy changes:
+  - Subfolders for business units were created in 4-projects step
+  - A new Network folder was created be used as parent by network projects:
+    - `prj-ENV-shared-base`
+    - `prj-ENV-shared-restricted`
+    - `prj-c-base-net-hub`
+    - `prj-c-restricted-net-hub`
+    - `prj-c-dns-hub`
+    - `prj-c-interconnect`
+- Network Refactoring
+  - Network projects are now created under a new folder `network`
+  - VPC firewall rules (`google_compute_firewall`) resources were replaced with Compute Network firewall policy (`google_compute_network_firewall_policy`) resources
+
+## Integrating New Features
+
+There is no direct path for upgrading from v3 to v4 as this may result in resources getting deleted or recreated.
+
+In case you require to integrate some of the v4's features, we recommend to review the documentation regarding the feature you are interested in and use v4's code as a guidance for its implementation. We also recommend to review the output from `terraform plan` for any destructive operations before applying the updates.
+
+**Note:** You must verify that you are using the correct version for `terraform` and `gcloud`.
+You can check these and other additional requirements using this [validate script](https://github.com/terraform-google-modules/terraform-example-foundation/blob/master/scripts/validate-requirements.sh).