Manage VM resources in environments

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

An Azure Pipelines environment is a group of resources that you can target with deployments from a pipeline. Typical environments include Development, Test, or Production.

To add physical or virtual machine (VM) resources to environments, you install agents on the machines. The environment's deployment history then provides traceability from each machine. This article describes how to define and use environments to manage deployments across VM or server resources.

Prerequisites

To carry out the procedures in this article, you need the following prerequisites:

Create an environment and add a VM

Use the following procedure to add a VM or physical machine to an environment.

Create the environment with a VM resource

1. In your Azure DevOps project, go to Pipelines > Environments and then select Create environment or New environment.

2. On the New environment screen, enter a Name and optional Description.

3. Under Resource, select Virtual machines, and then select Next.

   

Copy the registration script

The agent scripts for VM resources are like the scripts for self-hosted agents, and use the same commands. The scripts include an Azure DevOps Personal Access Token (PAT) for the signed-in user, which expires three hours after the script is generated. You need the PAT only to install the agent.

Run the copied registration script on the VM

1. Select Close. The new environment is created. To copy the script again, for example if your PAT expires, select Add resource again on the environment's page.

   

2. Run the copied script on each target VM that you want to register with the environment.

   Note

   If the VM already has another agent running on it, provide a unique name for the new agent to register with the environment.

3. Once the VM is registered, verify that it appears on the Resources tab of the Azure Pipelines environment page.

   

Use environments in YAML pipelines

You can target VM resources in your YAML deployment jobs by referencing their environment. For more information about YAML deployment jobs, see Deployment jobs and the jobs.deployment definition in the YAML pipelines schema reference.

The following pipeline deployment job runs only on VMs in the VMEnv environment.

trigger: 
- main

pool: 
   vmImage: ubuntu-latest

jobs:
- deployment: VMDeploy
  displayName: Deploy to VMenv
  environment: VMenv
  strategy:
     runOnce:
        deploy:   
          steps:
            - script: echo "Hello world"

You can target a specific VM in the environment by appending the VM resource name to the environment name. The following example deploys only to the VM resource named RESOURCE-PC in the VMenv environment.

trigger: 
- main

pool: 
   vmImage: ubuntu-latest

jobs:
- deployment: VMDeploy
  displayName: Deploy to RESOURCE-PC in VMenv
  environment: VMenv.RESOURCE-PC  # only deploy to the VM resource named RESOURCE-PC
  strategy:
     runOnce:
        deploy:   
          steps:
            - script: echo "Hello world"

You can also use the full syntax of the jobs-deployment-environment keyword, and deploy to specific environment VMs by listing them in resourceName.

trigger: 
- main

pool: 
   vmImage: ubuntu-latest

jobs:
- deployment: VMDeploy
  displayName: Deploy to RESOURCE-PC in VMenv with full syntax
  environment: 
    name: VMenv
    resourceType: virtualMachine
    resourceName: RESOURCE-PC # only deploy to the VM resource named RESOURCE-PC
  strategy:
    runOnce:
      deploy:   
          steps:
          - script: echo "Hello world"

Deployment strategy

In a deployment job, you apply a deployment strategy to define how to roll out your application. VMs support both the runOnce and the rolling strategies. For more information about deployment strategies and lifecycle hooks, see Deployment strategies.

Permissions

The first time you run the pipeline that uses the environment, you must grant permission for all runs of the pipeline to access the agent pool and the environment. Select the Waiting symbol next to the job on the pipeline run Summary screen, and then select Permit to grant the necessary permissions.

Add and manage tags

Tags are a way to target a specific set of environment VMs for deployment. When you specify tags in the environment keyword, the pipeline deploys only to environment VMs that have the tags applied.

There's no limit to the number of tags that you can apply to VMs. Tag names are limited to 256 characters each.

You can apply or remove tags by selecting the More actions icon next to the VM on the environment's Resources tab.

You can also apply tags interactively when you register the agent script on the VM.

If you specify multiple tags, the pipeline deploys only to VMs that include all the tags. The following example targets only VMs that have both the windows and prod tags. The pipeline doesn't deploy to VMs that have only one or none of the tags.

trigger: 
- main

pool: 
   vmImage: ubuntu-latest

jobs:
- deployment: VMDeploy
  displayName: Deploy to VM
  environment: 
    name: VMenv
    resourceType: virtualMachine
    tags: windows,prod # only deploy to VMs with both windows and prod tags
  strategy:
    runOnce:
      deploy:   
          steps:
          - script: echo "Hello world"

View deployment history

Select the Deployments tab of the environment page for complete traceability of commits and work items and a cross-pipeline deployment history per environment and resource.

Remove a VM from an environment

./config.sh remove

./config.cmd remove

Related content

• Create and target environments
• Environment - Kubernetes resource
• Deployment jobs
• YAML pipelines schema reference