docs: further iteration on lab 2

Author: vburckhardt

Diff for: docs/images/part-2/override-gui.png

@@ -21,9 +21,10 @@ From a compliance perspective, record all interactive operator actions with a ba
 
 In the lab, the workload is exposed through a public VPC load balancer that is attached to the workload VPC. With the following additions, you can make the solution more secure.
 
-Introduce a web application firewall in the flow in one of two ways:
+1. Create the public VPC load balancer in a separate edge VPC. Route the traffic from the edge VPC to the application that is running on the workload VPC through a private load balancer (which is routable only from within the VPC topology). This approach ensures that no direct public network flows to the workload VPC. For more information, see [Connecting from public internet](https://cloud.ibm.com/docs/framework-financial-services?topic=framework-financial-services-vpc-architecture-connectivity-workload#consumer-provider-public-internet) in "Consumer connectivity to workload VPC".
 
+2. Introduce a web application firewall in the flow in one of two ways:
 - As-a-service: Typically, you add a global load balancer, such as IBM Cloud CIS or Akamai, in front of the VPC load balancer. Then, you add a network ACL on the VPC load balancer to accept inbound traffic only from the global load balancer set of known IP addresses.
 - Hosted: You can host the application with a 3rd-party solution, such as BigIP F5. This solution is deployed and hosted on servers that you run, for example in VSIs in the landing-zone VPC topology. For a tutorial, see [Setting up a web application firewall with F5 BIG-IP](https://cloud.ibm.com/docs/framework-financial-services?topic=framework-financial-services-vpc-architecture-connectivity-waf-tutorial).
 
-Create the public VPC load balancer in a separate edge VPC. Route the traffic from the edge VPC to the application that is running on the workload VPC through a private load balancer (which is routable only from within the VPC topology). This approach ensures that no direct public network flows to the workload VPC. For more information, see [Connecting from public internet](https://cloud.ibm.com/docs/framework-financial-services?topic=framework-financial-services-vpc-architecture-connectivity-workload#consumer-provider-public-internet) in "Consumer connectivity to workload VPC".
+

Diff for: docs/part1/50-going-further.md

@@ -2,4 +2,6 @@
 
 Lab 1 shows how you can leverage existing landing-zone automation to deploy most of the topology, and then customize and deploy on top of that infrastructure.
 
-The purpose of part 2 is to show of the manual steps in part 1 can be fully automated. Part 2 will also show how the fully automated custom solution can be shared with other users in your enterprise through the [IBM Cloud Catalog](https://cloud.ibm.com/catalog).
+The purpose of lab 2 is to show of the manual steps in lab 1 can be fully automated. Lab 2 will also show how the fully automated custom solution can be shared with other users in your enterprise through the [IBM Cloud Catalog](https://cloud.ibm.com/catalog).
+
+Lab 2 assumes a basic knowledge of [Terraform](https://www.ibm.com/topics/terraform).

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

@@ -10,28 +10,23 @@ two ways the topology can be customized:
     variables that can be used to tweaks aspects of the VPC topology
     that is deployed. See them as "knobs" that you can turn to slightly
     adjust the desired VPC topology.
-2.  By using a json file, named override.json, which enables deeper and
-    broader types of customizations. Using a JSON file, you can fully
+2.  By using a json definition, which enables deeper and
+    broader types of customizations. The Landing Zone module accepts a json input in the form of a file or through a string containing a json definition. Using a json definition, you can fully
     customize all aspects of the topology, beyond the use of the
     Terraform input variables.
 
 ## Defining our custom topology with a json definition
 
 In this lab, we are going to use the json-based approach to define a
-topology that matches the manual steps followed in the part 1 of the
-lab. As a reminder:
--   A VPC-topology based on the standard SLZ pattern
--   A customization to expose one of the VSI in the management VPC
-    through a public floating IP -- this is our "jump box".
--   Exposing one of the VSI in the workload VPC behind a public load
-    balancer
--   All necessary adjustments to the network ACL and security group to
-    accommodate inbound and outbound traffic to the management jump box
-    and the workload.
+topology that matches the manual steps followed in lab 1 of the
+lab. Starting from the definition for the standard VSI landing zone pattern as a starting point, we make the following customizations:
+-   Expose one of the VSI in the management VPC through a public floating IP -- this is our "jump box".
+-   Add a public VPC load balancer serving public http traffic and distribiting requests to the VSIs in the workload VPC
+-   All necessary adjustments to the network ACL and security group to accommodate inbound and outbound traffic to the management jump box (ssh access) and the workload (http).
 
 ### Creating the json definition 
 
-There are three ways to produce a json file that codify the desired
+There are three ways to produce a json definition that codify the desired
 topology -- ranked by order of complexity:
 1.  The first way is to use the Graphical User Inferface tool provided
     at
@@ -56,5 +51,14 @@ topology -- ranked by order of complexity:
 ### Creating the json definition
 
 In this lab, we provide the JSON file containing those customizations
-[here](https://github.com/IBM/infra-to-app-with-landing-zone/blob/main/custom-slz/override.tftpl) . 
+[here](https://github.com/IBM/infra-to-app-with-landing-zone/blob/main/custom-slz/override.tftpl) .
+
+?> _TODO_ ensure the gui is updated before the lab
+
+You may take a few moment to explore the content of the provided json definition:
+  1. Import the json definition in the Graphical User Inferface tool provided at <https://slz-gui.15z7evpngrsf.us-south.codeengine.appdomain.cloud/>. 
+  2. Click the Import JSON button and copy paste the content of the JSON definition.
+  ![](../images/part-2/override-gui.png)
+  3. After import, you can use the GUI to explore the various facet of the topology using the right-hand menu. Of particular interest in the scope of the customizations are the [VPC Access control](https://slz-gui.15z7evpngrsf.us-south.codeengine.appdomain.cloud/nacls), [Security Groups](https://slz-gui.15z7evpngrsf.us-south.codeengine.appdomain.cloud/securityGroups), and [Virtual Server Instances](https://slz-gui.15z7evpngrsf.us-south.codeengine.appdomain.cloud/vsi) sections. 
+
 

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

@@ -5,25 +5,25 @@
 
 In this step, you will be executing a terraform module that automates
 the creation of the custom landing zone topology defined in the json
-file created in the [previous step](./10-customizing.md).
+definition created in the [previous step](./10-customizing.md).
 
 The objective is to provide a basic terraform module that can be easily
 consumed to create the custom VPC topology. See this module as a level
 of abstraction simplifying consumption: consumers of the module that we
 will create here do not need to understand landing zone, or even the
-json file containing the topology definition -- they can "just" run
-terraform apply with a minimal number of inputs to get the full custom
+json file containing the custom topology definition -- they can "just" run
+`terraform apply` with a minimal number of inputs to get the full custom
 VPC topology deployed in their account.
 
 ## Executing landing-zone with a json definition
 
 The code for this step is located in the [custom-slz](https://github.com/IBM/infra-to-app-with-landing-zone/tree/main/custom-slz) directory. The custom-slz directory contains two
 important files:
-1.  The [override.tftpl](https://github.com/IBM/infra-to-app-with-landing-zone/blob/main/custom-slz/override.tftpl) file -- which is a copy of the json definition for
-    our custom topology created in the previous step of this lab.
+1.  The [override.tftpl](https://github.com/IBM/infra-to-app-with-landing-zone/blob/main/custom-slz/override.tftpl) file -- which is a copy of the json definition for our custom topology created in the previous step of this lab.
+> In this lab, the file is a template file that contains the json definition, with one small addition: the file contains placeholders `${prefix}` that are replaced by an input variable at runtime to ensure that resource group names are unique in the account using the [templatefile](https://developer.hashicorp.com/terraform/language/functions/templatefile) function. This is necessary to ensure there is no clash in the resource group names from multiple attendees running the lab in the same IBM Cloud account.
 2.  The [main.tf](https://github.com/IBM/infra-to-app-with-landing-zone/blob/main/custom-slz/main.tf) file which contains the terraform logic calling the landing zone module with the 'right' parameters. The logic is relatively minimal as it mainly delegates the effort to the landing zone module. Two noteworthy aspects:
 
-    a.  The input named "override_json_string" is set to true. This instructs the landing zone module to look for and use the override.json file in the same directory.
+    a.  The input named `override_json_string` takes the full json definition. In this example, the json passed to the module goes through the templatefile function first to 'inject' the prefix. It is done to ensure uniqueness of the resource group names in the account as indicated in step 1.
 
     b.  The source is set to the standard vsi pattern and pointing to the latest version at the time this lab was written (v4.4.4).
 
@@ -40,7 +40,7 @@ module "landing_zone" {
 
 To run the terraform module on your local environment:
 
-1.  Clone the git repository locally with\
+1.  Clone the git repository locally with
     ```bash
     git clone https://github.com/IBM/infra-to-app-with-landing-zone
     ```
@@ -56,8 +56,23 @@ To run the terraform module on your local environment:
     terraform workspace new lab
     ```
 
-4.  Execute the module with terraform apply.
+4.  Generate a SSH key pair. This is the key pair that will be used to ssh to the VSIs created by this execution.
+```
+ssh-keygen -t rsa -b 4096 -N '' -f ./lab2-key-tf
+```
+
+5.  Export the IBM Cloud API Key that will be used by terraform for the execution. See [instructions](https://cloud.ibm.com/docs/account?topic=account-userapikey&interface=ui)
+```
+export TF_VAR_ibmcloud_api_key=<your API key>
+``` 
+
+6.  Generate a plan. The plan lists of resources that are going to be created.
+    ```bash
+    terraform plan --var=region=eu-gb -var=ssh-key="$(cat ./lab2-key-tf)" -var=prefix=lab-prefix
+    ```
+
+7.  (Optional) Execute the module with terraform apply.
+> This step may take up to 15 minutes to complete. We recommend to skip it if you are short on time. The automation will be run through the catalog onboarding in a subsequent step of this lab.
     ```bash
-    terraform apply --var=region=eu-gb -var=ssh-key="\$(cat pub
-    key) -var=prefix=lab-prefix
+    terraform apply --var=region=eu-gb -var=ssh-key="$(cat ./lab2-key-tf)" -var=prefix=lab-prefix
     ```

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

@@ -10,10 +10,10 @@ In order to implement this automation, we leverage the native terraform
 remote resource and invokes a script on that machine.
 
 In this step, we configure the remote-exec provisioner to run a script
-that installs Apache server on a worker VSI. The remote-exec provisioner
+that installs Apache server all VSIs in the workload VPC ("worker VSIs"). The remote-exec provisioner
 is configured to access the worker nodes through our management jump box
-that is publicly exposed. The same private ssh key is used in this
-example to connect to the jump box and to the worker vsis.
+that is publicly exposed through a floating IP. The same private ssh key is used in this
+example to connect to the jump box and to the worker VSIs.
 
 ![](../images/part-2/media/image21.png)
 

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

@@ -32,15 +32,17 @@ The end result is a **secure webapp** tile in the IBM Cloud Catalog, that end-us
 
     c.  Repository type: **Public repository** 
 
-    d.  Source URL: `https://github.com/IBM/infra-to-app-with-landing-zone/releases/tag/1.0.0`.
+    d.  Source URL: `https://github.com/IBM/infra-to-app-with-landing-zone/releases/tag/1.0.0`.\
     :information_source:  **Note** This URL is the direct link to the tar.gz asset file located in the [GitHub release page](https://github.com/IBM/infra-to-app-with-landing-zone/releases/tag/1.0.0). 
 
-    e.  Variation: **Standard**. 
+    e.  Variation: **Standard**. \
     :information_source:  **Note**: a Deployable Architecture may have multiple variations the user may choose from. For example, the VSI landing zone deployable architecture has got two variations: "quick start" and "standard". In this lab, our deployable architecture has got only one variation. It is a good practice to name this variation "Standard" - but you are free to input any name in this field. 
 
-    f.  Software Version: **1.0.0**. :information_source: **Note**: this is the version shown in the tile to the end-users in the catalog tile. It can be any string following the [semantic versioning conventions](https://semver.org/) and does not necessarily need to match the version in your source control management system. 
+    f.  Software Version: **1.0.0**. \
+    :information_source: **Note**: this is the version shown in the tile to the end-users in the catalog tile. It can be any string following the [semantic versioning conventions](https://semver.org/) and does not necessarily need to match the version in your source control management system. 
 
-    g.  Category: **Enterprise applications**. :information_source: **Note**: You may select a category that closely matches your deployable rchitecture. The catalog can be filtered by category. 
+    g.  Category: **Enterprise applications**. \
+    :information_source: **Note**: You may select a category that closely matches your deployable rchitecture. The catalog can be filtered by category. 
 
     h.  Click **Add product**