Update quick start

bootstrap/azuredevops/variables.tf

@@ -5,13 +5,13 @@ variable "starter_module" {
 }
 
 variable "version_control_system_access_token" {
-  description = "The personal access token for the version control system to use for the deployment|2|azure_name"
+  description = "The personal access token for the version control system to use for the deployment|2"
   type        = string
   sensitive   = true
 }
 
 variable "version_control_system_organization" {
-  description = "The organization for the version control system to use for the deployment|3|azure_name"
+  description = "The organization for the version control system to use for the deployment|3"
   type        = string
 }
 
@@ -51,7 +51,7 @@ variable "azure_devops_create_project" {
 }
 
 variable "azure_devops_project_name" {
-  description = "The name of the Azure DevOps project to use or create for the deployment|10|azure_name"
+  description = "The name of the Azure DevOps project to use or create for the deployment|10"
   type        = string
 }
 
@@ -72,7 +72,7 @@ variable "apply_approvers" {
 }
 
 variable "root_management_group_display_name" {
-  description = "The root management group display name|13|azure_name"
+  description = "The root management group display name|13"
   type        = string
   default     = "Tenant Root Group"
 }

bootstrap/github/variables.tf

@@ -5,13 +5,13 @@ variable "starter_module" {
 }
 
 variable "version_control_system_access_token" {
-  description = "The personal access token for the version control system to use for the deployment|2|azure_name"
+  description = "The personal access token for the version control system to use for the deployment|2"
   type        = string
   sensitive   = true
 }
 
 variable "version_control_system_organization" {
-  description = "The organization for the version control system to use for the deployment|3|azure_name"
+  description = "The organization for the version control system to use for the deployment|3"
   type        = string
 }
 
@@ -50,7 +50,7 @@ variable "repository_visibility" {
 }
 
 variable "root_management_group_display_name" {
-  description = "The root management group display name|10|azure_name"
+  description = "The root management group display name|10"
   type        = string
   default     = "Tenant Root Group"
 }

docs/wiki/[User-Guide]-Quick-Start.md

@@ -130,16 +130,127 @@ You'll need to decide whether you are using GitHub or Azure DevOps and follow th
 
 ### Azure DevOps
 
+1. Navigate to [dev.azure.com](https://dev.azure.com) and sign in to your organization.
+1. Ensure you navigate to the organization you want to deploy to.
+1. Click the `User settings` icon in the top right and select `Personal access tokens`.
+1. Click `+ New Token`.
+1. Enter `Azure Landing Zone Terraform Accelerator` in the `Name` field.
+1. Alter the `Expiration` drop down and select `Custom defined`.
+1. Choose tommorrows date in the date picker.
+1. Click the `Show all scopes` link at the bottom.
+1. Check the following scopes:
+    1. `Agent Pools`: `Read & manage`
+    1. `Build`: `Read & execute`
+    1. `Code`: `Full`
+    1. `Environment`: `Read & manage`
+    1. `Graph`: `Read & manage`
+    1. `Pipeline Resources`: `Use & manage`
+    1. `Project and Team`: `Read, write & manage`
+    1. `Service Connections`: `Read, write & manage`
+    1. `Variable Groups`: `Read, create & manage`
+1. Click `Create`.
+1. Copy the token and save it somewhere safe.
+1. Click `Close`.
+
 ### GitHub
 
+1. Navigate to [github.com](https://github.com).
+1. Click on your user icon in the top right and select `Settings`.
+1. Scroll down and click on `Developer Settings` in the left navigation.
+1. Click `Personal access tokens` in the left navigation and select `Tokens (classic)`.
+1. Click `Generate new token` at the top and select `Generate new token (classic)`.
+1. Enter `Azure Landing Zone Terraform Accelerator` in the `Note` field.
+1. Alter the `Expiration` drop down and select `Custom`.
+1. Choose tommorrows date in the date picker.
+1. Check the following scopes:
+    1. `repo`
+    1. `workflow`
+    1. `admin:org`: `write:org`
+    1. `user`: `read:user`
+    1. `user`: `user:email`
+    1. `delete_repo`
+1. Click `Generate token`.
+1. Copy the token and save it somewhere safe.
+1. If your organization uses single sign on, then click the `Configure SSO` link next to your new PAT.
+1. Select your organization and click `Authorize`, then follow the prompts to allow SSO.
 
 ## Install the ALZ PowerShell module
 
-1. In you PowerShell Core (pwsh) terminal type `Install-Module -Name ALZ`.
+1. In your PowerShell Core (pwsh) terminal type `Install-Module -Name ALZ`.
 1. The module should download and install the latest version.
 
 ## Run the Bootstrap
 
-Before running the 
+You are now ready to run the boostrap and setup your environment. The inputs differ depending on the VCS you have chosen:
+
+### Azure DevOps
+
+1. In your PowerShell Core (pwsh) terminal type `New-ALZEnvironment -IaC "terraform" -Cicd "azuredevops"`.
+1. The module will download the latest accelerator and then prompt you for inputs.
+1. Fill out the following inputs:
+    1. `starter_module`: This is the choice of [Starter Module](), which is the baseline configuration you want for your Azure landing zone. This also determine the second set of input you'll be prompted for here.
+    1. `version_control_system_access_token`: Enter the Azure DevOps PAT you generated in a previous step.
+    1. `version_control_system_organization`: Enter the name of your Azure DevOps organization.
+    1. `azure_location`: Enter the Azure region where you would like to deploy the storage account and identity for your continuous delivery pipeline. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`.
+    1. `service_name`: This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-<service_name>-mgmt-uksouth-001`. We recommend using `alz` for this.
+    1. `environment_name`: This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-<environment_name>-uksouth-001`. We recommend using `mgmt` for this.
+    1. `postfix_number`: This is used to build up the names of your Azure and Azure DevOps resources, for example `rg-alz-mgmt-uksouth-<postfix_number>`. We recommend using `1` for this.
+    1. `azure_devops_use_organisation_legacy_url`: If you have not migrated to the modern url (still using `https://<organization_name>.visualstudio.com`) for your Azure DevOps organisation, then set this to `true`.
+    1. `azure_devops_create_project`: If you have an existing project you want to use rather than creating a new one, select `true`. We recommend creating a new project to ensure it is isolated by a strong security boundary.
+    1. `azure_devops_project_name`: Enter the name of the Azure DevOps project to create or the name of an existing poroject if you set `azure_devops_create_project` to `false`.
+    1. `azure_devops_authentication_scheme`: Enter the authentication scheme that your pipeline will use to authenticate to Azure. [WorkloadIdentityFederation](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-azure-resource-manager-service-connection-using-workload-identity-federation) uses OpenId Connect and is the recommended approach. [ManagedServiceIdentity](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure?view=azure-devops#create-an-azure-resource-manager-service-connection-to-a-vm-with-a-managed-service-identity) requires the deployment of self-shoted agents are part of the bootstrap setup.
+    1. `apply_approvers`: This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is a comma-separated list like `[email protected],[email protected],[email protected]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider.
+    1. `root_management_group_display_name`: The is the name of the root management group that you applied permissions to in a previous step. This defaults to `Tenant Root Group`, but if you organization has changed it you'll need to enter the new display name.
+1. You will now see a green message telling you that the next section is specigic to the starter module you choose. Navigate to the documentation for the relevant starter module to get details of the specific inputs.
+1. Once you have entered the starter module input, you see that a Terraform `init` and `apply` happen.
+1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed.
+1. If you are happy with the plan, then type `yes` and hit enter.
+1. The Terraform will `apply` and your environment will be bootstrapped.
+
+### GitHub
 
+1. In your PowerShell Core (pwsh) terminal type `New-ALZEnvironment -IaC "terraform" -Cicd "azuredevops"`.
+1. The module will download the latest accelerator and then prompt you for inputs.
+1. Fill out the following inputs:
+    1. `starter_module`: This is the choice of [Starter Module](), which is the baseline configuration you want for your Azure landing zone. This also determine the second set of input you'll be prompted for here.
+    1. `version_control_system_access_token`: Enter the GitHub PAT you generated in a previous step.
+    1. `version_control_system_organization`: Enter the name of your GitHub organization.
+    1. `azure_location`: Enter the Azure region where you would like to deploy the storage account and identity for your continuous delivery pipeline. This field expects the `name` of the region, such as `uksouth`. You can find a full list of names by running `az account list-locations -o table`.
+    1. `service_name`: This is used to build up the names of your Azure and GitHub resources, for example `rg-<service_name>-mgmt-uksouth-001`. We recommend using `alz` for this.
+    1. `environment_name`: This is used to build up the names of your Azure and GitHub resources, for example `rg-alz-<environment_name>-uksouth-001`. We recommend using `mgmt` for this.
+    1. `postfix_number`: This is used to build up the names of your Azure and GitHub resources, for example `rg-alz-mgmt-uksouth-<postfix_number>`. We recommend using `1` for this.
+    1. `apply_approvers`: This is a list of service principal names (SPN) of people you wish to be in the group that approves apply of the Azure landing zone module. This is a comma-separated list like `[email protected],[email protected],[email protected]`. You may need to check what the SPN is prior to filling this out as it can vary based on identity provider.
+    1. `repository_visibility`: This determines whether the repository is `public` or `private`. We recommend you choose `private`, but if you are testing and don't have a licensed GitHub organization, you will need to choose `public` or the boostrapping will fail due to missing functionality.
+    1. `root_management_group_display_name`: The is the name of the root management group that you applied permissions to in a previous step. This defaults to `Tenant Root Group`, but if you organization has changed it you'll need to enter the new display name.
+1. You will now see a green message telling you that the next section is specigic to the starter module you choose. Navigate to the documentation for the relevant starter module to get details of the specific inputs.
+1. Once you have entered the starter module input, you see that a Terraform `init` and `apply` happen.
+1. There will be a pause after the `plan` phase you allow you to validate what is going to be deployed.
+1. If you are happy with the plan, then type `yes` and hit enter.
+1. The Terraform will `apply` and your environment will be bootstrapped.
+
+## Deploy the Landing Zone
+
+Now you have created your boostrapped environment you can deploy you Azure landing zone by triggering the continuous delivery pipeline in your version control system.
+
+### Azure DevOps
+
+1. Navigate to [dev.azure.com](https://dev.azure.com) and sign in to your organization.
+1. Navigate to your project.
+1. Click `Pipelines` in the left navigation.
+1. Click the `Azure Landing Zone Continuous Delivery` pipeline.
+1. Click `Run pipeline` in the top right.
+1. Take the defaults and click `Run`.
+1. Your pipeline will run a `plan`.
+1. If you provided `apply_approvers` to the bootstrap, it will prompt you to approve the `apply` stage.
+1. Your pipeline will run an `apply` and deploy an Azure landing zone based on the starter module you choose.
+
+### GitHub
 
+1. Navigate to [github.com](https://github.com).
+1. Navigate to your repository.
+1. Click `Actions` in the top navigation.
+1. Click the `Azure Landing Zone Continuous Delivery` pipeline in the left navigation.
+1. Click `Run workflow` in the top right, then keep the default branch and click `Run workflow`.
+1. Your pipeline will run a `plan`.
+1. If you provided `apply_approvers` to the bootstrap, it will prompt you to approve the `apply` job.
+1. Your pipeline will run an `apply` and deploy an Azure landing zone based on the starter module you choose.