Azure · glennmusa · Sep 17, 2021 · Sep 14, 2021 · Sep 15, 2021 · Sep 16, 2021
diff --git a/.devcontainer/README.md b/.devcontainer/README.md
@@ -11,7 +11,8 @@ All configuration related to the development container is in the `.devcontainer`
 
 ### Step-by-Step
 
-1. Follow the Mission LZ [Getting Started](https://github.com/Azure/missionlz/blob/main/src/docs/getting-started.md#pre-requisites) pre-requisites and step-by-step guide.
+1. Follow the Mission LZ [Getting Started](../docs/getting-started.md) pre-requisites and step-by-step guide.
+
 1. Open a command line (e.g. `wsl.exe` or `bash.exe`), change to the root folder of the local workspace for the cloned Mission LZ project, and start VS Code from this root folder (not a sub folder or a parent folder).
    > **NOTE:** If you are using WSL or BASH on Linux or Mac, you can navigate to the root folder of the project (for example, in the path `$HOME/missionlz` assuming you cloned the project to $HOME) and enter the command below to launch VS Code in correct directory. Be sure to include the trailing "." in the second command.
 

diff --git a/.github/workflows/apply-and-destroy-terraform.yml b/.github/workflows/apply-and-destroy-terraform.yml
diff --git a/README.md b/README.md
@@ -45,20 +45,20 @@ Mission LZ has the following scope:
 
 <!-- markdownlint-disable MD033 -->
 <!-- allow html for images so that they can be sized -->
-<img src="src/docs/images/scope.png" alt="Mission LZ Scope" width="600" />
+<img src="docs/images/scope.png" alt="Mission LZ Scope" width="600" />
 <!-- markdownlint-enable MD033 -->
 
 ## Networking
 
 Networking is set up in a hub and spoke design, separated by tiers: T0 (Identity and Authorization), T1 (Infrastructure Operations), T2 (DevSecOps and Shared Services), and multiple T3s (Workloads). Security can be configured to allow separation of duties between all tiers. Most customers will deploy each tier to a separate Azure subscription, but multiple subscriptions are not required.
 
 <!-- markdownlint-disable MD033 -->
-<img src="src/docs/images/networking.png" alt="Mission LZ Networking" width="600" />
+<img src="docs/images/networking.png" alt="Mission LZ Networking" width="600" />
 <!-- markdownlint-enable MD033 -->
 
 ## Getting Started using Mission LZ
 
-See our [Getting Started Guide](src/docs/getting-started.md) in the docs.
+See our [Getting Started Guide](docs/getting-started.md) in the docs.
 
 ## Product Roadmap
 
@@ -67,7 +67,7 @@ See the [Projects](https://github.com/Azure/missionlz/projects) page for the rel
 Here's what the repo consists of as of May 2021:
 
 <!-- markdownlint-disable MD033 -->
-<img src="src/docs/images/missionlz_as_of_may2021.png" alt="Mission LZ as of April 2021" width="600" />
+<img src="docs/images/missionlz_as_of_may2021.png" alt="Mission LZ as of April 2021" width="600" />
 <!-- markdownlint-enable MD033 -->
 
 ## Contributing

diff --git a/docs/command-line-deployment.md b/docs/command-line-deployment.md
@@ -0,0 +1,25 @@
+# Command-Line Deployment
+
+The steps in this article assume the following pre-requisites for command-line deployments:
+
+* Follow the Mission LZ [Getting Started](./getting-started.md) steps.
+
+## Step-by-step
+
+1. Follow the [steps to open the `.devcontainer`](../.devcontainer/README.md) as recommended (or start a local BASH shell with the prerequisites installed)
+
+   > `vscode@missionlz-dev:/workspaces/missionlz$` is the root working directory for the BASH shell in the `.devcontainer`
+
+1. Deploy with Bicep (recommended)
+   1. [Deploy](../src/bicep/README.md#Azure-CLI)
+   1. [Customize deployment](../src/bicep/README.md#Deploying-to-Other-Clouds)
+
+1. Or, deploy with Terraform
+   1. [Apply](../src/terraform/README.md)
+   1. [Customize deployment](../src/terraform/README.md#Deploying-to-Other-Clouds)
+
+See the development container [README](../.devcontainer/README.md) for more details on building and running the container.
+
+## Helpful Links
+
+For more endpoint mappings between AzureCloud and AzureUsGovernment: <https://docs.microsoft.com/en-us/azure/azure-government/compare-azure-government-global-azure#guidance-for-developers/>
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,42 @@
+# Getting Started
+
+## Prerequisites
+
+* Current version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
+* An Azure Subscription where you have ['Owner' RBAC permissions](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#owner)
+
+## Concepts
+
+### Command Line Deployments
+
+You can deploy Mission LZ from your workstation using the command line. Some other configurations are possible, but this is the simplest path.
+
+We highly recommend deploying from the Development Container since it comes packaged with all the right versions of the dependencies you'll need.
+
+### Use the Development Container for Command Line Deployments
+
+If you are planning to deploy from your local workstation, we recommend using the VS Code development container specified in this repository. The container includes all the tools and pre-requisites, but you have to build and run the container. If you have Docker Desktop installed, then VS Code makes the rest of it easy. See the [README](../.devcontainer/README.md) document in the `.devcontainer` folder for details.
+
+See [Using the devcontainer](./using-the-devcontainer.md) for configuring your workstation with the development container.
+
+If you want to deploy from the command line on your workstation but do not want to use the development container, take a look at the [`Dockerfile`](../.devcontainer/Dockerfile) and the [`devcontainer.json`](../.devcontainer/Dockerfile) file for examples on how to configure your environment.
+
+## Next steps
+
+### 1. Deploy the Hub and Spoke
+
+With the environment pre-requisites out of the way, deploy the hub and spoke using the [Command Line Deployment](./command-line-deployment.md) for step-by-step instructions:
+
+* [Command Line Deployment](./command-line-deployment.md)
+
+### 2. Deploy Your Workloads
+
+Now that you have the core hub and spoke tiers deployed (Hub, Tier 0, Tier 1, Tier 2), the next step is to deploy one or more workload tiers. Misson LZ supports multiple workload tiers. See [Workload Deployment](./workload-deployment.md) for details and step-by-step instructions:
+
+* [Workload Deployment](./workload-deployment.md)
+
+### 3. Manage Your Deployment
+
+Once you have a lab deployment of Mission Landing Zone established and have decided to move forward, you will want to start planning your production deployment. We recommend reviewing the following pages during your planning phase.
+
+* [Using Management Groups with Mission Landing Zone](./management-groups.md)
diff --git a/.../docs/imgs/custom_template_deployment.gif → docs/images/custom_template_deployment.gif b/.../docs/imgs/custom_template_deployment.gif → docs/images/custom_template_deployment.gif
diff --git a/src/bicep/docs/imgs/deploytoazure.svg → docs/images/deploytoazure.svg b/src/bicep/docs/imgs/deploytoazure.svg → docs/images/deploytoazure.svg
diff --git a/src/bicep/docs/imgs/deploytoazuregov.svg → docs/images/deploytoazuregov.svg b/src/bicep/docs/imgs/deploytoazuregov.svg → docs/images/deploytoazuregov.svg
diff --git a/...ent-groups/mg1-management-groups-list.png → ...ent-groups/mg1-management-groups-list.png b/...ent-groups/mg1-management-groups-list.png → ...ent-groups/mg1-management-groups-list.png
diff --git a/...nt-groups/mg2-empty-subscription-list.png → ...nt-groups/mg2-empty-subscription-list.png b/...nt-groups/mg2-empty-subscription-list.png → ...nt-groups/mg2-empty-subscription-list.png
diff --git a/...gement-groups/mg3-select-subscription.png → ...gement-groups/mg3-select-subscription.png b/...gement-groups/mg3-select-subscription.png → ...gement-groups/mg3-select-subscription.png
diff --git a/.../mg4-subscription-in-management-group.png → .../mg4-subscription-in-management-group.png b/.../mg4-subscription-in-management-group.png → .../mg4-subscription-in-management-group.png
diff --git a/src/docs/images/missionlz_as_of_may2021.png → docs/images/missionlz_as_of_may2021.png b/src/docs/images/missionlz_as_of_may2021.png → docs/images/missionlz_as_of_may2021.png
diff --git a/src/docs/images/networking.png → docs/images/networking.png b/src/docs/images/networking.png → docs/images/networking.png
diff --git a/src/docs/images/scope.png → docs/images/scope.png b/src/docs/images/scope.png → docs/images/scope.png
diff --git a/src/docs/management-groups.md → docs/management-groups.md b/src/docs/management-groups.md → docs/management-groups.md
diff --git a/src/docs/scca.md → docs/scca.md b/src/docs/scca.md → docs/scca.md
diff --git a/src/docs/getting-started.md → docs/using-the-devcontainer.md b/src/docs/getting-started.md → docs/using-the-devcontainer.md
@@ -1,27 +1,11 @@
-# Getting Started
+# Using the devcontainer
 
-## Concepts
-
-### Command Line Deployments
-
-You can deploy Mission LZ from your workstation using the command line. Some other configurations are possible, but these are the two simplest paths.
-
-The command-line deployments involve (1) defining configuration settings (we have examples and defaults to make this easier), and (2) running shell scripts that consolidate and wrap the Terraform commands. We strongly recommend using these scripts because they were designed to be usable, but you could also run the Terraform templates directly using the `terraform` command line tool.
-
-### Use the Development Container for Command Line Deployments
-
-If you are planning to deploy from your local workstation, we recommend using the VS Code development container specified in this repository. The container includes all the tools and pre-requisites, but you have to build and run the container. If you have Docker Desktop installed, then VS Code makes the rest of it easy. See the [README](../../.devcontainer/README.md) document in the `.devcontainer` folder for details.
-
-If you want to deploy from the command line on your workstation but do not want to use the development container, take a look at the [`Dockerfile`](../../.devcontainer/Dockerfile) and the [`devcontainer.json`](../../.devcontainer/Dockerfile) file for examples on how to configure your environment.
-
-## Pre-Requisites
+## Prerequisites
 
 * **Operating system:** Mac OS, Linux, or [Windows 10 with Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
   >*We developed this on Windows 10/WSL running Ubuntu 20.04*
 * **Docker:** Docker Desktop or Docker CE
   >*We use [Docker Desktop on Windows 10](https://docs.docker.com/docker-for-windows/install/), integrated with WSL*
-* Current version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli).
-* An Azure Subscription where you have ['Owner' RBAC permissions].
 
 All other tools and resources are in the development container. The simplest path is to deploy from one of these containers, but it is not required if you want to configure your own deployment environment.
 
@@ -46,27 +30,3 @@ All other tools and resources are in the development container. The simplest pat
      ```BASH
           git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"
      ```
-
-## Deployment paths
-
-* (*Optional*) For details and pre-requisites for the development container, see the [README](../../.devcontainer/README.md) document in the `.devcontainer` folder.
-
-## Next steps
-
-### 1. Deploy the Hub and Spoke
-
-With the environment pre-requisites out of the way, deploy the hub and spoke using the [Command Line Deployment](command-line-deployment.md) for step-by-step instructions:
-
-* [Command Line Deployment](command-line-deployment.md)
-
-### 2. Deploy Your Workloads
-
-Now that you have the core hub and spoke tiers deployed (tier 0, tier 1, tier 2), the next step is to deploy one or more workload tiers. Misson LZ supports multiple workload tiers. See [Workload Deployment](workload-deployment.md) for details and step-by-step instructions:
-
-* [Workload Deployment](workload-deployment.md)
-
-### 3. Manage Your Deployment
-
-Once you have a lab deployment of Mission Landing Zone established and have decided to move forward, you will want to start planning your production deployment. We recommend reviewing the following pages during your planning phase.
-
-* [Using Management Groups with Mission Landing Zone](management-groups.md)
diff --git a/docs/workload-deployment.md b/docs/workload-deployment.md
@@ -0,0 +1,21 @@
+# Workload Deployment (Tier 3)
+
+Mission LZ supports deploying multiple workload tiers that are connected to the hub. We call these tier 3s, or T3s, for convenience. Each tier 3 is intended to support a single workload or single team that needs isolation from the other teams and network connectivity via the hub.
+
+You'll have to have completed the deployment of Mission LZ to peer this new workload to the Hub network and Firewall. See [Command-Line Deployment](./command-line-deployment.md) for steps on how to do deploy those things.
+
+## Step-by-step
+
+1. Log in using the Azure CLI
+
+    ```BASH
+    az login
+    ```
+
+1. Deploy with Bicep (recommended)
+   1. [Deploy](../src/bicep/examples/newWorkload/README.md)
+   1. [Customize deployment](../src/bicep/README.md#Deploying-to-Other-Clouds)
+
+1. Or, deploy with Terraform
+   1. [Apply](../src/terraform/README.md#Deploying-new-Spoke-Networks)
+   1. [Customize deployment](../src/terraform/README.md#Deploying-to-Other-Clouds)
diff --git a/src/bicep/README.md b/src/bicep/README.md
@@ -4,8 +4,8 @@
 
 If you want to develop with Bicep you'll need these:
 
-1. Install Azure CLI https://docs.microsoft.com/en-us/cli/azure/install-azure-cli#install
-1. Install Bicep https://github.com/Azure/bicep/blob/main/docs/installing.md#install-and-manage-via-azure-cli-easiest
+1. Install Azure CLI <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli#install>
+1. Install Bicep <https://github.com/Azure/bicep/blob/main/docs/installing.md#install-and-manage-via-azure-cli-easiest>
 
 However, you don't need Bicep to deploy the compiled `mlz.json` in this repository.
 
@@ -21,10 +21,12 @@ You can deploy with the Azure Portal, the Azure CLI, or with both in an Air-Gapp
 ### Azure Portal
 
 #### AzureCloud
-[![Deploy To Azure](docs/imgs/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json)
+
+[![Deploy To Azure](../../docs/images/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json)
 
 #### AzureUSGovernment
-[![Deploy To Azure US Gov](docs/imgs/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json)
+
+[![Deploy To Azure US Gov](../../docs/images/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json)
 
 ### Azure CLI
 
@@ -50,7 +52,13 @@ az deployment sub create \
     identitySubscriptionId=$identitySubscriptionId \
     operationsSubscriptionId=$operationsSubscriptionId \
     sharedServicesSubscriptionId=$sharedServicesSubscriptionId
+```
 
+#### Deploying to Other Clouds
+
+Supply a different deployment `--location` or override variables with the `--parameters` options:
+
+```plaintext
 # if I were deploying into AzureUSGovernment for example:
 az cloud set -n AzureUsGovernment
 az deployment sub create \
@@ -69,15 +77,15 @@ az deployment sub create \
 
 #### Manually upload and deploy from Portal
 
-1. Save `mlz.json` to disk: https://raw.githubusercontent.com/glennmusa/missionlz/glennmusa/bicep/src/bicep/mlz.json
-1. Create a deployment using the 'Custom Deployment' feature: https://portal.azure.com/#create/Microsoft.Template or https://portal.azure.us/#create/Microsoft.Template
+1. Save `mlz.json` to disk: <https://github.com/Azure/missionlz/blob/bicep/src/bicep/mlz.json>
+1. Create a deployment using the 'Custom Deployment' feature: <https://portal.azure.com/#create/Microsoft.Template> or <https://portal.azure.us/#create/Microsoft.Template>
 1. Click 'Build your own template in the editor'
 1. Click 'Load file'
 1. Select the 'mlz.json' file you saved
 1. Click 'Save'
 1. Click 'Review + Create'
 
-Check out this GIF in the docs to see a visual explanation: [docs/imgs/custom_template_deployment.gif](docs/imgs/custom_template_deployment.gif)
+Check out this GIF in the docs to see a visual explanation: [../../docs/images/custom_template_deployment.gif](../../docs/images/custom_template_deployment.gif)
 
 #### Deploy with Azure CLI
 

diff --git a/src/bicep/examples/newWorkload/README.md b/src/bicep/examples/newWorkload/README.md
@@ -117,7 +117,7 @@ az deployment sub create \
 Or, completely experimentally, try the Portal:
 
 #### AzureCloud
-[![Deploy To Azure](../../docs/imgs/deploytoazure.svg?sanitze=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fsrc%2Fbicep%2Fexamples%2FnewWorkload%2FnewWorkload.json)
+[![Deploy To Azure](../../../../docs/images/deploytoazure.svg?sanitze=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fexamples%2FnewWorkload%2FnewWorkload.json)
 
 #### AzureUSGovernment
-[![Deploy To Azure US Gov](../../docs/imgs/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fexamples%2FnewWorkload%2FnewWorkload.json)
+[![Deploy To Azure US Gov](../../../../docs/images/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure%2Fmissionlz%2Fbicep%2Fexamples%2FnewWorkload%2FnewWorkload.json)
diff --git a/src/bicep/examples/remoteAccess/README.md b/src/bicep/examples/remoteAccess/README.md
@@ -114,8 +114,8 @@ Or, completely experimentally, try the Portal:
 
 ### AzureCloud
 
-[![Deploy To Azure](../../docs/imgs/deploytoazure.svg?sanitze=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fsrc%2Fbicep%2Fexamples%2FremoteAccess%2Fmain.json)
+[![Deploy To Azure](../../../../docs/images/deploytoazure.svg?sanitze=true)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fsrc%2Fbicep%2Fexamples%2FremoteAccess%2Fmain.json)
 
 ### AzureUSGovernment
 
-[![Deploy To Azure US Gov](../../docs/imgs/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fexamples%2FremoteAccess%2Fmain.json)
+[![Deploy To Azure US Gov](../../../../docs/images/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fglennmusa%2Fmissionlz%2Fglennmusa%2Fbicep%2Fexamples%2FremoteAccess%2Fmain.json)
diff --git a/src/bicep/ui/README.md b/src/bicep/ui/README.md
@@ -1,7 +1,7 @@
 # MLZ UI
 
-This folder contains a UI template to be executed against an mlz.json file generated from the bicep modules of MLZ.   This file is intented for use as a quickstart only.
+This folder contains a UI template to be executed against an mlz.json file generated from the bicep modules of MLZ. This file is intented for use as a quickstart only.
 
-[![Deploy To Azure](../docs/imgs/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#blade/Microsoft_Azure_CreateUIDef/CustomDeploymentBlade/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fui%2Fmlz-portal.json)
+[![Deploy To Azure](../../../docs/images/deploytoazure.svg?sanitize=true)](https://portal.azure.com/#blade/Microsoft_Azure_CreateUIDef/CustomDeploymentBlade/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fui%2Fmlz-portal.json)
 
-[![Deploy To Azure Gov](../docs/imgs/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#blade/Microsoft_Azure_CreateUIDef/CustomDeploymentBlade/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fui%2Fmlz-portal.json)
+[![Deploy To Azure Gov](../../../docs/images/deploytoazuregov.svg?sanitize=true)](https://portal.azure.us/#blade/Microsoft_Azure_CreateUIDef/CustomDeploymentBlade/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fmlz.json/uiFormDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fmissionlz%2Fbicep%2Fsrc%2Fbicep%2Fui%2Fmlz-portal.json)