Edit

Environment - virtual machine resource

  • Article
  • 5 minutes to read

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

Use virtual machine (VM) resources to manage deployments across multiple machines with YAML pipelines. VM resources let you install agents on your own servers for rolling deployments.

VM resources connect to environments. After you define an environment, you can add VMs to target with deployments. The deployment history view in an environment provides traceability from your VM to your pipeline.

Prerequisites

You must have at least a Basic license and access to the following areas:

  • the repository connected to your pipeline
  • the VM you want to connect to the environment

For more information about security for Azure Pipelines, see Pipeline security resources.

To add a VM to an environment, you must have the Administrator role for the corresponding deployment pool. A deployment pool is a set of target servers available to the organization. Learn more about deployment pool and environment permissions.

Note

If you are configuring a deployment group agent, or if you see an error when registering a VM environment resource, you must set the PAT scope to All accessible organizations.

Create a VM resource

Note

You can use this same process to set up physical machines with a registration script.

The first step in adding a VM resource is to define an environment.

Define an environment

  1. Select Create environment or New environment, depending on whether it's your first environment.
  2. Add a Name (required) for the environment and a Description.
  3. Save the new environment.

Add a resource

  1. Select your environment and choose Add resource.

  2. Select Virtual machines for your Resource type. Then select Next.

    Add an environment.

  3. Choose Windows or Linux for the Operating System.

  4. Copy the registration script. Your script will be a PowerShell script if you've selected Windows and a Linux script if you've selected Linux.

    Add a virtual machine.

  5. Run the copied script on each of the target virtual machines that you want to register with this environment.

    • If you're installing on Windows, you'll need to run the script an PowerShell administrator.
    • If you're installing on Linux, you'll need to have permission to download and run executable scripts.

    Note

    • The Personal Access Token (PAT) for the signed-in user gets included in the script. The PAT expires on the day you generate the script.
    • If your VM already has any other agent running on it, provide a unique name for agent to register with the environment.
    • To learn more about installing the agent script, see Self-hosted Linux agents and Self-hosted Windows agents. The agent scripts for VM resources are like the scripts for self-hosted agents and you can use the same commands.

  6. Once your VM is registered, it appears as an environment resource under the Resources tab of the environment.

  7. To add more VMs, copy the script again. Select Add resource > Virtual machines. The Windows and Linux scripts are the same for all the VMs added to the environment.

  8. When the VM script is successfully installed, your VM appears in the list of resources for the environment.

    View resources.

Use VM in pipelines

Target VMs in your pipeline by referencing the environment. By default, the pipeline job runs for all of the VMs defined for an environment.

trigger: 
- main

pool: 
   vmImage: ubuntu-latest

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

Note

The resourceType values are case sensitive. Specifying the incorrect casing will result in no matching resources found in the environment. See the YAML schema for more information.

You can select a specific virtual machine from the environment to only receive the deployment by specifying it by its resourceName. For example, to target deploying only to the Virtual Machine resource named USHAN-PC in the VMenv environment, add the resourceName parameter and give it the value of USHAN-PC.

trigger: 
- main

pool: 
   vmImage: ubuntu-latest

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

To learn more about deployment jobs, see the YAML schema.

Add and manage tags

Tags give you a way to target a set of specific VMs in an environment for deployment. You can add tags to the VM as part of the interactive registration script or through the UI. Tags are each limited to 256 characters. There's no limit to the number of tags that you can use.

Add or remove tags in the UI from the resource view by selecting More actions for a VM resource.

Set VM tags.

When you select multiple tags, VMs that include all the tags get used in your pipeline. For example, this pipeline targets VMs with both the windows and prod tags. If a VM only has one of these tags, it's not targeted.

trigger: 
- master

pool: 
   vmImage: ubuntu-latest

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

Apply deployment strategy

Apply a deployment strategy to define how your application gets rolled out. The runOnce strategy and the rolling strategy for VMs are both supported. For more information about deployment strategies and life-cycle hooks, see Deployment jobs/Deployment strategies.

View deployment history

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

VMDeployments_view

Remove a VM from an environment

Windows environment

To remove VMs from a Windows environment, run the following command. Ensure you do the following tasks:

  • Run the command from an administrator PowerShell command prompt
  • Run the command on each machine
  • Run the command in the same folder path as the environment registration command was run
./config.cmd remove

Linux environment

To remove a VM from a Linux environment, run the following command on each machine.

./config.sh remove

Known limitations

When you retry a stage, it reruns the deployment on all VMs and not just failed targets.