docs: updates to doc based on reviews (#5)

* updates to doc

Signed-off-by: Adam Geiger <[email protected]>

* additional updates to doc

Signed-off-by: Adam Geiger <[email protected]>

---------

Signed-off-by: Adam Geiger <[email protected]>

Author: argeiger

Diff for: docs/index.html

@@ -55,7 +55,7 @@
         loadSidebar: "sidebar.md",
         auto2top: true,
         maxLevel: 3,
-        subMaxLevel: 2,
+        subMaxLevel: 0,
 
         // 5. docsify-themeable
         themeable: {
@@ -66,6 +66,10 @@
         requestHeaders: {
           'cache-control': 'max-age=0',
         },
+        pagination: {
+          crossChapter: true,
+          crossChapterText: true,
+        },
       };
     </script>
 

Diff for: docs/part1/00-objectives.md

@@ -2,8 +2,7 @@
 
 In lab 1, you provision a secure VPC-based topology that is aligned with the **VSI on VPC landing zone** deployable architecture, as shown in the following diagram.
 
-![VSI on VPC landing zone architecture diagram](https://raw.githubusercontent.com/terraform-ibm-modules/terraform-ibm-landing-zone/main/reference-architectures/vsi-vsi.drawio.svg 'size=60%' )
-
+<img src="https://raw.githubusercontent.com/terraform-ibm-modules/terraform-ibm-landing-zone/main/reference-architectures/vsi-vsi.drawio.svg" width="75%" heigh="75%"/>
 
 After you provision the VPC, you customize the deployed infrastructure in the following ways:
 - Expose one of the VSI in the management VPC to act as a "jump box" for operator access. This jump box is the entry point for operators to access the VSIs in the workload VPC.

Diff for: docs/part1/10-project.md

@@ -63,6 +63,7 @@
 1. While you wait for the deployment to finish, consider doing these things:
 
     - Look at the deployment logs:
+        - The Terraform init step initializes the Terraform configuration files for use with Terraform.
         - The Terraform plan steps show the list of resources that are going to be created.
         - The Terraform apply steps shows the resources that are being created.
 

Diff for: docs/part1/20-operator-access.md

@@ -27,24 +27,25 @@ Complete the following steps to enable public SSH access to one of the VSI in th
 
     ![Floating IP address](../images/part-1/20-floating-ip.png)
 
-5. In the [Security Groups for VPC](https://cloud.ibm.com/vpc-ext/network/securityGroups), click the one labeled `<your_initials>-management`.
-6. Go to the Rules section and allow port 22 for inbound by clicking **Create** in the _Inbound rules_ section.
+5. Click **Save**.
+6. In the [Security Groups for VPC](https://cloud.ibm.com/vpc-ext/network/securityGroups), click the one labeled `<your_initials>-management`.
+7. Go to the Rules section and allow port 22 for SSH inbound access by clicking **Create** in the _Inbound rules_ section.
 
     :information_source: **Tip**: Security groups are stateful so you don’t need to add a corresponding outbound rule.
 
     ![Allow SSH in Security group](../images/part-1/20-ssh-sg.png)
 
-7. Click **Create**.
-8. In the [Access control lists for VPC](https://cloud.ibm.com/vpc-ext/network/acl), click the one labeled `<your_initials>-management-acl`.
-9. Create the following ACL inbound rule:
+8. Click **Create**.
+9. In the [Access control lists for VPC](https://cloud.ibm.com/vpc-ext/network/acl), click the one labeled `<your_initials>-management-acl`.
+10. Create the following ACL inbound rule for SSH access:
 
     ![SSH ACL Inbound rule](../images/part-1/20-ssh-acl-inbound.png)
 
-10. Create the following ACL outbound rule:
+11. Create the following ACL outbound rule for SSH access:
 
     ![SSH ACL Outbound rule](../images/part-1/20-ssh-acl-outbound.png)
 
-11. You can now access the 'jump-box' through the public floating IP address that you provisioned earlier. On your computer, issue the following command from the terminal or command window:
+12. You can now access the 'jump-box' through the public floating IP address that you provisioned earlier. On your computer, issue the following command from the terminal or command window:
 
     ```sh
     ssh -i ./lab-key root@<Floating IP of Virtual server instance>

Diff for: docs/part2/10-customizing.md

@@ -1,6 +1,6 @@
 # Customizing the landing zone topology
 
-## Two ways to customize
+## Ways to customize
 
 The landing zone module is designed to enable both lightweight and deep customizations of the VPC topology, including all the services that are deployed to make the VPC topology compliant.
 
@@ -9,9 +9,9 @@ In a nutshell, you can customize the topology in two ways:
 - By using Terraform input variables.
 
     The module accepts more than 70 input variables that you can use to tweak the VPC topology. Consider the input variables as "knobs" that you can turn to adjust the topology.
-- By passing a JSON string value to the `override.json` variable.
+- By passing a JSON string value to the file `override.json` or through the module variable `override_json_string`.
 
-    The override file enables deeper and broader types of customizations. By using a JSON file, you can fully customize aspects of the topology beyond what you can achieve with Terraform input variables.
+    The override enables deeper and broader types of customizations. By using a JSON definition, you can fully customize aspects of the topology beyond what you can achieve with Terraform input variables.
 
 ## Defining our custom topology with a JSON definition
 

Diff for: docs/part2/20-custom-module.md

@@ -19,11 +19,11 @@ You can find the code for this step in the [custom-slz](https://github.com/IBM/i
     Notice these two settings in the `main.tf` file:
 
     - The `override_json_string` input variable takes the full JSON definition. In this example, the JSON that is passed to the module through the `templatefile` function first to 'inject' the prefix. That process is done to ensure uniqueness of the resource group names in the account, as mentioned in the first item.
-    - The `source` is set to the standard VSI pattern and points to the version 4.4.7 (the most recent version at the time that this lab was written).
+    - The `source` is set to the standard VSI pattern and points to the version 4.5.4 (the most recent version at the time that this lab was written).
 
     ```hcl
     module "landing_zone" {
-      source           = "git::https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone.git//patterns/vsi?ref=v4.4.7"
+      source           = "git::https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone.git//patterns/vsi?ref=v4.5.4"
       prefix           = var.prefix
       region           = var.region
       ibmcloud_api_key = var.ibmcloud_api_key
@@ -67,13 +67,13 @@ To run the Terraform module in your local environment, follow these steps.
 6.  Generate a plan. The plan lists of resources that are going to be created.
 
     ```sh
-    terraform plan --var=region=eu-gb -var=ssh-key="$(cat ./lab2-key-tf)" -var=prefix=lab-prefix
+    terraform plan --var=region=eu-gb -var=ssh_key="$(cat ./lab2-key-tf.pub)" -var=prefix=lab-prefix
     ```
 
 7.  (Optional) Apply the changes.
 
     This step might take up to 15 minutes to complete. You can skip it if you're short on time. The automation is run through the catalog onboarding in a later step of this lab.
 
     ```sh
-    terraform apply --var=region=eu-gb -var=ssh-key="$(cat ./lab2-key-tf)" -var=prefix=lab-prefix
+    terraform apply --var=region=eu-gb -var=ssh_key="$(cat ./lab2-key-tf.pub)" -var=prefix=lab-prefix
     ```

Diff for: docs/part2/30-add-apache.md

@@ -10,29 +10,79 @@ We configure the remote-exec provisioner to run a script that installs the Apach
 
 ![Diagram of the flow through the jump box to the workload VSIs](../images/part-2/media/image21.png)
 
-## Steps
-
-```hcl
-resource "null_resource" "application-install" {
-  count = var.number_vsi_workload
-  connection {
-    type         = "ssh"
-    user         = "root"
-    bastion_host = var.floating_ip_address
-    host         = local.workload_ip_list[count.index]
-    private_key  = var.ssh_private_key
-    agent        = false
-    timeout      = "15m"
-  }
-
-  provisioner "remote-exec" {
-    inline = [
-      "apt-get install apache2 -y"
-    ]
-  }
-}
-```
-
-You can find the full logic in the [app-install](https://github.com/IBM/infra-to-app-with-landing-zone/tree/main/app-install) directory.
-
-?> _TODO_ add steps
+## Execute the Apache deployment logic 
+
+You can find the code for this step in the [app-install](https://github.com/IBM/infra-to-app-with-landing-zone/tree/main/app-install) directory. The directory contains the following important files:
+
+- The [main.tf](https://github.com/IBM/infra-to-app-with-landing-zone/blob/main/app-install/main.tf) file which contains the terraform logic calling the remote-exec provisioner with the ‘right’ parameters.
+   
+    Notice the following settings in the `main.tf` file:
+
+    - In the connection block, the `bastion_host` is set to the management server floating IP address that you will use as a jump host to connect to the workload server.
+    - In the connection block, the `host` is set to the IP address of the workload server.
+    - In the provisioner block, a list of the commands that will be executed on the workload server are listed.
+
+    ```hcl
+    resource "null_resource" "application-install" {
+      count = var.number_vsi_workload
+      connection {
+        type         = "ssh"
+        user         = "root"
+        bastion_host = var.floating_ip_address
+        host         = local.workload_ip_list[count.index]
+        private_key  = var.ssh_private_key
+        agent        = false
+        timeout      = "15m"
+      }
+
+      provisioner "remote-exec" {
+        inline = [
+          "apt-get install apache2 -y"
+        ]
+      }
+    }
+    ```
+
+To run the Terraform module in your local environment, follow these steps.
+
+1.  Clone the repository locally with the following Git command, unless you cloned it in the previous step ([Executing the landing zone with a JSON definition](#/./part2/20-custom-module?id=executing-the-landing-zone-with-a-json-definition)):
+
+    ```sh
+    git clone https://github.com/IBM/infra-to-app-with-landing-zone
+    ```
+
+2.  Change to the `app-install` folder
+
+    ```sh
+    cd infra-to-app-with-slz/app-install
+    ```
+
+3.  Create a Terraform workspace. Replace `lab` with your own name in the following command.
+
+    ```sh
+    terraform workspace new lab
+    ```
+
+    Note: If you receive the error `Workspace "..." already exists`, issue the command:
+    
+    ```sh
+    terraform workspace select lab
+    ```
+
+4.  Export the IBM Cloud API key that the Terraform will use for the execution. For instructions, see [Managing user API keys](https://cloud.ibm.com/docs/account?topic=account-userapikey&interface=ui).
+
+    ```sh
+    export TF_VAR_ibmcloud_api_key=<your API key>
+    ```
+
+6.  Generate a plan. The plan lists of resources that are going to be created.
+
+    ```sh
+    terraform plan --var=region=eu-gb -var=ssh_private_key="$(cat ./lab2-key-tf)" -var=floating_ip_address=<The floating point IP address of the jump box> -var=vpc_id=<ID of the workload VPC>
+    ```
+
+7.  (Optional) Apply the changes.
+
+    ```sh
+    terraform apply --var=region=eu-gb -var=ssh_private_key="$(cat ./lab2-key-tf)" -var=floating_ip_address=<The floating point IP address of the jump box> -var=vpc_id=<ID of the workload VPC>
+    ```

Diff for: main.tf

@@ -5,7 +5,7 @@
 
 
 module "landing_zone" {
-  source           = "git::https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone.git//patterns/vsi?ref=v4.4.4"
+  source           = "git::https://github.com/terraform-ibm-modules/terraform-ibm-landing-zone.git//patterns/vsi?ref=v4.5.4"
   prefix           = var.prefix
   region           = var.region
   ibmcloud_api_key = var.ibmcloud_api_key