Environment - virtual machine resource

Azure Pipelines | 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.

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: ContosoDeploy
   resourceType: VirtualMachine
  strategy:
     runOnce:
        deploy:   
          steps:
            - script: echo "Hello world"

You can select specific sets of virtual machines from the environment to receive the deployment with tags. For example, if you only want to deploy to resources with the windows tag, add the tags parameter and the value windows to your pipeline.

trigger: 
- main

pool: 
   vmImage: ubuntu-latest

jobs:
- deployment: VMDeploy
  displayName: Deploy to VM
  environment: 
    name: ContosoDeploy
    resourceType: VirtualMachine
    tags: windows # only deploy to virtual machines with this tag
  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 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: ContosoDeploy
    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

VMjobs_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.