feat: add FAQ, Glossary & Troubleshooting docs (#466)

* initial verison of docs folder and files

* fix glossary link

* update glossary and troubleshooting

* add cross reference to troubleshooting

* Add item for IPv6 issue in Cloud Shell

* Apply suggestions from code review

Co-authored-by: Bharath KKB <bharathkrishnakb@gmail.com>

* make Troubleshooting a section under Prerequisites

* adjust common errors heading

* Add alternative to upgrade the terraform runner image version

* upgrade option is only valid for versions 0.14.x

Co-authored-by: Bharath KKB <bharathkrishnakb@gmail.com>

0-bootstrap/README.md

@@ -55,7 +55,7 @@ file.
 
 ## Purpose
 
-The purpose of this step is to bootstrap a Google Cloud organization, creating all the required resources & permissions to start using the Cloud Foundation Toolkit (CFT). This step also configures a CI/CD pipeline for foundations code in subsequent stages. The CI/CD pipeline can use either Cloud Build andCloud Source Repos or Jenkins and your own Git repos (which might live on-premises).
+The purpose of this step is to bootstrap a Google Cloud organization, creating all the required resources & permissions to start using the Cloud Foundation Toolkit (CFT). This step also configures a CI/CD pipeline for foundations code in subsequent stages. The CI/CD pipeline can use either Cloud Build and Cloud Source Repos or Jenkins and your own Git repos (which might live on-premises).
 
 ## Prerequisites
 
@@ -66,7 +66,7 @@ installed:
 - [Terraform](https://www.terraform.io/downloads.html) version 0.13.6.
 - An existing project which the user has access to be used by terraform-validator.
 
-Note: Make sure that you use the same version of Terraform throughout this
+**Note:** Make sure that you use the same version of Terraform throughout this
 series. Otherwise, you might experience Terraform state snapshot lock errors.
 
 Also make sure that you've done the following:
@@ -93,6 +93,10 @@ For more information about the permissions that are required and the resources
 that are created, see the organization bootstrap module
 [documentation.](https://github.com/terraform-google-modules/terraform-google-bootstrap)
 
+### Troubleshooting
+
+Please refer to [troubleshooting](../docs/TROUBLESHOOTING.md) if you run into issues during this step.
+
 ## Deploying with Jenkins
 
 If you are using the `jenkins_bootstrap` sub-module, see
@@ -144,7 +148,7 @@ ERROR: logging before flag.Parse: I0413 13:49:49.852290 6380 convert.go:183] unk
 
 These are warnings for resources that are not yet supported or not known by terraform-validator, these are not actual errors.
 
-**Note 2:** After the deploy, even if you did not receive the project quota error described in the first item of the [Troubleshooting](#troubleshooting) section, we recommend that your request 50 additional projects for the service account, `terraform_service_account`, created in this step.
+**Note 2:** After the deploy, even if you did not receive the project quota error described in the [Troubleshooting guide](../docs/TROUBLESHOOTING.md#project-quota-exceeded), we recommend that you request 50 additional projects for the service account, `terraform_service_account`, created in this step.
 
 ## Running Terraform locally
 
@@ -196,34 +200,3 @@ the following steps:
 | terraform\_validator\_policies\_repo | Cloud Source Repository created for terraform-validator policies. |
 
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
-
-## Troubleshooting
-
-When you run the examples in this repository, you might see the following errors
-during a Terraform `apply` command:
-
-
-- `Error code 8, message: The project cannot be created because you have exceeded
-   your allotted project quota`.
-
-  - This message means you have reached your [project creation
-     quota](https://support.google.com/cloud/answer/6330231). In this case, you can
-    use the
-    [Request Project Quota Increase](https://support.google.com/code/contact/project_quota_increase)
-    form to request a quota increase. In the support form, for **Email addresses
-    that will be used to create projects**, use the `terraform_sa_email` address
-    that's created in the organization bootstrap module. If you see other quota
-    errors, see the [Quota documentation](https://cloud.google.com/docs/quota).
-
-- `Error: Error when reading or editing Organization Not Found : <organization-id>: googleapi: Error 403: The caller does not have permission, forbidden`.
-  - Check that your user have [Organization Admin](https://cloud.google.com/iam/docs/understanding-roles#resource-manager-roles) predefined role at the Organization level.
-  -  If this is the case, try the following:
-      ```
-      gcloud auth application-default login
-      gcloud auth list # <- confirm that correct account has a star next to it
-      ```
-  - Re-run `terraform` after.
-
-- `Error: Error setting billing account "XXXXXX-XXXXXX-XXXXXX" for project "projects/some-project": googleapi: Error 400: Precondition check failed., failedPrecondition`. Most likely this is related to billing quota issue.
-  - To confirm this, try `gcloud alpha billing projects link projects/some-project --billing-account XXXXXX-XXXXXX-XXXXXX`.
-  - If output states `Cloud billing quota exceeded`, please request increase via [https://support.google.com/code/contact/billing_quota_increase](https://support.google.com/code/contact/billing_quota_increase).

1-org/README.md

@@ -63,9 +63,13 @@ The purpose of this step is to set up top-level shared folders, monitoring and n
 3. Membership in the security admins group for the user running Terraform.
 4. Security Command Center notifications require that you choose a Security Command Center tier and create and grant permissions for the Security Command Center service account as outlined in [Setting up Security Command Center](https://cloud.google.com/security-command-center/docs/quickstart-security-command-center)
 
-Note: Make sure that you use the same version of Terraform throughout this
+**Note:** Make sure that you use the same version of Terraform throughout this
 series, otherwise you might experience Terraform state snapshot lock errors.
 
+### Troubleshooting
+
+Please refer to [troubleshooting](../docs/TROUBLESHOOTING.md) if you run into issues during this step.
+
 ## Usage
 
 **Disclaimer:** This step enables [Data Access logs](https://cloud.google.com/logging/docs/audit#data-access) for all services in your organization.

2-environments/README.md

@@ -63,6 +63,10 @@ The purpose of this step is to setup development, non-production, and production
 1. Cloud Identity / Google Workspace group for monitoring admins.
 1. Membership in the monitoring admins group for user running Terraform.
 
+### Troubleshooting
+
+Please refer to [troubleshooting](../docs/TROUBLESHOOTING.md) if you run into issues during this step.
+
 ## Usage
 
 ### Deploying with Cloud Build

3-networks/README.md

@@ -64,7 +64,15 @@ The purpose of this step is to:
 1. 0-bootstrap executed successfully.
 1. 1-org executed successfully.
 1. 2-environments executed successfully.
-1. Obtain the value for the access_context_manager_policy_id variable. Can be obtained by running `gcloud access-context-manager policies list --organization YOUR_ORGANIZATION_ID --format="value(name)"`.
+1. Obtain the value for the access_context_manager_policy_id variable. Can be obtained by running
+
+```
+gcloud access-context-manager policies list --organization YOUR_ORGANIZATION_ID --format="value(name)"
+```
+
+### Troubleshooting
+
+Please refer to [troubleshooting](../docs/TROUBLESHOOTING.md) if you run into issues during this step.
 
 ## Usage
 

4-projects/README.md

@@ -75,9 +75,6 @@ This pipeline can be utilized for deploying resources in projects across develop
    gcloud access-context-manager perimeters list --policy ACCESS_CONTEXT_MANAGER_POLICY_ID --format="value(name)"
    ```
 
-**Troubleshooting:**
-If you do not have access to run the commands above and you are in the organization admins group, you can append `--impersonate-service-account=org-terraform@<SEED_PROJECT_ID>.iam.gserviceaccount.com` to run the command as the Terraform service account.
-
 **Note:** If you have more than one service perimeter for each environment, you can also get the values from the `restricted_service_perimeter_name` output from each of the`3-networks` environments.
 
 If you are using Cloud Build you can also search for the values in the outputs from the build logs:
@@ -101,6 +98,10 @@ gcloud builds log BUILD_ID \
 
 Change the `BRANCH_NAME` from `development` to `non-production` or `production` for the other two service perimeters.
 
+### Troubleshooting
+
+Please refer to [troubleshooting](../docs/TROUBLESHOOTING.md) if you run into issues during this step.
+
 ## Usage
 
 **Note:** You need to set variable `enable_hub_and_spoke` to `true` to be able to used the **Hub-and-Spoke** architecture detailed in the **Networking** section of the [google cloud security foundations guide](https://services.google.com/fh/files/misc/google-cloud-security-foundations-guide.pdf).

5-app-infra/README.md

@@ -72,6 +72,10 @@ This Compute Engine instance is created using the base network from step `3-netw
 1. 3-networks executed successfully.
 1. 4-projects executed successfully.
 
+### Troubleshooting
+
+Please refer to [troubleshooting](../docs/TROUBLESHOOTING.md) if you run into issues during this step.
+
 ## Usage
 
 ### Deploying with Cloud Build

docs/FAQ.md

@@ -0,0 +1,12 @@
+# Frequently Asked Questions
+
+## Why am I encountering a low quota with projects created via Terraform Example Foundation?
+
+When you deploy the Terraform Example Foundation with the Service Account created in step 0-bootstrap,
+the project quota will be based on the reputation of your service account rather than your user identity.
+In many cases, this quota is initially low.
+
+We recommend that your request 50 additional projects for the service account, `terraform_service_account`, created in step 0-bootstrap.
+You can use the [Request Project Quota Increase](https://support.google.com/code/contact/project_quota_increase) form to request the quota increase.
+In the support form, for **Email addresses that will be used to create projects**, use the `terraform_service_account` address that's created in the organization bootstrap module.
+If you see other quota errors, see the [Quota documentation](https://cloud.google.com/docs/quota).

docs/GLOSSARY.md

@@ -0,0 +1,26 @@
+# Glossary
+
+Defined terms in the documentation for Terraform Example Foundation are capitalized and have
+specific meaning within the domain of knowledge.
+
+## Terraform Service Account
+
+The email for 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 using service account impersonation.
+
+## 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.
+
+## Foundation Pipeline
+
+A project created in step 0-bootstrap to manage infrastructure **within the organization**.
+The pipeline can use **Cloud Build** or **Jenkins** depending or your context and Terraform is executed using the seed project service account.
+Also know as the CI/CD project.
+It is located under folder `bootstrap`.
+
+## App Infra Pipeline
+
+A project created in step 4-projects to host a Cloud Build pipeline configured to manage infrastructure **within projects**.
+A separate pipeline exists for each of the business units and it can be configured to use a service account that has limited permissions to deploy into certain projects created in 4-projects.
+They are located under folder `common`.