fix: update Jenkins documentation (terraform-google-modules#159)

0-bootstrap/main.tf

@@ -153,7 +153,7 @@ module "cloudbuild_bootstrap" {
 //  terraform_sa_name                       = module.seed_bootstrap.terraform_sa_name
 //  terraform_state_bucket                  = module.seed_bootstrap.gcs_bucket_tfstate
 //  sa_enable_impersonation                 = true
-//  jenkins_master_ip_addresses             = var.jenkins_master_ip_addresses
+//  jenkins_master_subnetwork_cidr_range    = var.jenkins_master_subnetwork_cidr_range
 //  jenkins_agent_gce_subnetwork_cidr_range = var.jenkins_agent_gce_subnetwork_cidr_range
 //  jenkins_agent_gce_private_ip_address    = var.jenkins_agent_gce_private_ip_address
 //  nat_bgp_asn                             = var.nat_bgp_asn

0-bootstrap/modules/jenkins-agent/README.md

@@ -6,7 +6,7 @@ The objective of this module is to deploy a Google Cloud Platform project `prj-c
     - VPC to connect the Jenkins GCE Instance to
     - FW rules to allow communication over port 22
     - VPN connection with on-prem (or where ever your Jenkins Master is located)
-    - Custom service account `[email protected]` for the GCE instance. This service account is granted the access to generate tokens on the provided Terraform custom service account
+    - Custom service account `sa-jenkins-agent-gce@prj-cicd-xxxx.iam.gserviceaccount.com` for the GCE instance. This service account is granted the access to generate tokens on the provided Terraform custom service account
 Please note this module does not include an option to create a Jenkins Master. To deploy a Jenkins Master, you should follow one of the available user guides about [Jenkins in GCP](https://cloud.google.com/jenkins).
 
 **If you don't have a Jenkins implementation and don't want one**, then we recommend you to [use the Cloud Build module](../../README.md) instead.
@@ -27,9 +27,9 @@ module "jenkins_bootstrap" {
   terraform_sa_name                       = "<SERVICE_ACCOUNT_NAME>" # normally module.seed_bootstrap.terraform_sa_name
   terraform_state_bucket                  = "<GCS_STATE_BUCKET_NAME>" # normally module.seed_bootstrap.gcs_bucket_tfstate
   sa_enable_impersonation                 = true
-  jenkins_master_ip_addresses             = ["10.1.0.6/32"]
-  jenkins_agent_gce_subnetwork_cidr_range = "10.2.0.0/24"
-  jenkins_agent_gce_private_ip_address    = "10.2.0.6"
+  jenkins_master_subnetwork_cidr_range    = ["10.1.0.6/32"]
+  jenkins_agent_gce_subnetwork_cidr_range = "172.16.1.0/24"
+  jenkins_agent_gce_private_ip_address    = "172.16.1.6"
   nat_bgp_asn                             = "BGP_ASN_FOR_NAT_CLOUD_ROUTE"
   jenkins_agent_sa_email                  = "jenkins-agent-gce" # service_account_prefix will be added
   jenkins_agent_gce_ssh_pub_key           = var.jenkins_agent_gce_ssh_pub_key
@@ -63,7 +63,7 @@ module "jenkins_bootstrap" {
 | jenkins\_agent\_gce\_ssh\_user | Jenkins Agent GCE Instance SSH username. | string | `"jenkins"` | no |
 | jenkins\_agent\_gce\_subnetwork\_cidr\_range | The subnetwork to which the Jenkins Agent will be connected to (in CIDR range 0.0.0.0/0) | string | n/a | yes |
 | jenkins\_agent\_sa\_email | Email for Jenkins Agent service account. | string | `"jenkins-agent-gce"` | no |
-| jenkins\_master\_ip\_addresses | A list of CIDR IP ranges of the Jenkins Master in the form ['0.0.0.0/0']. Usually only one IP in the form '0.0.0.0/32'. Needed to create a FW rule that allows communication with the Jenkins Agent GCE Instance. | list(string) | n/a | yes |
+| jenkins\_master\_subnetwork\_cidr\_range | A list of CIDR IP ranges of the Jenkins Master in the form ['0.0.0.0/0']. Usually only one IP in the form '0.0.0.0/32'. Needed to create a FW rule that allows communication with the Jenkins Agent GCE Instance. | list(string) | n/a | yes |
 | nat\_bgp\_asn | BGP ASN for NAT cloud route. This is needed to allow the Jenkins Agent to download packages and updates from the internet without having an external IP address. | number | n/a | yes |
 | org\_id | GCP Organization ID | string | n/a | yes |
 | project\_labels | Labels to apply to the project. | map(string) | `<map>` | no |

0-bootstrap/modules/jenkins-agent/main.tf

@@ -112,7 +112,7 @@ resource "google_compute_firewall" "fw_allow_ssh_into_jenkins_agent" {
   name           = "fw-${google_compute_network.jenkins_agents.name}-1000-i-a-all-all-tcp-22"
   description    = "Allow the Jenkins Master (Client) to connect to the Jenkins Agents (Servers) using SSH."
   network        = google_compute_network.jenkins_agents.name
-  source_ranges  = var.jenkins_master_ip_addresses
+  source_ranges  = var.jenkins_master_subnetwork_cidr_range
   target_tags    = local.jenkins_gce_fw_tags
   priority       = 1000
   enable_logging = true

0-bootstrap/modules/jenkins-agent/variables.tf

@@ -81,7 +81,7 @@ variable "jenkins_agent_sa_email" {
   default     = "jenkins-agent-gce"
 }
 
-variable "jenkins_master_ip_addresses" {
+variable "jenkins_master_subnetwork_cidr_range" {
   description = "A list of CIDR IP ranges of the Jenkins Master in the form ['0.0.0.0/0']. Usually only one IP in the form '0.0.0.0/32'. Needed to create a FW rule that allows communication with the Jenkins Agent GCE Instance."
   type        = list(string)
 }

0-bootstrap/terraform.example.tfvars

@@ -31,14 +31,14 @@ default_region = "australia-southeast1"
     Specific to jenkins_bootstrap module
    ---------------------------------------- */
 // Un-comment the jenkins_bootstrap module and its outputs if you want to use Jenkins instead of Cloud Build
-//jenkins_agent_gce_subnetwork_cidr_range = "10.2.0.0/24"
+//jenkins_agent_gce_subnetwork_cidr_range = "172.16.1.0/24"
 //
-//jenkins_agent_gce_private_ip_address = "10.2.0.6"
+//jenkins_agent_gce_private_ip_address = "172.16.1.6"
 //
 //jenkins_agent_gce_ssh_pub_key = "ssh-rsa [KEY_VALUE] [USERNAME]"
 //
 //jenkins_agent_sa_email = "jenkins-agent-gce" # service_account_prefix will be added
 //
-//jenkins_master_ip_addresses = ["10.1.0.6/32"]
+//jenkins_master_subnetwork_cidr_range = ["10.1.0.6/32"]
 //
 //nat_bgp_asn = "64514"

0-bootstrap/variables.tf

@@ -83,7 +83,7 @@ variable "skip_gcloud_download" {
 //  default     = "jenkins-agent-gce"
 //}
 //
-//variable "jenkins_master_ip_addresses" {
+//variable "jenkins_master_subnetwork_cidr_range" {
 //  description = "A list of CIDR IP ranges of the Jenkins Master in the form ['0.0.0.0/0']. Usually only one IP in the form '0.0.0.0/32'. Needed to create a FW rule that allows communication with the Jenkins Agent GCE Instance."
 //  type        = list(string)
 //}

1-org/README.md

@@ -20,51 +20,38 @@ You can choose not to enable the Data Access logs by setting variable `data_acce
 1. Navigate into the repo `cd gcp-org` and change to a non prod branch `git checkout -b plan`
 1. Copy contents of foundation to new repo `cp -RT ../terraform-example-foundation/1-org/ .` (modify accordingly based on your current directory).
 1. Copy cloud build configuration files for terraform `cp ../terraform-example-foundation/build/cloudbuild-tf-* . ` (modify accordingly based on your current directory).
-1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . ` (modify accordingly based on your current directory).
+1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . `1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . ` to the root of your new repository  (modify accordingly based on your current directory). to the root of your new repository (modify accordingly based on your current directory).
 1. Ensure wrapper script can be executed `chmod 755 ./tf-wrapper.sh`.
-1. Rename terraform.example.tfvars to terraform.tfvars and update the file with values from your environment and bootstrap (you can re-run `terraform output` in the 0-bootstrap directory to find these values). Make sure that `default_region` is set to a valid [BigQuery dataset region](https://cloud.google.com/bigquery/docs/locations).
+1. Rename `terraform.example.tfvars` to `terraform.tfvars` and update the file with values from your environment and bootstrap (you can re-run `terraform output` in the 0-bootstrap directory to find these values). Make sure that `default_region` is set to a valid [BigQuery dataset region](https://cloud.google.com/bigquery/docs/locations).
 1. Commit changes with `git add .` and `git commit -m 'Your message'`
 1. Push your plan branch to trigger a plan `git push --set-upstream origin plan` (the branch `plan` is not a special one. Any branch which name is different from `dev`, `nonprod` or `prod` will trigger a terraform plan).
     1. Review the plan output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 1. Merge changes to prod branch with `git checkout -b prod` and `git push origin prod`
     1. Review the apply output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 
-
 ### Setup to run via Jenkins
-1. Clone repo you created manually in Bootstrap: `git clone <YOUR_NEW_REPO-1-org>`
+1. Clone the repo you created manually in bootstrap: `git clone <YOUR_NEW_REPO-1-org>`
 1. Navigate into the repo `cd YOUR_NEW_REPO_CLONE-1-org` and change to a non prod branch `git checkout -b plan`
-1. Copy contents of foundation to new repo `cp -R ../terraform-example-foundation/1-org/* .` (modify accordingly based on your current directory).
-1. Copy the `Jenkinsfile` to the root of your new repository and replace the `_TF_SA_EMAIL` with the name of your Terraform Service Account in the `seed` project. (modify accordingly based on your current directory):
-   ```
-   cp ../terraform-example-foundation/build/Jenkinsfile .
-   sed -i 's/_TF_SA_EMAIL/TF_SERVICE_ACCOUNT_EMAIL/' Jenkinsfile
-   ```
-   **If using MacOS:**
-    ```
-    cp ../terraform-example-foundation/build/Jenkinsfile .
-    sed -i '.bak' 's/_TF_SA_EMAIL/TF_SERVICE_ACCOUNT_EMAIL/' Jenkinsfile
-    rm Jenkinsfile.bak
-    ```
-1. Copy the `tf-wrapper.sh` configuration file to the root of your new repository (modify accordingly based on your current directory):
+1. Copy contents of foundation to new repo `cp -RT ../terraform-example-foundation/1-org/ .` (modify accordingly based on your current directory).
+1. Copy the Jenkinsfile script `cp ../terraform-example-foundation/build/Jenkinsfile .` to the root of your new repository (modify accordingly based on your current directory).
+1. Update the variables located in the `environment {}` section of the `Jenkinsfile` with values from your environment:
     ```
-    cp ../terraform-example-foundation/build/tf-wrapper.sh .
+    _POLICY_REPO (optional)
+    _TF_SA_EMAIL
+    _STATE_BUCKET_NAME
     ```
+1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . `1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . ` to the root of your new repository  (modify accordingly based on your current directory). to the root of your new repository (modify accordingly based on your current directory).
 1. Ensure wrapper script can be executed `chmod 755 ./tf-wrapper.sh`.
-1. Rename `terraform.example.tfvars` to `terraform.tfvars` and update the file with values from your environment. (you can re-run `terraform output` in the 0-bootstrap directory to find these values). Make sure that `default_region` is set to a valid [BigQuery dataset region](https://cloud.google.com/bigquery/docs/locations).
-    ```
-    # Rename file
-    mv envs/shared/terraform.example.tfvars envs/shared/terraform.tfvars
-    # Edit the file to provide the necessary values
-    vi envs/shared/terraform.tfvars
-    ```
-
+1. Rename `terraform.example.tfvars` to `terraform.tfvars` and update the file with values from your environment and bootstrap (you can re-run `terraform output` in the 0-bootstrap directory to find these values). Make sure that `default_region` is set to a valid [BigQuery dataset region](https://cloud.google.com/bigquery/docs/locations).
 1. Commit changes with `git add .` and `git commit -m 'Your message'`
 1. Push your plan branch `git push --set-upstream origin plan`. The branch `plan` is not a special one. Any branch which name is different from `dev`, `nonprod` or `prod` will trigger a terraform plan.
-    - Assuming you configured an automatic trigger in your Jenkins Master (see [Jenkins sub-module README](../../../0-bootstrap/modules/jenkins-agent)), this will trigger a plan. You can also trigger a Jenkins job manually. Given the many options to do this in Jenkins, it is out of the scope of this document see [Jenkins website](www.jenkins.io) for more details.
+    - Assuming you configured an automatic trigger in your Jenkins Master (see [Jenkins sub-module README](../0-bootstrap/modules/jenkins-agent)), this will trigger a plan. You can also trigger a Jenkins job manually. Given the many options to do this in Jenkins, it is out of the scope of this document see [Jenkins website](http://www.jenkins.io) for more details.
     1. Review the plan output in your Master's web UI.
 1. Merge changes to prod branch with `git checkout -b prod` and `git push origin prod`
     1. Review the apply output in your Master's web UI (You might want to use the option to "Scan Multibranch Pipeline Now" in your Jenkins Master UI).
 
+1. You can now move to the instructions in the step [2-environments](../2-environments/README.md).
+
 ### Run terraform locally
 1. Change into 1-org folder.
 1. Run `cp ../build/tf-wrapper.sh .`

2-environments/README.md

@@ -10,36 +10,51 @@ The purpose of this step is to set up dev, nonprod, and prod environments within
 1. Membership in the monitoring admins group for user running terraform
 
 ## Usage
-### Setup to run the automated pipelines
+
+### Setup to run via Cloud Build
 1. Clone repo `gcloud source repos clone gcp-environments --project=YOUR_CLOUD_BUILD_PROJECT_ID`
 1. Change freshly cloned repo and change to non master branch `git checkout -b plan`
 1. Copy contents of foundation to new repo `cp -RT ../terraform-example-foundation/2-environments/ .` (modify accordingly based on your current directory)
 1. Copy cloud build configuration files for terraform `cp ../terraform-example-foundation/build/cloudbuild-tf-* . ` (modify accordingly based on your current directory).
-1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . ` (modify accordingly based on your current directory)
+1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . `1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . ` to the root of your new repository  (modify accordingly based on your current directory). to the root of your new repository (modify accordingly based on your current directory).
 1. Ensure wrapper script can be executed `chmod 755 ./tf-wrapper.sh`.
-1. Rename terraform.example.tfvars to terraform.tfvars and update the file with values from your environment and bootstrap.
+1. Rename `terraform.example.tfvars` to `terraform.tfvars` and update the file with values from your environment and bootstrap (you can re-run `terraform output` in the 0-bootstrap directory to find these values).
 1. Commit changes with `git add .` and `git commit -m 'Your message'`
-
-#### If using Cloud Build
 1. Push your plan branch to trigger a plan for all environments `git push --set-upstream origin plan` (the branch `plan` is not a special one. Any branch which name is different from `dev`, `nonprod` or `prod` will trigger a terraform plan).
     1. Review the plan output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 1. Merge changes to dev with `git checkout -b dev` and `git push origin dev`
     1. Review the apply output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 1. Merge changes to nonprod with `git checkout -b nonprod` and `git push origin nonprod`
     1. Review the apply output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
-1. Merge changes to prod with `git checkout -b prod` and `git push origin prod`
+1. Merge changes to prod branch with `git checkout -b prod` and `git push origin prod`
     1. Review the apply output in your cloud build project https://console.cloud.google.com/cloud-build/builds?project=YOUR_CLOUD_BUILD_PROJECT_ID
 
-#### If using Jenkins
-1. Push your plan branch to trigger a plan for all environments `git push --set-upstream origin plan` (the branch `plan` is not a special one. Any branch which name is different from `dev`, `nonprod` or `prod` will trigger a terraform plan).
+### Setup to run via Jenkins
+1. Clone the repo you created manually in bootstrap: `git clone <YOUR_NEW_REPO-2-environments>`
+1. Navigate into the repo `cd YOUR_NEW_REPO_CLONE-2-environments` and change to a non prod branch `git checkout -b plan` (the branch `plan` is not a special one. Any branch which name is different from `dev`, `nonprod` or `prod` will trigger a terraform plan).
+1. Copy contents of foundation to new repo `cp -RT ../terraform-example-foundation/2-environments/ .` (modify accordingly based on your current directory).
+1. Copy the Jenkinsfile script `cp ../terraform-example-foundation/build/Jenkinsfile .` to the root of your new repository (modify accordingly based on your current directory).
+1. Update the variables located in the `environment {}` section of the `Jenkinsfile` with values from your environment:
+    ```
+    _POLICY_REPO (optional)
+    _TF_SA_EMAIL
+    _STATE_BUCKET_NAME
+    ```
+1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . `1. Copy terraform wrapper script `cp ../terraform-example-foundation/build/tf-wrapper.sh . ` to the root of your new repository  (modify accordingly based on your current directory). to the root of your new repository (modify accordingly based on your current directory).
+1. Ensure wrapper script can be executed `chmod 755 ./tf-wrapper.sh`.
+1. Rename `terraform.example.tfvars` to `terraform.tfvars` and update the file with values from your environment and bootstrap (you can re-run `terraform output` in the 0-bootstrap directory to find these values).
+1. Commit changes with `git add .` and `git commit -m 'Your message'`
+1. Push your plan branch `git push --set-upstream origin plan`. The branch `plan` is not a special one. Any branch which name is different from `dev`, `nonprod` or `prod` will trigger a terraform plan.
+    - Assuming you configured an automatic trigger in your Jenkins Master (see [Jenkins sub-module README](../0-bootstrap/modules/jenkins-agent)), this will trigger a plan. You can also trigger a Jenkins job manually. Given the many options to do this in Jenkins, it is out of the scope of this document see [Jenkins website](http://www.jenkins.io) for more details.
     1. Review the plan output in your Master's web UI.
 1. Merge changes to dev with `git checkout -b dev` and `git push origin dev`
-    1. Review the apply output in your Master's web UI.
+    1. Review the apply output in your Master's web UI (You might want to use the option to "Scan Multibranch Pipeline Now" in your Jenkins Master UI).
 1. Merge changes to nonprod with `git checkout -b nonprod` and `git push origin nonprod`
-    1. Review the apply output in your Master's web UI.
-1. Merge changes to prod with `git checkout -b prod` and `git push origin prod`
-    1. Review the apply output in your Master's web UI.
+    1. Review the apply output in your Master's web UI (You might want to use the option to "Scan Multibranch Pipeline Now" in your Jenkins Master UI).
+1. Merge changes to prod branch with `git checkout -b prod` and `git push origin prod`
+    1. Review the apply output in your Master's web UI (You might want to use the option to "Scan Multibranch Pipeline Now" in your Jenkins Master UI).
 
+1. You can now move to the instructions in the step [3-networks](../3-networks/README.md).
 
 ### Run terraform locally
 1. Change into 2-environments folder.