This step-by-step guide describes the process to deploy the Azure Mission-Critical reference implementation in your own environment from the beginning. At the end of this guide you will have an Azure DevOps organization and project set up to deploy a copy of the Azure Mission-Critical reference implementation into an Azure Subscription.
This guide describes the steps to get started using the Azure DevOps Portal (UI) only. To create the set up through the Azure CLI only follow this guide instead.
The Azure Mission-Critical project is using a GitHub repository for version control of code artifacts and manifest files. The project leverages Azure DevOps Pipelines for build and deployment (CI/CD) pipelines.
Instead of GitHub also other Git-based repositories can be used, such as Azure DevOps Repos.
All relevant code artifacts and manifest files are stored in this GitHub repository and can easily be forked into your own account or organization.
This guide describes the end-to-end process for setting up all pre-requisites and dependencies before deploying the Azure Mission-Critical reference implementation into an Azure subscription of your choice.
The Azure Mission-Critical reference implementation gets deployed into an Azure Subscription. For this you will need a Service Principal (SPN) with Owner permissions on that subscription.
- Either your user needs to have Owner or User Access Administrator (UAA) permission and you have the right to create new Service Principals on your Azure AD tenant, or
- You need to have a pre-provisioned Service Principal with Owner permissions on the subscription
If you will create the Service Principal yourself, it is recommended to have either Azure CLI installed on your machine or have access to it through the Azure Cloud Shell.
Also, to deploy the Connected reference implementation, you are required to have an existing domain name which is managed in an Azure DNS Zone. This is needed in order to connect Azure Front Door via Private Link to the backends on AKS, as this requires officially validated SSL certificates. The pipeline will take care of the certificate creation and validation using Let's Encrypt, but you need to provision the DNS Zone beforehand. Depending on your scenario, Azure App Service Domains might be an option to easily procure a domain name.
The process to deploy the Azure Mission-Critical reference implementation is comprised of the following steps:
- Create an Azure DevOps organization and project
- Generate your own repository based on the Azure Mission-Critical GitHub template repository
- Import deployment pipelines
- Create Service Principals for each individual Azure subscription
- Create Service Connections in Azure DevOps
- Adjust configuration
- Configure pre-provided VNets
- Set up private build agents
- Execute the first deployment
- Check deployed resources
If you run into any issues during the deployment, consult the Troubleshooting guide.
To deploy the Azure Mission-Critical reference implementation, you need to create a new Azure DevOps organization, or re-use an existing one. In this organization you will then create a new project used to host all pipelines for Azure Mission-Critical.
Once you have created an Azure DevOps organization, you can create a new project in that organization. Go to the Azure DevOps portal, select the desired Organization and Click on "+ New Project" in the upper right hand corner.
Select a name and set the visibility. Both "Enterprise" or "Private" are fine for this walkthrough.
This will result in a new project, <your-project> in your Azure DevOps organization:
Azure DevOps Repos would allow us to import the Azure Mission-Critical GitHub repository into Azure DevOps as well. For this guide we have decided to generate our own repository based on the template on GitHub and use it from there.
Go to the root of this Azure Mission-Critical repository on GitHub and click on "Use this template" in the top right corner:
This will let you create a repository in your own account or organization. This is needed to allow you to make modification to our code within your own repository.
Now that you have your own repo, let's start to import the pre-created pipelines into Azure Pipelines.
The files to import are the YAML files stored in the root of the /.ado/pipelines/ directory. Do not import files from subdirectories, such as /.ado/pipelines/config/ or /.ado/pipelines/templates/, or from other directories in the repo.
You can find more details about any of the pipelines within the pipelines documentation.
To start, you will import only the following pipeline from the /.ado/pipelines/ directory:
/.ado/pipelines/azure-release-e2e.yaml
When you are later ready to also deploy further environments such as INT (integration) and PROD (production), repeat the same steps (and consecutive actions below) for the respective pipelines:
/.ado/pipelines/azure-release-int.yaml/.ado/pipelines/azure-release-prod.yaml
Important! The Import Pipeline UI will ask you to approve needed permissions, and will show you a list of all YAML files found within the repository. See note above about which YAML files to import.
-
Go to your Azure DevOps project
-
Go to "Pipelines"
-
Click "Create pipeline" or "New pipeline"
-
Select "GitHub (YAML)"
Note! If requested, grant the Azure Pipelines app permissions to access your GitHub repository.
-
Search for your repository in "Select a repository" (name of your template)
Note! If requested, grant the Azure Pipelines app permissions to access your GitHub repository.
-
Select "Existing Azure Pipelines YAML file" in the "Configure your pipeline" dialog and click "Continue"
Note! In the "Select an existing YAML file" dialog, select the YAML file you want to import. For the e2e pipeline this is
/.ado/pipelines/azure-release-e2e.yaml.
-
Select "Save" (from the dropdown menu under the "Run" button) to save the pipeline
-
Rename the pipeline by clicking on the three dots and (optionally) move it into a folder (see below). The UI usually doesn't immediately reflect the change, so just refresh the page.
This step can be skipped if a Service Principal was pre-provisioned.
All pipelines require an Azure DevOps service connection to access the target Azure Subscription where the resources are deployed. These service connections use Service Principals to access Azure which can be configured automatically, when proper access is given, or manually in Azure DevOps by providing a pre-created Azure Service Principal with the required permissions.
We need to create an AAD Service Principal with Subscription-level Owner permissions. We need owner permission as the pipeline will need to create various role assignments.
You need to repeat these steps for each of the environments that you want to create. But you can also only start with one for now. If so, we recommend to start with e2e.
# Get the subscription ID
az account show --query id -o tsv
# Output:
xxx-xxxxxxx-xxxxxxx-xxxx
# Verify that this is indeed the subscription you want to target. Otherwise you can switch the scope using:
# az account set --subscription <name>
# Make sure to change the name to a unique one within your tenant
az ad sp create-for-rbac --scopes "/subscriptions/xxx-xxxxxxx-xxxxxxx-xxxx" --role "Owner" --name <CHANGE-MY-NAME-alwayson-deployment-sp>
# Output:
{
"appId": "d37d23d3-d3d3-460b-a4ab-aa7a11504e76",
"displayName": "my-alwayson-deployment-sp",
"password": "notARealP@assword-h3re",
"tenant": "64f988bf-86f1-42af-91ab-2d7gh011db47"
}Take a note of the appId and password from the output of that command as you will need it below.
More information about the required permissions needed to deploy via Terraform can be found here.
Our Azure Mission-Critical reference implementation knows three different environments: prod, int and e2e. These three environments can be selected for each individual pipeline run and can refer to the same or different (recommended) Azure subscriptions for proper separation. These environments are represented by service connections in Azure DevOps:
Important! Since these connection names are used in pipelines, use them exactly as specified below. If you change the name of the service connection, you have to also change it in pipeline YAML.
alwayson-e2e-serviceconnectionalwayson-prod-serviceconnectionalwayson-int-serviceconnection
If you only created one Service Principal above, you only need to create one Service Connection for now.
When you create the service connections, make sure that you specify the right credentials for the service principal created earlier.
- Go to "Project settings" in Azure DevOps Portal
- Go to "Service connections" in the "Pipelines" section
- Click on "New service connection"
- Select "Azure Resource Manager"
- Select "Service principal (manual)"
- Set the subscription details and credentials
- Set the service connection name to one of the three above
- Click on "Verify and save"
There are three variables files in the /.ado/pipelines/config folder, one for each environment. You need to edit these files to reflect your own workspace before you execute the first deployments. They are named variables-values-[env].yaml.
Modify the respective file for the environment which you want to deploy. At least the variables which are marked as required in the table below need to be changed.
| Required to modify | Key | Description | Sample value |
|---|---|---|---|
| YES | prefix | Custom prefix used for Azure resources. Must not be longer than 6 characters! | mye2e |
| YES | contactEmail | E-mail alias used for alerting. Be careful which address you put in here as it will potentially receive a lot of notification emails | alwaysonappnet@example.com |
| NO | terraformResourceGroup | Resource Group where the Terraform state Storage account will be deployed | terraformstate-rg |
| NO | stampLocations | List of locations (Azure Regions) where this environment will be deployed into. You can keep the default to start with. | ["northeurope", "eastus2"] |
| YES | envDnsZoneRG | Name of the Azure Resource group which holds the Azure DNS Zone for your custom domain. | mydns-rg |
| YES | envDomainName | Name of the Azure DNS Zone. | example.com |
After modifying the file, make sure to commit and push the changes to your Git repository.
For more details on the variables, you can consult this guide.
If you are deploying an environment, which needs connectivity to other company resources such as through a hub-and-spoke model, you need to pre-provision a number of VNets for this environment. If you do not plan to use this feature for the environment which you are working on right now (e.g. E2E), you can skip this step. In this case, the deployment will create temporary, unconnected VNets for each deployment.
For every region that you want to deploy stamps into, you need at least two pre-provisioned VNets. Those will often be created by a central platform team with peering set up to a hub network. These VNets need to be created in the same subscription as the environment. Collect the resource IDs of the VNets and create/update the corresponding file in .ado/pipelines/config/vnets-[environment].json. See /.ado/pipelines/config/vnets-int.json for an example.
See this guide for more information about the VNet usage and setup.
After modifying the file, make sure to commit and push the changes to your Git repository.
Deployment pipelines are taking a dependency on ADO environments. Each pipeline requires an environment created on the ADO project.
Note: Based on your ADO organizational settings, the environments will have already been created for you when you imported the pipelines.
- Click on Pipelines->Environment on the ADO project
- Create a "New environment"
Click on "Create"
In order to deploy the resources in the next step, you must first set up the private Build Agent infrastructure. For detailed instructions on this, please follow this guide.
After completing all previous steps in this guide, you can start executing the pipelines to spin up the infrastructure.
You might notice a longer delay until the job actually starts. This is due to the fact the ADO first needs to spin up instances in the scale set before they can pick up any task.
Otherwise you should see no immediate difference compared to the Azure Mission-Critical Online reference implementation in the deployment itself. However, when you check the deployed resources, you will notice differences. For example that AKS is now deployed as a private cluster or that you will not be able to see the repositories in the Azure Container Registry through the Azure Portal anymore (due to the network restrictions to only allow Private Endpoint traffic).
Go the the Pipelines section of the Azure DevOps Portal and click on the E2E release pipeline.
Then click Run pipeline:
In the popup window, uncheck the box Destroy environment at the end and then click Run.
This will now kick off your first full pipeline run. You can follow the progress in the run screen:
Upon the first execution of a pipeline, Azure DevOps might ask you to grant permissions on the required service connection to Azure, as well as the environment.
Click on View and then on Permit for each required permission.
After this, the pipeline execution will kick off.
If you run into any issues during the deployment, consult the Troubleshooting guide.
The full run, which deploys all resources from scratch, might take around 30-40 minutes. Once all jobs are finished, take a note of the resource prefix which is now shown in the header of your pipeline screen:
You can now go to the Azure Portal and check the provisioned resources. In the Resource Groups blade, locate the groups which start with the aforementioned prefix. You will see two resources groups (or more, depending if you changed the number of desired stamps):
Global Resources
Stamp Resources
For information on how to connect to the data plane, e.g. of AKS follow this guide.
We can now browse to the demo app website. Fetch the URL from the Front Door resource:
- Find the "Global Resource" group, e.g.
<myprefix>123-global-fd - Click on the Front Door resource (e.g.
<myprefix>123-global-fd) - Click on the "Frontend host" link
- This opens the landing page of the demo app. Feel free to browse around!
With the completion of at least one deployment pipeline it is now a good time to read more about the pipeline workflows and other available documentation:
-
Guidance on Azure DevOps Workflows
-
Detailed information about the infrastructure layer - Terraform documentation.