[User Guide] Quick Start Phase 1

Phase 1 of the accelerator is to setup your pre-requisites. Follow the steps below to do that.

1.1 Tools

You'll need to install the following tools before getting started.

• PowerShell 7.4 (or newer): Follow the instructions for your operating system
• Azure CLI 2.55.0 (or newer): Follow the instructions for your operating system

NOTE: In all cases, ensure that the tools are available from a PowerShell core (pwsh) terminal. You may need to add them to your environment path if they are not.

1.2 Azure Subscriptions

We recommend setting up 3 subscriptions for Azure landing zones. These are management, identity and connectivity. See our advanced scenarios section for alternatives.

• Management: This is used to deploy the bootstrap and management resources, such as log analytics and automation accounts.
• Identity: This is used to deploy the identity resources, such as Azure AD and Azure AD Domain Services.
• Connectivity: This is used to deploy the hub networking resources, such as virtual networks and firewalls.

You can read more about the management, identity and connectivity subscriptions in the Landing Zone docs.

To create the subscriptions you will need access to a billing agreement. The following links detail the permissions required for each type of agreement:

• Enterprise Agreement (EA)
• Microsoft Customer Agreement (MCA)

Once you have the access required, create the three subscriptions following your desired naming convention.

Take note of the subscription id of each subscription as we will need them later.

1.3 Azure Authentication and Permissions

You need either an Azure User Account or Service Principal with the following permissions to run the bootstrap:

• Owner on your chosen parent management group for the Azure landing zone. This could be Tenant Root Group or a new management group you create under there if preferred.
  • Owner is required as this account will be granting permissions for the identities that run the management group deployment. Those identities will be granted least privilege permissions.
• Owner on each of your 3 Azure landing zone subscriptions.

For simplicity we recommend using a User account since this is a one off process that you are unlikely to repeat.

1.3.1 Authenticate via User Account

1. Open a new PowerShell Core (pwsh) terminal.
2. Run az login.
3. You'll be redirected to a browser to login, perform MFA, etc.
4. Find the subscription id of the management subscription you made a note of earlier.
5. Type az account set --subscription "<subscription id of your management subscription>" and hit enter.
6. Type az account show and verify that you are connected to the management subscription.

1.3.2 Authenticate via Service Principal (Skip this if using a User account)

Follow the instructions in the Service Principal section.

1.4 Version Control Systems

You'll need to decide if you are using GitHub, Azure DevOps or the Local File System and follow these steps:

1.4.1 Azure DevOps

1.4.1.1 Azure DevOps Pre-Requisites

When you first create an Azure DevOps organization, it will not have any Microsoft-hosted agents available. If you intend to use Microsoft-hosted agents, you must either license your org or request a free pipeline.

1. Setup billing for your organization: Set up billing for your organization
2. Check for and request a free pipeline via the form here: Configure and pay for parallel jobs

If you choose the billing option, you'll then need to purchase at least one parallel pipeline. You can do this by following the instructions here: Configure and pay for parallel jobs.

1.4.1.2 Azure DevOps Personal Access Token (PAT)

This first PAT is referred to as token-1.

1. Navigate to dev.azure.com and sign in to your organization.
2. Ensure you navigate to the organization you want to deploy to.
3. Click the User settings icon in the top right and select Personal access tokens.
4. Click + New Token.
5. Enter Azure Landing Zone Terraform Accelerator in the Name field.
6. Alter the Expiration drop down and select Custom defined.
7. Choose tomorrows date in the date picker.
8. Click the Show all scopes link at the bottom.
9. Check the following scopes:
   1. Agent Pools: Read & manage
   2. Build: Read & execute
   3. Code: Full
   4. Environment: Read & manage
   5. Graph: Read & manage
   6. Pipeline Resources: Use & manage
   7. Project and Team: Read, write & manage
   8. Service Connections: Read, query & manage
   9. Variable Groups: Read, create & manage
10. Click Create.
11. Copy the token and save it somewhere safe.
12. Click Close.

If you are using self-hosted runners, you will need to create a second PAT that we'll refer to as token-2 for them. You can do this by following the steps above with the following differences:

1. Select the maximum value for the Expiration field (this allows up to 1 year). NOTE: You may want to set a shorter expiration date for security reasons. In either case, you will need to have a process in place to extend expiration the token before it expires.
2. Select only the Agent Pools: Read & manage scope.

1.4.2 GitHub

1.4.2.1 GitHub Pre-Requisites

The accelerator does not support GitHub personal accounts, since they don't support all the features required for security. You must have a GitHub organization account or the accelerator will fail on apply. You can create a free organization here. Learn more about account types here.

NOTE: If you choose to use a free organization account the accelerator bootstrap will make your repositories public. It must do this to support the functionality required by the accelerator. This is not recommended for production environments.

1.4.2.2 GitHub Personal Access Token (PAT)

NOTE: The following instructions refer to classic personal access tokens. You can also use fine-grained access tokens which are still in beta to provide more granular permissions. These docs will be updated to reflect this in the future.

This first PAT is referred to as token-1.

1. Navigate to github.com.
2. Click on your user icon in the top right and select Settings.
3. Scroll down and click on Developer Settings in the left navigation.
4. Click Personal access tokens in the left navigation and select Tokens (classic).
5. Click Generate new token at the top and select Generate new token (classic).
6. Enter Azure Landing Zone Terraform Accelerator in the Note field.
7. Alter the Expiration drop down and select Custom.
8. Choose tomorrows date in the date picker.
9. Check the following scopes:
   1. repo
   2. workflow
   3. admin:org
   4. user: read:user
   5. user: user:email
   6. delete_repo
10. Click Generate token.
11. Copy the token and save it somewhere safe.
12. If your organization uses single sign on, then click the Configure SSO link next to your new PAT.
13. Select your organization and click Authorize, then follow the prompts to allow SSO.

If you are using self-hosted runners, you will need to create a second PAT that we'll refer to as token-2 for them. You can do this by following the steps above with the following differences:

1. Select No expiration for the Expiration field. NOTE: You may want to set an expiration date for security reasons, but you will need to have a process in place to regenerate the token in that scenario.
2. The scope required depends on the type of organization you are using:
   1. If you are using a Free organization or an Enterprise orgnization without a runner group, select only the repo scope.
   2. If you are using an Enterprise organization and a runner group, select the admin:org scope for classic tokens (or organization_self_hosted_runners:write for fine-grained tokens).

1.4.3 Local File System

You just need to ensure that you have a folder on your local file system that you can use to store the files, which your current session has access to.

Next Steps

Now head to Phase 2.