Skip to content

EC2 Agent Pool Deployment Patterns and Practices

Document describes a general approach to using a terraform module to deploy Azure DevOps agents into AWS using a custom AMI image.

Overview

In most cases, Microsoft Hosted or generic systems through Azure VMSS will meet the needs of a AzDo Agent. Please see Agents-and-Agent-Pools.md for more details on generic use cases.

If you already have a system and simply want to add it as an AzDo Agent, please see the Self-Hosted other VM/Hardware section in Agents-and-Agent-Pools.md.

Prerequisites

  1. AWS account access to deploy EC2 instances
  2. AWS account access to store PAT in HSM
  3. Azure Service Principal to generate PAT access to Azure DevOps
    • Submit an IT ticket to request a Service Principal account
  4. Project Administrator access to Azure Devops Project where the Agent Pool will be deployed
  5. General knowledge of Terraform

Terraform Module

The core module used to deploy Azure Devops Agents into AWS is located in the terraform-aws-mlife-pool repo.

Please see the documentation in the repo for the required inputs and variables.

Azure Prerequisites

These are bootstrap steps and only need to be run once.

Generate PAT for Service Principal

  1. Sign into Azure Devops with your Service Principal
  2. Generate a PAT that has Full Access to the Organization where your Project and Pipelines will run
  3. Store your PAT in HSM to be retrieved later by the agent deployment pipeline
  4. Sign out of Service Principal

Add Service Principal to Your Project

  1. Submit a request to the Energizers team to ensure Service Principal is added to the Organization and has the appropriate access to your Project

Create a Self-hosted Agent Pool in the Project Settings

  1. As Project Administrator
  2. Click on your Project
  3. Go to Project Settings --> Agent Pools --> Add Pool
  4. Ensure New is checked
  5. Select Self-hosted as the Pool type
  6. Enter pool name and description and click Create

Associate Service Principal with Agent Pool

  1. Click on your Project
  2. Go to Project Settings --> Agent Pools
  3. Click on your recently created Agent Pool
  4. Click on the Security tab
  5. Click on +Add
  6. In the User or group field, search for your Service Principal
  7. In the Role field, select Administrator
  8. In the User permissions box, in top right corner is a drop down menu. Click on it and select Organization
  9. Click +Add and add the same values that you did for the project, i.e. find your service principal and make it an Administrator

Deployment Pipeline

You will need to consume the terraform module in an Azure DevOps pipeline that will deploy the agents into your AWS environment/account.

Existing Pipelines and Terraform

Your environment may already have a pipeline that deploys infrastructure. Strongly recommend using these existing pipelines to reduce sprawl of pipelines deploying infrastructure to the same environment. Please contact your infrastructure team and/or development teams to see if there are any existing infrastructure deployment pipelines.

An example of an existing pipeline using the terraform module can be found in * terraform-aws-carelink-env * carelink-infrastructure-environments

New Terraform and Pipeline

If there are no existing pipeline or if there is compelling reasons to create a separate pipeline, then a new Azure DevOps pipeline will need to be created as well as the calling terraform code.

Process

  1. Write the calling terraform code that will call the terraform module. Ensure that the required variables and inputs can be passed to the module.
  2. Add appropriate Service Connection that can deploy to your AWS environment
    • Consult your infrastructure team for access keys
    • Requires Project Administrator to add a Service Connection
  3. Wrap the calling terraform code into an Azure DevOps Pipeline and use the Service Connection to deploy into your AWS environment