-
Notifications
You must be signed in to change notification settings - Fork 36
[User Guide] Quick Start Phase 2 Azure DevOps
You can choose to bootstrap with bicep
or terraform
skip to the relevant section below to do that.
Although you can just run Deploy-Accelerator
and fill out the prompted inputs, we recommend creating an inputs file. This will make it easier to run the accelerator more than once in order to refine your preferred configuration. In the following docs, we'll show that approach, but if you want to be prompted for inputs, just go ahead and run Deploy-Accelerator
now.
-
Create a new folder on you local drive called
accelerator
. -
Inside the accelerator create two folders called
config
andoutput
. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -
Inside the
config
folder create a new file calledinputs.yaml
. You can usejson
if you prefer, but our examples here areyaml
.# Windows New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force New-Item -ItemType "directory" c:\accelerator\output
# Linux/Mac New-Item -ItemType "file" ~/accelerator/config/inputs.yaml -Force New-Item -ItemType "directory" ~/accelerator/output
📂accelerator ┣ 📂config ┃ ┗ 📜inputs.yaml ┗ 📂output
-
Open your
inputs.yaml
file in Visual Studio Code (or your preferred editor) and copy the content from inputs-azure-devops-bicep-complete.yaml into that file. -
Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets
<>
:Input Placeholder Description iac
bicep
This is the choice of bicep
orterraform
. Keep this asbicep
for this example.bootstrap
alz_azuredevops
This is the choice of Version Control System. Keep this as alz_azuredevops
for this example.starter
complete
This is the choice of Starter Modules, which is the baseline configuration you want for your Azure landing zone. Keep this as complete
for this example. This also determines the second set of inputs you'll be prompted for.bootstrap_location
<region>
Replace <region>
with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects thename
of the region, such asuksouth
. You can find a full list of names by runningaz account list-locations -o table
.starter_location
<region>
Replace <region>
with the Azure region where you would like to deploy the starter module resources in Azure. This field expects thename
of the region, such asuksouth
. You can find a full list of names by runningaz account list-locations -o table
.root_parent_management_group_id
""
This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the Tenant Root Group
management group, you leave this as an empty string""
or supply the tenant id.subscription_id_management
<management-subscription-id>
Replace <management-subscription-id>
with the id of the management subscription you created in the previous phase.subscription_id_identity
<identity-subscription-id>
Replace <identity-subscription-id>
with the id of the identity subscription you created in the previous phase.subscription_id_connectivity
<connectivity-subscription-id>
Replace <connectivity-subscription-id>
with the id of the connectivity subscription you created in the previous phase.azure_devops_personal_access_token
<token-1>
Replace <token-1>
with thetoken-1
Azure DevOps PAT you generated in a previous step.azure_devops_agents_personal_access_token
<token-2>
Replace <token-2>
with thetoken-2
Azure DevOps PAT you generated in the previous step specifically for the self-hosted agents. This only applies if you haveuse_self_hosted_agents
set totrue
. You can set this to an empty string""
if you are not using self-hosted agents.azure_devops_organization_name
<azure-devops-organization>
Replace <azure-devops-organization>
with the name of your Azure DevOps organization. This is the section of the url afterdev.azure.com
or before.visualstudio.com
. E.g. entermy-org
forhttps://dev.azure.com/my-org
.use_separate_repository_for_templates
true
Determine whether to create a separate repository to store pipeline templates as an extra layer of security. Set to false
if you don't wish to secure your pipeline templates by using a separate repository. This will default totrue
.bootstrap_location
<region>
Replace <region>
with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects thename
of the region, such asuksouth
. You can find a full list of names by runningaz account list-locations -o table
.bootstrap_subscription_id
""
Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via az login
will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer.service_name
alz
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 usingalz
for this.environment_name
mgmt
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 usingmgmt
for this.postfix_number
1
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 using1
for this.azure_devops_use_organisation_legacy_url
false
If you have not migrated to the modern url (still using https://<organization_name>.visualstudio.com
) for your Azure DevOps organisation, then set this totrue
.azure_devops_create_project
true
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.azure_devops_project_name
<azure-devops-project-name>
Replace <azure-devops-project-name>
with the name of the Azure DevOps project to create or the name of an existing project if you setazure_devops_create_project
tofalse
.use_self_hosted_agents
true
This controls if you want to deploy self-hosted agents. This will default to true
.use_private_networking
true
This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have use_self_hosted_agents
set totrue
. This defaults totrue
.allow_storage_access_from_my_ip
false
This is not relecant to Bicep and we'll remove the need to specify it later, leave it set to false
.apply_approvers
<email-address>
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 an array of strings 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. Use empty array[]
to disable approvals. Note if supplying via the user interface, use a comma separated string like[email protected],[email protected],[email protected]
.create_branch_policies
true
This controls whether to create branch policies for the repository. This defaults to true
. -
Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done.
-
In your PowerShell Core (pwsh) terminal run the module:
# Windows (adjust the paths to match your setup) Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output"
# Linux/Mac (adjust the paths to match your setup) Deploy-Accelerator -inputs "~/accelerator/config/inputs.yaml" -output "~/accelerator/output"
-
You will see a Terraform
init
andapply
happen. -
There will be a pause after the
plan
phase you allow you to validate what is going to be deployed. -
If you are happy with the plan, then type
yes
and hit enter. -
The Terraform will
apply
and your environment will be bootstrapped.
-
Create a new folder on you local drive called
accelerator
. -
Inside the accelerator create two folders called
config
andoutput
. You'll store you input file inside config and the output folder will be the place that the accelerator stores files while it works. -
Inside the
config
folder create a new file calledinputs.yaml
. You can usejson
if you prefer, but our examples here areyaml
.# Windows New-Item -ItemType "file" c:\accelerator\config\inputs.yaml -Force New-Item -ItemType "directory" c:\accelerator\output
# Linux/Mac New-Item -ItemType "file" ~/accelerator/config/inputs.yaml -Force New-Item -ItemType "directory" ~/accelerator/output
📂accelerator ┣ 📂config ┃ ┗ 📜inputs.yaml ┗ 📂output
-
Open your
inputs.yaml
file in Visual Studio Code (or your preferred editor) and copy the content from the relevant input file for your chosen starter module:- Basic - inputs-azure-devops-terraform-basic.yaml
- Hub Networking - inputs-azure-devops-terraform-hubnetworking.yaml
- Complete - inputs-azure-devops-terraform-complete.yaml
-
Check through the file and update each input as required. It is mandatory to update items with placeholders surrounded by angle brackets
<>
:Input Placeholder Description iac
terraform
This is the choice of bicep
orterraform
. Keep this asterraform
for this example.bootstrap
alz_azuredevops
This is the choice of Version Control System. Keep this as alz_azuredevops
for this example.starter
complete
This is the choice of Starter Modules, which is the baseline configuration you want for your Azure landing zone. Choose complete
,hubnetworking
orbasic
for this example. This also determines the second set of inputs you'll be prompted for.bootstrap_location
<region>
Replace <region>
with the Azure region where you would like to deploy the bootstrap resources in Azure. This field expects thename
of the region, such asuksouth
. You can find a full list of names by runningaz account list-locations -o table
.starter_location
<region>
Replace <region>
with the Azure region where you would like to deploy the starter module resources in Azure. This field expects thename
of the region, such asuksouth
. You can find a full list of names by runningaz account list-locations -o table
.root_parent_management_group_id
""
This is the id of the management group that will be the parent of the management group structure created by the accelerator. If you are using the Tenant Root Group
management group, you leave this as an empty string""
or supply the tenant id.subscription_id_management
<management-subscription-id>
Replace <management-subscription-id>
with the id of the management subscription you created in the previous phase.subscription_id_identity
<identity-subscription-id>
Replace <identity-subscription-id>
with the id of the identity subscription you created in the previous phase.subscription_id_connectivity
<connectivity-subscription-id>
Replace <connectivity-subscription-id>
with the id of the connectivity subscription you created in the previous phase.azure_devops_personal_access_token
<token-1>
Replace <token-1>
with thetoken-1
Azure DevOps PAT you generated in a previous step.azure_devops_agents_personal_access_token
<token-2>
Replace <token-2>
with thetoken-2
Azure DevOps PAT you generated in the previous step specifically for the self-hosted agents. This only applies if you haveuse_self_hosted_agents
set totrue
. You can set this to an empty string""
if you are not using self-hosted agents.azure_devops_organization_name
<azure-devops-organization>
Replace <azure-devops-organization>
with the name of your Azure DevOps organization. This is the section of the url afterdev.azure.com
or before.visualstudio.com
. E.g. entermy-org
forhttps://dev.azure.com/my-org
.use_separate_repository_for_templates
true
Determine whether to create a separate repository to store pipeline templates as an extra layer of security. Set to false
if you don't wish to secure your pipeline templates by using a separate repository. This will default totrue
.bootstrap_subscription_id
""
Enter the id of the subscription in which you would like to deploy the bootstrap resources in Azure. If left blank, the subscription you are connected to via az login
will be used. In most cases this is the management subscription, but you can specifiy a separate subscription if you prefer.service_name
alz
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 usingalz
for this.environment_name
mgmt
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 usingmgmt
for this.postfix_number
1
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 using1
for this.azure_devops_use_organisation_legacy_url
false
If you have not migrated to the modern url (still using https://<organization_name>.visualstudio.com
) for your Azure DevOps organisation, then set this totrue
.azure_devops_create_project
true
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.azure_devops_project_name
<azure-devops-project-name>
Replace <azure-devops-project-name>
with the name of the Azure DevOps project to create or the name of an existing project if you setazure_devops_create_project
tofalse
.use_self_hosted_agents
true
This controls if you want to deploy self-hosted agents. This will default to true
.use_private_networking
true
This controls whether private networking is deployed for your self-hosted agents and storage account. This only applies if you have use_self_hosted_agents
set totrue
. This defaults totrue
.allow_storage_access_from_my_ip
false
This controls whether to allow access to the storage account from your IP address. This is only needed for trouble shooting. This only applies if you have use_private_networking
set totrue
. This defaults tofalse
.apply_approvers
<email-address>
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 an array of strings 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. Use empty array[]
to disable approvals. Note if supplying via the user interface, use a comma separated string like[email protected],[email protected],[email protected]
.create_branch_policies
true
This controls whether to create branch policies for the repository. This defaults to true
. -
Now head over to your chosen starter module documentation to get the specific inputs for that module. Come back here when you are done.
- Terraform Basic Starter Module: Management groups and policies.
- Terraform Hub Networking Starter Module: Management groups, policies and hub networking.
- Terraform Complete Starter Module: Management groups, policies, hub networking with fully custom configuration.
-
In your PowerShell Core (pwsh) terminal run the module:
# Windows (adjust the paths to match your setup) Deploy-Accelerator -inputs "c:\accelerator\config\inputs.yaml" -output "c:\accelerator\output"
# Linux/Mac (adjust the paths to match your setup) Deploy-Accelerator -inputs "~/accelerator/config/inputs.yaml" -output "~/accelerator/output"
-
You will see a Terraform
init
andapply
happen. -
There will be a pause after the
plan
phase you allow you to validate what is going to be deployed. -
If you are happy with the plan, then type
yes
and hit enter. -
The Terraform will
apply
and your environment will be bootstrapped.
Now head to Phase 3.
This wiki is being actively developed
If you discover any documentation bugs or would like to request new content, please raise them as an issue or feel free to contribute to the wiki via a pull request. The wiki docs are located in the repository in the docs/wiki/
folder.
- Home
-
User guide
- Getting started
- Quick Start
- Starter Modules
- Input Files
- Azure DevOps Bicep Complete
- Azure DevOps Terraform Complete Multi Region
- Azure DevOps Terraform Sovereign Landing Zone
- Azure DevOps Terraform Basic
- Azure DevOps Terraform Hub Networking
- Azure DevOps Terraform Complete
- GitHub Bicep Complete
- GitHub Terraform Complete Multi Region
- GitHub Terraform Sovereign Landing Zone
- GitHub Terraform Basic
- GitHub Terraform Hub Networking
- GitHub Terraform Complete
- Local Bicep Complete
- Local Terraform Complete Multi Region
- Local Terraform Sovereign Landing Zone
- Local Terraform Basic
- Local Terraform Hub Networking
- Local Terraform Complete
- Frequently Asked Questions
- Upgrade Guide
- Advanced Scenarios
- Troubleshooting
- Contributing