Important: This plug-in is maintained by the Jenkins community and won’t be supported by Microsoft as of February 29, 2024.
A Jenkins Plugin to create Jenkins agents in Azure Virtual Machines (via Azure ARM template).
Supported features:
You can install/update this plugin in Jenkins update center (Manage Jenkins -> Manage Plugins, search Azure VM Agents Plugin).
You can also manually install the plugin if you want to try the latest feature before it's officially released. To manually install the plugin:
mvn package
azure-vm-agents.hpi
in target
folder of your repo, click Upload.To use this plugin to create VM agents, first you need to have an Azure Service Principal in your Jenkins instance.
Select the retention strategy
Retention time define the time of hour before automatically deleting since the agent created. And the pool size define the agent pool size you want to maintain. If you change your cloud name, template name or most of parameters (e.g. Region, Image), we will delete the existing agents at once and provision the new one according to your new template. But if you only change your Retention Time or Pool Size, we will only scale in, scale out or do nothing for you.
After you configured an Azure VM agent template, when you run a new Jenkins job, Jenkins will automatically provision a new Azure VM only if there is no executor available.
A more common scenario is you want to restrict some jobs to always be running on a particular VM agent instead of Jenkins controller. To achieve that:
For how to select agent in pipeline, refer to this doc.
The built-in image only has a clean Windows or Ubuntu OS and some tools like Git and Maven installed, in some cases, you may want to have more customization on the image. To use a custom image:
In Image Configuration, select "Use Advanced Image Configurations".
Choose between two possible alternatives:
For the launch method, select SSH or JNLP.
We recommend to use SSH rather than connecting it to the controller, it's simpler to setup and get much clearer logs.
When using the Inbound agent launch option, ensure the following:
- Jenkins URL (Manage Jenkins -> Configure System -> Jenkins Location)
- The URL needs to be reachable by the Azure agent, so make sure to configure any relevant firewall rules accordingly.
- TCP port for Inbound agents (Manage Jenkins -> Configure Global Security -> Enable security -> TCP port for inbound agents).
- The TCP port needs to be reachable from the Azure agent launched with connecting to the controller. It is recommended to use a fixed port so that any necessary firewall exceptions can be made.
If the Jenkins controller is running on Azure, then open an endpoint for "TCP port for Inbound agents" and, in case of Windows, add the necessary firewall rules inside virtual machine (Run -> firewall.cpl).
For the Initialization Script, you can provide a script that will be executed after the VM is provisioned. This allows to install any app/tool you need on the agent. Please be aware you need to at least install JRE if the image does not have Java pre-installed. We prepared a sample script for Linux via SSH, Windows via SSH and Windows via connecting to the controller. Please find details in help button.
If you hit the storage scalability limits for your custom images on the storage account where the VHD resides, you should consider using the agent's temporary storage or copy your custom image in multiple storage accounts and use multiple VM templates with the same label within the same agent cloud.
For more details about how to prepare custom images, refer to the below links:
Init script should finish in 20 minutes (this time can be configured in Deployment Timeout setting of Azure Profile Configuration). It's not recommended to run complex init script, if the init script is expected to take a long time to complete, it is recommended to use a custom-prepared image.
If you choose Use Advanced Image Configurations, you can click on Advanced button where you can find more VM configurations:
Virtual Network Name, Virtual Network Resource Group Name and Subnet name: by default the VM does not belong to any virtual network, you can provide one if you want the VM to be in a virtual network for network security. Please be noted the virtual network must exist.
Make VM agent IP private: by default the plugin will create a public IP for the VM so it's public accessible on internet. Check this option if you don't want the public IP to be created.
Make VM agent IP private can make the VM more secure, but if you configured to use SSH to launch agent, Jenkins controller needs to be able to access the VM. So in this case you need to also specify virtual network and subnet name so the agent and Jenkins master are in the same subnet.
Network Security Group Name: add the VM to a network security group.
JVM Options: specify JVM options.
Number of Executors: specify the number concurrent builds that a VM agent can run at the same time.
Disable template: disable this template temporarily.
This plugin can be fully configured by the Jenkins Configuration as Code plugin.
Configure the plugin using the UI initially and then export the configuration and tweak to your needs
It is recommended that you use the configuration-as-code
plugin for automating the plugin configuration. If you can't do that for some reason then you can use groovy script
Here is a sample groovy script that creates a new Azure cloud and VM template. You can run it in Manage Jenkins -> Script Console.
//Configure cloud with built-in image
import com.microsoft.azure.vmagent.builders.*
def myCloud = new AzureVMCloudBuilder()
.withCloudName("myAzure")
.withAzureCredentialsId("<your azure credential ID>")
.withNewResourceGroupName("<your Resource Group Name>")
.addNewTemplate()
.withName("ubuntu")
.withLabels("ubuntu")
.withLocation("East US")
.withVirtualMachineSize("Standard_DS2_v2")
.withNewStorageAccount("<your Storage Account Name>")
.addNewBuiltInImage()
.withBuiltInImageName("Ubuntu 16.14 LTS")
.withInstallGit(true)
.withInstallMaven(true)
.withInstallDocker(true)
.endBuiltInImage()
.withAdminCredential("<your admin credential ID>")
.endTemplate()
.build()
Jenkins.getInstance().clouds.add(myCloud)
//Configure cloud with mutli-template of advanced images
import com.microsoft.azure.vmagent.builders.*
def firstTemplate = new AzureVMTemplateBuilder()
.withName("first-template")
.withLabels("ubuntu")
.withLocation("East US")
.withVirtualMachineSize("Standard_DS2_v2")
.withNewStorageAccount("<your Storage Account Name>")
.addNewAdvancedImage()
.withReferenceImage("Canonical", "UbuntuServer", "16.04-LTS", "latest")
.withInitScript("sudo add-apt-repository ppa:openjdk-r/ppa -y \n" +
"sudo apt-get -y update \n" +
"sudo apt-get install openjdk-8-jre openjdk-8-jre-headless openjdk-8-jdk -y")
.endAdvancedImage()
.withAdminCredential("<your admin credential ID>")
.build()
def myCloud = new AzureVMCloudBuilder()
.withCloudName("myAzure")
.withAzureCredentialsId("<your azure credential ID>")
.withNewResourceGroupName("<your Resource Group Name>")
.addToTemplates(firstTemplate)
.addNewTemplate()
.withName("second-template")
.withLabels("windows")
.withLocation("Southeast Asia")
.withVirtualMachineSize("Standard_DS2_v2")
.withNewStorageAccount("<your Storage Account Name>")
.addNewAdvancedImage()
.withReferenceImage("MicrosoftWindowsServer", "WindowsServer", "2016-Datacenter", "latest")
.endAdvancedImage()
.withAdminCredential("<your admin credential ID>")
.endTemplate()
.build()
Jenkins.getInstance().clouds.add(myCloud)
//inherit existing template
import com.microsoft.azure.vmagent.builders.*
import com.microsoft.azure.vmagent.*
AzureVMAgentTemplate baseTemplate = new AzureVMTemplateBuilder()
.withLocation("Southeast Asia")
.withVirtualMachineSize("Standard_DS2_v2")
.withStorageAccountType("Premium_LRS")
.withNewStorageAccount("<your Storage Account Name>")
.addNewAdvancedImage()
.withReferenceImage("Canonical", "UbuntuServer", "16.04-LTS", "latest")
.endAdvancedImage()
.withAdminCredential("<your admin credential ID>")
.build()
def myCloud = new AzureVMCloudBuilder()
.withCloudName("myAzure")
.withAzureCredentialsId("<your azure credential ID>")
.withNewResourceGroupName("<your Resource Group Name>")
.addNewTemplateLike(baseTemplate)
.withName("inherit")
.withLabels("inherit")
.addNewAdvancedImageLike(baseTemplate.getAdvancedImageInside())
.withInitScript("sudo add-apt-repository ppa:openjdk-r/ppa -y \n" +
"sudo apt-get -y update \n" +
"sudo apt-get install openjdk-8-jre openjdk-8-jre-headless openjdk-8-jdk -y")
.endAdvancedImage()
.endTemplate()
.build()
Jenkins.getInstance().clouds.add(myCloud)
This sample only contains a few arguments of builder, please find all the arguments in folder builders.
If you can't tell from validation why a deployment does not work you can enable additional logging.
The plugin creates a Jenkins logger called Azure VM Agent (Auto)
, update that to FINE
level and re-run the agent provisioning.
The ARM template which is used to deploy resources will now show up.
More information on Jenkins logs can be found in the Jenkins documentation for Viewing logs.