Minimal viable documentation for vnext (#125)

* initial commit of minimal viable docs

* update on design principles

* update to principles

* adding quickstart

* corrections

* added instructions for teardown

* draft of readme

* update lab readme

* link to release notes

* ready for review

* broken link

* cleanup

* corrections

* more feedback

Docs/Release/2019-09.md

@@ -0,0 +1,36 @@
+# September 2019 2.0 (Preview Release)
+_Azure Virtual Datacenter Toolkit_
+
+The **September 2019** preview release represents a major change for the toolkit. 
+There are numerous breaking changes and hence we incrementing the major version to 2.
+
+We have revisited our core [design princilpes]() and this lead to significant architectural changes.
+
+At a high level, these include:
+
+- Using [Azure DevOps]() as the default for orchestrating a deployment using [YAML pipelines][]
+- Reducing the use of custom code and constructs
+    - [Modules][] can now be deployed without any custom code
+- Promoting [_Landing Zone_]() as a core pattern
+- Improving auditability of deployments
+
+NOTE: 
+The toolkit is in _preview_. 
+The approach of the toolkit is based on work with our customers, but the specific implementation of this release is not production-ready.
+
+## General changes
+
+* The toolkit now uses [PowerShell Core 6.2][] with [Az PowerShell][] modules.
+* There is _no longer any Python scripts_ beginning with this release
+* [Modules][] are deployment engine agnostic. 
+    - You don't have to use anything proprietary to deploy a module.
+    - Modules consist of templates and parameters that can be deployed just like any other Azure Resource Manager template.
+
+## Known Issues
+
+* Lack of documentation
+
+[Modules]: ../../Modules
+[YAML pipelines]: https://docs.microsoft.com/en-us/azure/devops/pipelines/process/stages?view=azure-devops&tabs=yaml
+[PowerShell Core 6.2]: https://docs.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-core-62?view=powershell-6
+[Az PowerShell]: https://docs.microsoft.com/en-us/powershell/azure/install-az-ps?view=azps-2.5.0

Docs/design-principles.md

@@ -0,0 +1,41 @@
+# Design Principles
+
+These design principles drive the decisions around the toolkit's features and architecture.
+Understanding the design principles is helpful for understanding the intended usage of the toolkit.
+
+Contributors should be familar with these principles before submiting a pull request or recommending a new feature.
+
+There are some instances where the current implementation is not consistent with the stated design principles. 
+However, the intent to always improve consistency.
+
+## Everything-as-Code, Declarative, and Automated
+
+The toolkit is following the common [principles of DevOps](https://docs.microsoft.com/azure/architecture/checklist/dev-ops).
+
+We place an emphasis on [infrastructure-as-code (IaC)](https://en.wikipedia.org/wiki/Infrastructure_as_code) following a [declarative approach](https://en.wikipedia.org/wiki/Declarative_programming). This principle is extended to policy and process (i.e., gated release process).
+**Anything that can be managed through code, should be managed in code.** This is what is meant by _everything-as-code_.
+
+The declarative model means that the code describes a _desired state_ and that some run-time is responsbile for interpreting the code and establishing the desire state. A declarative approach is contrasted against an imperative or procedural approach. An imperative approach provides a set of steps to execute and a desired state can only be infer (at best) from the steps. Azure Resource Manager templates and Azure Policy are declarative.
+
+Automation is a third pillar along with everything-as-code and the declarative approach.
+Any change of state should be intiated as a change to source code. The change in source code triggers an automated process, that includes validation and safety checks. This allows for more predictable outcomes and reduces the risk of human error.
+**Anything that can be automated, should be automated.**
+
+## Don't abstract the platform
+
+The toolkit should avoid introducing abstractions that encapsulate the native platform.
+Instead, it should leverage native features and existing technologies as much as possible.
+
+Any custom code included in the toolkit should be use to compose (or "glue together") native features.
+
+## Open technology choices
+
+A core purpose for the toolkit is to provide end-to-end reference implementations for core enterprise control plane scenarios. The reference implementations are concrete implementations and we have to choose specific technologies. While we have chosen native Azure technologies for our reference implementations, we recognize that customers may have other technology preferences. 
+
+The toolkit should avoid designs that introduce [tight coupling](https://en.wikipedia.org/wiki/Loose_coupling) between different functions. For example, the technology used to orchestrate a deployment (i.e., Azure DevOps, Jenkins) should not restrict the technology used to define the deployment (i.e., Azure Resource Manager templates, Terraform).
+
+## Common tools for automation and manual process
+
+Any automatation should follow the same steps and use the same tools that a developer would use manually.
+For example, a CI/CD pipeline in Azure DevOps should invoke the same commands that a human being would use when deploying manually.
+By having common tools and prodcedures, outcomes are more predictable.

Docs/quickstart.md

@@ -0,0 +1,200 @@
+# Toolkit Quickstart Guide
+
+This guide will walk you through deploying one of the example archetypes provided in the toolkit.
+Specifically, we will deploy a [shared services](../Environments/SharedServices) that does not depend on an on-premises environment.
+
+## Prerequisites
+
+At a minimum you will need to follow this quickstart:
+* [Docker](https://www.docker.com/get-started)
+* [Git](https://git-scm.com/downloads)
+
+We recommended [Visual Studio Code](https://code.visualstudio.com/) as well, though any text editor will suffice.
+
+You can install these on your local machine, or you can the lab VM provided in the toolkit.
+See these instructions for [setting up the lab VM](../LabVM/README.md).
+
+After these prerequisties are installed, we will [clone the reposistory on GitHub](https://help.github.com/en/articles/cloning-a-repository-from-github) and [build a Docker image](https://docs.docker.com/glossary/?term=build).
+This quickstart assumes that you will be interacting with the toolkit through the Docker image.
+
+### Clone the repository
+
+These steps assume that the `git` command is on your path.
+
+1. Open a terminal window
+1. Navigate to a folder where you want to store the source for the toolkit. If you are using the labVM, you can use the default `c:\Users\vdcadmin` folder.
+1. Run `git clone https://github.com/Azure/vdc.git`. This will clone the GitHub repository in a folder named `vdc`.
+1. Run `cd vdc` to change directory in the source folder.
+1. Run `git checkout master` to switch to the branch with the current in-development version of the toolkit.
+
+### Build the Docker image
+
+1. Ensure that the [Docker daemon](https://docs.docker.com/config/daemon/) is running. If you are new to Docker, the easiest way to do this is to install [Docker Desktop](https://www.docker.com/products/docker-desktop).
+1. Open a terminal window
+1. Navigate to the folder where you cloned the repository. _The rest of the quickstart assumes that this path is `C:\Users\vdcadmin\vdc\`_
+1. Run `docker build . -t vdc:latest` to build the image.
+
+### Run the toolkit container
+After the image finishing building, you can run it using:
+
+`docker run -it --rm -v C:\Users\vdcadmin\vdc\Config:/usr/src/app/Config -v C:\Users\vdcadmin\vdc\Environments:/usr/src/app/Environments -v C:\Users\vdcadmin\vdc\Modules:/usr/src/app/Modules vdc:latest`
+
+A few things to note:
+- You don't need to build the image every time you want to run the container. You'll only need to rebuild it if there are changes to the source (primarily changes in the `Orchestration` folder).
+- The `docker run` command above will map volumes in the container to volumes on the host machine. This will allow you to directly modify files in these directories (`Config`,`Environments`, and `Modules`).
+
+When the container starts, you will see the prompt
+`PS /usr/src/app>`
+
+## Configure the toolkit
+
+To configure the toolkit for this quickstart, we will need to collect the following information.
+
+You'll need:
+- A subscription for the toolkit to use for logging and tracking deployment.
+- A subscription that we'll deploy a shared services environment into.
+- The associated tenant id of the Azure Active Directory associated with those subscriptions.
+- The object id of the user account that you'll use to run the deployment.
+- The object id of a [service principal](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal) that Azure DevOps can use for deployment.
+- An organizatgion name for generating a prefix for naming resources. This can be something fictious like "contoso".
+- The desired username and password for the Active Directory domain admin that will be created.
+- The [public ssh key](https://docs.microsoft.com/azure/virtual-machines/linux/mac-create-ssh-keys) for accessing the Linux jumpbox.
+- The desired password of the Windows jumpbox.
+
+Note: You can use a single subscription. You'll just need to provide the same subscription id in multiple locations in the configuration.
+
+### Collecting user object id and tentant id
+
+You can get your user object id and tenant id in the portal or by using command line utitilies.
+
+Using Azure PowerShell:
+1. Run `Connect-AzAccount` to login and set an Azure context.
+1. Run `Get-AzContext | % { Get-AzADUser -UserPrincipalName $($_.Account.Id) } | select Id` to get the user object id.
+1. Run `Get-AzContext | select Tenant` to get the tenant id.
+
+Additional details on these cmdlets are here:
+- [Connect-AzAccount](https://docs.microsoft.com/powershell/module/az.accounts/connect-azaccount?view=azps-2.6.0)
+- [Get-AzContext](https://docs.microsoft.com/powershell/module/az.accounts/get-azcontext?view=azps-2.6.0)
+- [Get-AzADUser](https://docs.microsoft.com/powershell/module/az.resources/get-azaduser?view=azps-2.6.0)
+- [select](https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/select-object?view=powershell-6)
+
+### Azure DevOps service principal
+
+Strictly speaking, you do not need a service principal for the purpose of this quickstart.
+You can reuse your user object id in place of the service principal object id.
+However, if you want to deploy using Azure DevOps will need to create the service principal.
+
+Follow [thse instructions](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal) for creating the service principal and note the object id during creation. The service principal will require owner permissions.
+
+### Setting the configuration
+
+To deploy the shared services environment, you will need to modify two configuration files and set several environmental variables.
+
+#### [`Config\toolkit.subscription.json`](../Config/toolkit.subscription.json)
+
+This file is for toolkit configuration in general.
+
+- Set `Subscription.TenantId` to the tenant id note above.
+- Set `Subscription.SubscriptionId` to the id of the subscription used for logging and deployment state tracking noted above.
+
+#### [`Environments\_Common\subscriptions.json`](../Environments/_Common/subscriptions.json)
+
+This file is for the deployment enviroments configuration. In the quickstart, we are only interested in the `SharedServices`.
+
+- Set `SharedServices.TenantId` to the tenant id note above.
+- Set `SharedServices.SubscriptionId` to the id of the target subscription for the deployment noted above.
+
+#### Environmental variables
+
+The toolkit uses environmental variables instead of configuration files to help avoid the accidental inclusion of secrets into your source control. In the context of a CI/CD pipeline, these values would be retrieved from a key vault.
+
+You can set these environmental variables by substituting the actual values in the script below.
+You can then copy and paste this script into PowerShell to execute it.
+
+Note: The first two variables are set with the content of the configuration files we just modified. The path will not resolve correctly unless you are in `/usr/src/app` directory. 
+
+```PowerShell
+$ENV:VDC_SUBSCRIPTIONS = (Get-Content .\Environments\_Common\subscriptions.json -Raw)
+$ENV:VDC_TOOLKIT_SUBSCRIPTION = (Get-Content .\Config\toolkit.subscription.json -Raw)
+
+$ENV:ORGANIZATION_NAME = "contoso"
+$ENV:TENANT_ID = "00000000-0000-0000-0000-000000000000"
+
+$ENV:KEYVAULT_MANAGEMENT_USER_ID  = "00000000-0000-0000-0000-000000000000"
+$ENV:DEVOPS_SERVICE_PRINCIPAL_USER_ID = "00000000-0000-0000-0000-000000000000"
+
+$ENV:DOMAIN_ADMIN_USERNAME = "xxx"
+$ENV:DOMAIN_ADMIN_USER_PWD = "yyy"
+
+$ENV:ADMIN_USER_PWD = "zzz"
+
+$ENV:ADMIN_USER_SSH = "ssh-rsa ... [email protected]"
+```
+
+To use the above script:
+
+1. Return to the running Docker container from earlier in the quickstart.
+1. Confirm that you are in the `/usr/src/app` directory.
+1. Make a copy of the above script and replace the necessary values.
+1. Copy the script into the clipboard and paste it in the terminal.
+1. Verify that the enviromental variables are set by running `env` to view the current values.
+
+## Deploying the shared services environment
+
+1. Return to the running Docker container from earlier in the quickstart.
+1. If you have not already done so, run `Connect-AzAccount` to login and set an Azure context.
+1. To deply the entire shared services environment, you can run a single command:
+
+    ``` PowerShell
+    ./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json
+    ```
+
+The toolkit will begin deploying the constituent modules and the status will be sent to the terminal.
+Open the [Azure portal](https://portal.azure.com) and you can check the status of the invididual deployments.
+
+## Deploying individual moduels
+
+If you prefer you can deploy the constituent modules for shared services individually. 
+The following is the series of commands to execute.
+
+``` PowerShell
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "DiagnosticStorageAccount"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "LogAnalytics"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "AutomationAccounts"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "LinkLogAnalyticsWithAutomationAccount"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "JumpboxASG"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "DomainControllerASG"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "SharedServicesNSG"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "DMZNSG"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "SharedServicesRouteTable"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "VirtualNetwork"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "EnableServiceEndpointOnDiagnosticStorageAccount"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "VirtualNetworkGateway"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "LocalVirtualNetworkGatewayConnection"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "RemoteVirtualNetworkGatewayConnection"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "AzureFirewall"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "KeyVault"
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -DefinitionPath ./Environments/SharedServices/definition.json -ModuleConfigurationName "ArtifactsStorageAccount"
+```
+
+### Teardown the environment
+
+You can easily tear down the shared services environment by running this command:
+
+``` PowerShell
+./Orchestration/OrchestrationService/ModuleConfigurationDeployment.ps1 -TearDownEnvironment -DefinitionPath ./Environments/SharedServices/definition.json
+```
+
+> Note: This is the same command you used to deploy expect that you include ` -TearDownEnvironment`.
+> It uses the same configuration, so if you change the configuration the tear down may not execute as expected.
+
+For safety reasons, the key vault will not be deleted. Instead, it will be set to a _removed_ state. This means that the name is still considered in use. To fully delete the key vault, use:
+
+``` PowerShell
+Get-AzKeyVault -InRemovedState | ? { Write-Host "Removing vault: $($_.VaultName)"; Remove-AzKeyVault -InRemovedState -VaultName $_.VaultName -Location $_.Location -Force }
+```
+
+### Next steps
+
+Congratulations! You've deployed your first environment with the VDC Toolkit.
+Please be sure to [report any issues](https://github.com/Azure/vdc/issues) you might encounter.

LabVM/README.md

@@ -1,21 +1,31 @@
-# Azure Virtual Datacenter Admin Workstation
-This one click deployment will build a VDC Admin & Development box in Azure.  All of the tools required to build and admin a VDC are installed.
+# Azure Virtual Datacenter lab workstation
+
+This one click deployment will build the toolkit development box in Azure.
+All of the dependencies required to use the toolkit are installed.
 
 <a href="https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fvdc%2Fvnext%2FLabVM%2Fazure-deploy.json" target="_blank">
     <img src="http://azuredeploy.net/deploybutton.png"/>
 </a>
 
-**Software included on the VM**
+> NOTE This can take 30 minutes to set up. Please be aware that if you login too early, the software won't be ready.
+
+## Software included on the VM
 
 1. Docker for Windows Community Edition
 1. Git for Windows (bash)
 1. Visual Studio Code with Extentions: Azure ARM Tools, Azure CLI, Python Linting, Docker, PowerShell
 
-**Creds**
-1. User: vdcadmin
-1. Password: Password.1!!
+See the [`auzre-deploy.json` file for credentials](azure-deploy.json#L16-L17).
+
+> NOTE Storing credentials in source code is a very bad practice.
+> You should change these credentials as soon as you log into the VM.
+
+## Starting Docker
+- Once the VM is deployed use the Azure portal to connect.
+- Double click the Docker for Windows shortcut on the desktop.
+- It will take a few minutes for Docker to start the first time.
+- You may need to sign out and sign back in for Docker to work.
+
 
-**Starting Docker**
-1. Once the VM is deployed use the Azure portal to connect.
-1. Double click the Docker for Windows shortcut on the desktop.
-1. It will take a few minutes for Docker to start the first time.
+## Next steps
+Checkout the [quick start guide](../Docs/quickstart.md).