chore: improve local deploy instructions (#901)

* first draft updated docs

* Apply suggestions from code review

Co-authored-by: Bharath KKB <[email protected]>

Author: maxi-cit

0-bootstrap/README.md

@@ -125,7 +125,14 @@ your current Jenkins manager (controller) environment.
 
 ## Deploying with Cloud Build
 
-1. Go to the `0-bootstrap` folder.
+1. Clone [terraform-example-foundation](https://github.com/terraform-google-modules/terraform-example-foundation) into your local environment and navigate to the `0-bootstrap` folder.
+
+   ```bash
+   git clone https://github.com/terraform-google-modules/terraform-example-foundation.git
+
+   cd terraform-example-foundation/0-bootstrap
+   ```
+
 1. Rename `terraform.example.tfvars` to `terraform.tfvars` and update the file with values from your environment:
 
    ```bash

1-org/README.md

@@ -109,9 +109,9 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
 
 ### Deploying with Cloud Build
 
-1. Clone the `gcp-org` repo based on the Terraform output from the previous step.
-Clone the repo at the same level of the `terraform-example-foundation` folder, the next instructions assume that layout.
-Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to see the project again.
+1. Clone the `gcp-org` repo based on the Terraform output from the `0-bootstrap` step.
+Clone the repo at the same level of the `terraform-example-foundation` folder, the following instructions assume this layout.
+Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to get the Cloud Build Project ID.
 
    ```bash
    export CLOUD_BUILD_PROJECT_ID=$(terraform -chdir="terraform-example-foundation/0-bootstrap/" output -raw cloudbuild_project_id)
@@ -120,8 +120,9 @@ Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to see
    gcloud source repos clone gcp-org --project=${CLOUD_BUILD_PROJECT_ID}
    ```
 
-   - The message `warning: You appear to have cloned an empty repository.` is
+   **Note:** The message `warning: You appear to have cloned an empty repository.` is
    normal and can be ignored.
+
 1. Navigate into the repo, change to a non-production branch and copy contents of foundation to new repo.
    All subsequent steps assume you are running them from the `gcp-org` directory.
    If you run them from another directory, adjust your copy paths accordingly.
@@ -207,10 +208,11 @@ See `0-bootstrap` [README-Jenkins.md](../0-bootstrap/README-Jenkins.md#deploying
 
 ### Running Terraform locally
 
-1. Change into `1-org` folder, copy the Terraform wrapper script and ensure it can be executed.
+1. The next instructions assume that you are at the same level of the `terraform-example-foundation` folder.
+Change into `1-org` folder, copy the Terraform wrapper script and ensure it can be executed.
 
    ```bash
-   cd 1-org
+   cd terraform-example-foundation/1-org
    cp ../build/tf-wrapper.sh .
    chmod 755 ./tf-wrapper.sh
    ```

2-environments/README.md

@@ -75,7 +75,9 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
 
 ### Deploying with Cloud Build
 
-1. Clone repo.
+1. Clone the `gcp-environments` repo based on the Terraform output from the `0-bootstrap` step.
+Clone the repo at the same level of the `terraform-example-foundation` folder, the following instructions assume this layout.
+Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to get the Cloud Build Project ID.
 
    ```bash
    export CLOUD_BUILD_PROJECT_ID=$(terraform -chdir="terraform-example-foundation/0-bootstrap/" output -raw cloudbuild_project_id)
@@ -162,10 +164,10 @@ See `0-bootstrap` [README-Jenkins.md](../0-bootstrap/README-Jenkins.md#deploying
 
 ### Run Terraform locally
 
-1. Change into `2-environments` folder, copy the Terraform wrapper script and ensure it can be executed.
+1. The next instructions assume that you are at the same level of the `terraform-example-foundation` folder. Change into `2-environments` folder, copy the Terraform wrapper script and ensure it can be executed.
 
    ```bash
-   cd 2-environments
+   cd terraform-example-foundation/2-environments
    cp ../build/tf-wrapper.sh .
    chmod 755 ./tf-wrapper.sh
    ```

3-networks-dual-svpc/README.md

@@ -134,7 +134,9 @@ If you are not able to use Dedicated or Partner Interconnect, you can also use a
 
 ### Deploying with Cloud Build
 
-1. Clone repo.
+1. Clone the `gcp-networks` repo based on the Terraform output from the `0-bootstrap` step.
+Clone the repo at the same level of the `terraform-example-foundation` folder, the following instructions assume this layout.
+Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to get the Cloud Build Project ID.
 
    ```bash
    export CLOUD_BUILD_PROJECT_ID=$(terraform -chdir="terraform-example-foundation/0-bootstrap/" output -raw cloudbuild_project_id)
@@ -267,10 +269,10 @@ See `0-bootstrap` [README-Jenkins.md](../0-bootstrap/README-Jenkins.md#deploying
 
 ### Run Terraform locally
 
-1. Change into `3-networks-dual-svpc` folder, copy the Terraform wrapper script and ensure it can be executed.
+1. The next instructions assume that you are at the same level of the `terraform-example-foundation` folder. Change into `3-networks-dual-svpc` folder, copy the Terraform wrapper script and ensure it can be executed.
 
    ```bash
-   cd 3-networks-dual-svpc
+   cd terraform-example-foundation/3-networks-dual-svpc
    cp ../build/tf-wrapper.sh .
    chmod 755 ./tf-wrapper.sh
    ```

3-networks-hub-and-spoke/README.md

@@ -143,7 +143,9 @@ If you are not able to use Dedicated or Partner Interconnect, you can also use a
 
 ### Deploying with Cloud Build
 
-1. Clone repo.
+1. Clone the `gcp-networks` repo based on the Terraform output from the `0-bootstrap` step.
+Clone the repo at the same level of the `terraform-example-foundation` folder, the following instructions assume this layout.
+Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to get the Cloud Build Project ID.
 
    ```bash
    export CLOUD_BUILD_PROJECT_ID=$(terraform -chdir="terraform-example-foundation/0-bootstrap/" output -raw cloudbuild_project_id)
@@ -276,10 +278,10 @@ See `0-bootstrap` [README-Jenkins.md](../0-bootstrap/README-Jenkins.md#deploying
 
 ### Run Terraform locally
 
-1. Change into `3-networks-hub-and-spoke` folder, copy the Terraform wrapper script and ensure it can be executed.
+1. The next instructions assume that you are at the same level of the `terraform-example-foundation` folder. Change into `3-networks-hub-and-spoke` folder, copy the Terraform wrapper script and ensure it can be executed.
 
    ```bash
-   cd 3-networks-hub-and-spoke
+   cd terraform-example-foundation/3-networks-hub-and-spoke
    cp ../build/tf-wrapper.sh .
    chmod 755 ./tf-wrapper.sh
    ```

4-projects/README.md

@@ -87,7 +87,9 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
 
 ### Deploying with Cloud Build
 
-1. Clone repo.
+1. Clone the `gcp-projects` repo based on the Terraform output from the `0-bootstrap` step.
+Clone the repo at the same level of the `terraform-example-foundation` folder, the following instructions assume this layout.
+Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to get the Cloud Build Project ID.
 
    ```bash
    export CLOUD_BUILD_PROJECT_ID=$(terraform -chdir="terraform-example-foundation/0-bootstrap/" output -raw cloudbuild_project_id)
@@ -216,10 +218,10 @@ See `0-bootstrap` [README-Jenkins.md](../0-bootstrap/README-Jenkins.md#deploying
 
 ### Run Terraform locally
 
-1. Change into `4-projects` folder, copy the Terraform wrapper script and ensure it can be executed.
+1. The next instructions assume that you are at the same level of the `terraform-example-foundation` folder. Change into `4-projects` folder, copy the Terraform wrapper script and ensure it can be executed.
 
    ```bash
-   cd 4-projects
+   cd terraform-example-foundation/4-projects
    cp ../build/tf-wrapper.sh .
    chmod 755 ./tf-wrapper.sh
    ```
@@ -250,7 +252,7 @@ When using Cloud Build or Jenkins as your CI/CD tool each environment correspond
 
 To use the `validate` option of the `tf-wrapper.sh` script, please follow the [instructions](https://cloud.google.com/docs/terraform/policy-validation/validate-policies#install) to install the terraform-tools component.
 
-1. Use `terraform output` to get the Cloud Build project ID and the environment step Terraform Service Account from 0-bootstrap output. An environment variable `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT` will be set using the Terraform Service Account to enable impersonation.
+1. Use `terraform output` to get the Cloud Build Project ID and the environment step Terraform Service Account from 0-bootstrap output. An environment variable `GOOGLE_IMPERSONATE_SERVICE_ACCOUNT` will be set using the Terraform Service Account to enable impersonation.
 
    ```bash
    export CLOUD_BUILD_PROJECT_ID=$(terraform -chdir="../0-bootstrap/" output -raw cloudbuild_project_id)

5-app-infra/README.md

@@ -80,7 +80,9 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
 
 ### Deploying with Cloud Build
 
-1. Clone the policies repo. **Note:** This repo has the same name as the repo created in step 1-org, to prevent a collision the command below will clone it in folder gcp-policies-app-infra.
+1. Clone the `gcp-policies` repo based on the Terraform output from the `0-bootstrap` step.
+Clone the repo at the same level of the `terraform-example-foundation` folder, the following instructions assume this layout.
+Run `terraform output cloudbuild_project_id` in the `0-bootstrap` folder to get the Cloud Build Project ID.
 
    ```bash
    export INFRA_PIPELINE_PROJECT_ID=$(terraform -chdir="gcp-projects/business_unit_1/shared/" output -raw cloudbuild_project_id)
@@ -89,6 +91,8 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
    gcloud source repos clone gcp-policies gcp-policies-app-infra --project=${INFRA_PIPELINE_PROJECT_ID}
    ```
 
+   **Note:** `gcp-policies` repo has the same name as the repo created in step `1-org`. In order to prevent a collision, the previous command will clone this repo in the folder `gcp-policies-app-infra`.
+
 1. Navigate into the repo and copy contents of policy-library to new repo. All subsequent steps assume you are running them
    from the gcp-policies-app-infra directory. If you run them from another directory,
    adjust your copy paths accordingly.
@@ -190,10 +194,10 @@ commands. The `-T` flag is needed for Linux, but causes problems for MacOS.
 
 ### Run Terraform locally
 
-1. Change into `5-app-infra` folder, copy the Terraform wrapper script and ensure it can be executed.
+1. The next instructions assume that you are at the same level of the `terraform-example-foundation` folder. Change into `5-app-infra` folder, copy the Terraform wrapper script and ensure it can be executed.
 
    ```bash
-   cd 5-app-infra
+   cd terraform-example-foundation/5-app-infra
    cp ../build/tf-wrapper.sh .
    chmod 755 ./tf-wrapper.sh
    ```