Doc changes to be more explicit on .devcontainer usage for command-li…

…ne deployments (vs local shell) (#211)

* Moved the project cloning steps to be here

* Move project cloning steps to Getting Started page

The steps for cloning the project to a local machine apply to all usage paths (i.e. development container, command line, and UI deployments), but are only documented in this development container page. The "setup" steps in this page (e.g. the steps of getting the bits to the local machine and ready to run) should be moved to top-level "getting started" page. This will also help simplify/clarify the "Command-Line Deployment" steps by avoiding some context switching across the different getting started pages.

* Update README.md

* Fixed the issues found by linter

* Update README.md

* Making devcontainer usage more explicit

I've personally needed to think about where I need to run these commands to deploy via command-line. This attempts to make it more explicit

* Updates after linter

* Update after linter

* Adding authentication note

* changes to step-by-step list

.devcontainer/README.md

@@ -9,43 +9,20 @@ All configuration related to the development container is in the `.devcontainer`
 - `devcontainer.json`: Configuration settings for the development container
 - `Dockerfile`: Docker container definition for the development container
 
-### Setup
-
-- Install Docker Desktop or Docker CE on a host machine. The host machine can be Windows, Linux, or Mac, and can run on-premises or in the cloud.
-- Clone the Mission LZ from GitHub to a local workspace on the host machine.
- - **Recommended:** If you are using Windows for the host machine, clone and open this repository on Windows Subsystem for Linux (WSL). WSL is not required, but disk IO performance in the container is better and the overall experience is more consistent when running a development container from WSL.
- > **NOTE:** When using Windows with WSL as the host machine, we recommend the following additional steps:
- >
- > - After [installing WSL for Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10), you can run your Linux distribution path right inside PowerShell, from Windows Terminal, or in the Windows command prompt by entering `wsl.exe` or `bash.exe`. These commands will switch to a display of the Linux command line, using the path for your current directory. This path will appear to be in a mounted folder, `/mnt/c`, because we're now viewing your Windows C:\ drive folder from the Linux subsystem. You can access all of your local computer's file system from within the Linux shell by using this `/mnt/c` mounted file path.
- > - For best performance, we recommend cloning the workspace to the Linux file system. For example, from the Linux shell (as noted above), you could run:
- >
- ```BASH
- cd $HOME
- git clone https://github.com/Azure/missionlz.git
- ```
- >
- > - The Windows Git Credential Manager can be configured to work from WSL to help with complex authentication patterns like two-factor authentication. See the [documentation here](https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-git#git-credential-manager-setup). Below is the command to run for setting the Windows Credential Manager in WSL:
-
- ```BASH
- git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"
- ```
-
-- Open a command line (e.g. `wsl.exe` or `bash.exe`), change to the root folder of the local workspace for the cloned repository, 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.
+### Step-by-Step
+
+1. Open a command line (e.g. `wsl.exe` or `bash.exe`), change to the root folder of the cloned 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.
 
  ```BASH
  cd $HOME/missionlz
  code .
  ```
 
-- Install the recommended VS Code extensions found in `.vscode/extensions.json` (relative to the root of the project folder), including the "Remote Development" extension from Microsoft.
- > **NOTE:** When VS Code starts, it reads the file `.vscode/extensions.json` relative from the current working directory. On startup, VS Code may prompt the user to install any extensions referenced here that are not already installed.
-
-### Step-by-Step
-
-1. Open VS Code from the root folder of the local workspace (not a sub folder or a parent folder). You should see a folder named `.devcontainer` at the root of the VS Code Explorer pane.
+1. Install the recommended VS Code extensions found in `.vscode/extensions.json` (relative to the root of the project folder), including the "Remote Development" extension from Microsoft.
+ > **NOTE:** When VS Code is correctly started from the MissionLZ project root directory, you should see folders named `.devcontainer`, `.vscode`, and `src` at the root of the VS Code Explorer pane. In the startup process, VS Code reads the file `.vscode/extensions.json` (relative from the current working directory) and may prompt the user to install any extensions referenced here that are not already installed.
 
-1. In the VS Code command palette (Ctrl+Shift+P), run this command
+1. In the VS Code command palette (Ctrl+Shift+P), run this command:
 
  ```VSCODE
  Remote-Containers: Reopen in Container
@@ -55,16 +32,18 @@ All configuration related to the development container is in the `.devcontainer`
 
  When logged into the devcontainer's terminal, the working directory changes to `vscode@missionlz-dev:/workspaces/missionlz$`
 
-1. (*Optional*) If you'd like to interact with the devcontainer's terminal from another terminal other than VS Code's built in terminal, you can use the `docker exec` command.
+### Step-by-Step (VS Code alternative)
 
- > **NOTE:** VS Code attaches to the container as the user named "vscode", so you have to do the same thing when attaching to a BASH session in the container by specifying the user as an argument to the `docker exec` command. If you do not specify the user then you will be connected as root, which will cause permissions issues in git (if you are launching VS Code from WSL).
+(*Optional*) If you'd like to interact with the devcontainer's terminal from another terminal other than VS Code's built in terminal, you can use the `docker exec` command.
 
- ```BASH
- docker exec --interactive --tty --user vscode missionlz-dev /bin/bash
- ```
+ > **NOTE:** VS Code attaches to the container as the user named "vscode", so you have to do the same thing when attaching to a BASH session in the container by specifying the user as an argument to the `docker exec` command. If you do not specify the user then you will be connected as root, which will cause permissions issues in git (if you are launching VS Code from WSL).
 
- Or, the equivalent short form below:
+```BASH
+docker exec --interactive --tty --user vscode missionlz-dev /bin/bash
+```
 
- ```BASH
- docker exec -it -u vscode missionlz-dev /bin/bash
- ```
+Or, the equivalent short form below:
+
+```BASH
+docker exec -it -u vscode missionlz-dev /bin/bash
+```

src/docs/command-line-deployment.md

@@ -1,35 +1,55 @@
 # Command-Line Deployment
 
+The steps in this article assume the following pre-requisites for command-line deployments:
+
+* Follow the Mission LZ [Getting Started](https://github.com/Azure/missionlz/blob/main/src/docs/getting-started.md#pre-requisites) steps.
+* **(Highly recommend)** Use the [the Mission LZ `.devcontainer`](https://github.com/Azure/missionlz/blob/main/src/docs/getting-started.md#use-the-development-container-for-command-line-deployments) provided in the Mission LZ project and perform the deployment steps below within this context. This container image provides a controlled environment that includes all the pre-requisite tools for Mission LZ deployments and should lead to an overall better user experience.
+
+ > As an alternative, it is possible to deploy Mission LZ via BASH running from the local workstation, but requires the following additional requirements:
+ >
+ > * An Azure Subscription where you have ['Owner' RBAC permissions](<https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/>)
+ > * The current version of Azure CLI (try `az cli -v` or see <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli/>)
+ > * Terraform CLI version > v0.13.4 (try `terraform -v` or see <https://learn.hashicorp.com/tutorials/terraform/install-cli/>)
+
 ## Step-by-step
 
+1. Follow the [steps to open the `.devcontainer`](../../.devcontainer/README.md) as the recommended option (or start a local BASH shell with the additional requirements installed as the alternate option)
+
+ > `vscode@missionlz-dev:/workspaces/missionlz$` is the root working directory for the BASH shell in the `.devcontainer`
+
 1. Log in using the Azure CLI
 
  ```BASH
  az login
  ```
 
-1. [Quickstart](#Quickstart)
-1. [Setup Mission LZ Resources](#Setup-Mission-LZ-Resources)
-1. [Set Terraform Configuration Variables](#Set-Terraform-Configuration-Variables)
-1. [Deploy Terraform Configuration](#Deploy-Terraform-Configuration)
-1. [Clean up Mission LZ Resources](#Clean-up-Mission-LZ-Resources)
+ > *(Optional)* If you needed to deploy into another cloud such as Azure Government, set the cloud name before logging in:
+
+ ```BASH
+ az cloud set -n AzureUSGovernment
+ az login
+ ```
 
-### Quickstart
+1. Quickstart
+ 1. [Deploy](#quickstart-deploy)
+ 1. [Clean](#quickstart-clean)
+ 1. [Arguments](#quickstart-arguments)
+1. Advanced path (*optional*)
+ 1. [Setup Mission LZ Resources](#setup-mission-lz-resources)
+ 1. [Set Terraform Configuration Variables](#set-terraform-configuration-variables)
+ 1. [Deploy Terraform Configuration](#deploy-terraform-configuration)
+ 1. [Clean up Mission LZ Resources](#clean-up-mission-lz-resources)
 
-#### Quickstart Deploy
+## Quickstart
+
+### Quickstart Deploy
 
 Interested in just getting started and seeing what this does? Login to Azure CLI and try this command to deploy Mission LZ with some default configuration:
 
 ```bash
 src/scripts/deploy.sh -s {your_subscription_id}
 ```
 
-> **NOTE** This implies some software pre-requisites. We highly [recommend using the .devcontainer](https://github.com/Azure/missionlz/blob/main/src/docs/getting-started.md#use-the-development-container-for-command-line-deployments) described in this repository to make thing easier. However, deploying Mission LZ via BASH shell is possible with these minimum requirements:
->
-> - An Azure Subscription where you have ['Owner' RBAC permissions](<https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/>)
-> - The current version of Azure CLI (try `az cli -v` or see <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli/>)
-> - Terraform CLI version > v0.13.4 (try `terraform -v` or see <https://learn.hashicorp.com/tutorials/terraform/install-cli/>)
-
 The `deploy.sh` command deploys all of the MLZ and Terraform resources, and by default, into a single subscription in Azure Commercial EastUS with a timestamped name.
 
 If you needed to deploy into another cloud, say Azure Government, you would [override the default region](https://azure.microsoft.com/en-us/global-infrastructure/geographies/#overview) and [default azurerm terraform environment](https://www.terraform.io/docs/language/settings/backends/azurerm.html#environment) like:
@@ -44,7 +64,7 @@ src/scripts/deploy.sh -s {your_subscription_id} \
 
 For a complete list of arguments see [Quickstart Arguments](#Quickstart-Arguments).
 
-#### Quickstart Clean
+### Quickstart Clean
 
 Once the deployment is complete, you'll be presented with a command that will clean up all of the resources that were deployed:
 
@@ -63,7 +83,7 @@ src/scripts/clean.sh -z mymlzenv
 
 The `clean.sh` command will call Terraform destroy for all the resources Terraform created and delete the MLZ resources and service principal.
 
-#### Quickstart Arguments
+### Quickstart Arguments
 
 If you don't wish to use those defaults, you can customize this command to target multiple subscriptions, different regions, and using different Terraform environments and azurerm configurations with the full set of arguments:
 
@@ -95,7 +115,7 @@ src/scripts/deploy.sh -s {my_mlz_configuration_subscription_id} \
 
 Need further customization? The rest of this documentation covers in detail how to customize this deployment to your needs.
 
-### Setup Mission LZ Resources
+## Setup Mission LZ Resources
 
 Deployment of MLZ happens through use of a single Service Principal whose credentials are stored in a central "config" Key Vault.
 
@@ -121,18 +141,18 @@ MLZ uses this Service Principal and its credentials from the Key Vault to deploy
 
 1. Then, run `create_mlz_configuration_resources.sh` at [src/scripts/config/create_mlz_configuration_resources.sh](/src/scripts/config/create_mlz_configuration_resources.sh) to create:
 
- - A config Resource Group to store the Key Vault
- - Resource Groups for each tier to store the Terraform state Storage Account
- - A Service Principal to execute terraform commands
- - An Azure Key Vault to store the Service Principal's client ID and client secret
- - A Storage Account and Container for each tier to store tier Terraform state files
- - Tier specific Terraform backend config files
+ * A config Resource Group to store the Key Vault
+ * Resource Groups for each tier to store the Terraform state Storage Account
+ * A Service Principal to execute terraform commands
+ * An Azure Key Vault to store the Service Principal's client ID and client secret
+ * A Storage Account and Container for each tier to store tier Terraform state files
+ * Tier specific Terraform backend config files
 
  ```bash
  src/scripts/config/create_mlz_configuration_resources.sh src/mlz.config
  ```
 
-### Set Terraform Configuration Variables
+## Set Terraform Configuration Variables
 
 First, clone the *.tfvars.sample file for the global Terraform configuration (e.g. [src/core/globals.tfvars.sample](/src/core/globals.tfvars.sample)) and substitute placeholders marked by curly braces "{" and "}" with the values of your choosing.
 
@@ -150,7 +170,7 @@ Would become:
 location="eastus" # the value used by Terraform in src/core/globals.tfvars
 ```
 
-### Deploy Terraform Configuration
+## Deploy Terraform Configuration
 
 You can use `apply_terraform.sh` at [src/scripts/terraform/apply_terraform.sh](/src/scripts/terraform/apply_terraform.sh) to both initialize Terraform and apply a Terraform configuration based on the backend environment variables and Terraform variables you've setup in previous steps.
 
@@ -199,7 +219,7 @@ src/scripts/terraform/init_terraform.sh \
  src/core/tier-1
 ```
 
-### Clean up Mission LZ Resources
+## Clean up Mission LZ Resources
 
 After you've deployed your environments with Terraform, it is no longer mandatory to keep Mission LZ Resources like the Service Principal, Key Vault, nor the Terraform state files (though you can re-use these resources and stored Terraform state for updating the deployed environment incrementally using `terraform apply` or destroying them from terraform with `terraform destroy`).
 
@@ -209,7 +229,7 @@ If you no longer have the need for a Service Principal with Contributor rights,
 src/scripts/config/config_clean.sh src/mlz.config
 ```
 
-### Terraform Providers
+## Terraform Providers
 
 The development container definition downloads the required Terraform plugin providers during the container build so that the container can be transported to an air-gapped network for use. The container also sets the `TF_PLUGIN_CACHE_DIR` environment variable, which Terraform uses as the search location for locally installed providers. If you are not using the container to deploy or if the `TF_PLUGIN_CACHE_DIR` environment variable is not set, Terraform will automatically attempt to download the provider from the internet when you execute the `terraform init` command.
 

src/docs/getting-started.md

@@ -30,10 +30,33 @@ All other tools and resources are in the development container and in the user i
 
 ## Step-by-step
 
+* Install Docker Desktop or Docker CE on a host machine. The host machine can be Windows, Linux, or Mac, and can run on-premises or in the cloud.
+* Clone the Mission LZ from GitHub to a local workspace on the host machine.
+ * **Recommended:** If you are using Windows for the host machine, clone and open this repository on Windows Subsystem for Linux (WSL). WSL is not required, but disk IO performance in the container is better and the overall experience is more consistent when running a development container from WSL.
+ > **NOTE:** When using Windows with WSL as the host machine, we recommend the following additional steps:
+ >
+ > * After [installing WSL for Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10), you can run your Linux distribution path right inside PowerShell, from Windows Terminal, or in the Windows command prompt by entering `wsl.exe` or `bash.exe`. These commands will switch to a display of the Linux command line, using the path for your current directory. This path will appear to be in a mounted folder, `/mnt/c`, because we're now viewing your Windows C:\ drive folder from the Linux subsystem. You can access all of your local computer's file system from within the Linux shell by using this `/mnt/c` mounted file path.
+ > * For best performance, we recommend cloning the workspace to the Linux file system. For example, from the Linux shell (as noted above), you could run:
+ >
+ ```BASH
+ cd $HOME
+ git clone https://github.com/Azure/missionlz.git
+ ```
+ >
+ > * Authenticating to git is not required for cloning the Mission LZ repo, but you may want to set it up for times when you need authentication, like when you need to push a new branch. 
+ > * The Windows Git Credential Manager can be configured to work from WSL to help with complex authentication patterns like two-factor authentication. See the [documentation here](https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-git#git-credential-manager-setup). Below is the command to run for setting the Windows Credential Manager in WSL:
+ >
+ ```BASH
+ git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"
+ ```
+
+## Deployment paths
+
 * See the detailed step-by-step guides for [Command Line Deployments](command-line-deployment.md) and [User Interface Deployments](ui-deployment.md).
 * (*Optional*) For details and pre-requisites for the development container, see the [README](../../.devcontainer/README.md) document in the `.devcontainer` folder.
 
 ## Next steps
 
 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)
+
+* [Using Management Groups with Mission Landing Zone](management-groups.md)