Tutorial: Use Azure Container Instances as a Jenkins build agent


Many Azure services have Jenkins plug-ins. Some of these plug-ins will be out of support as of February 29, 2024. Azure CLI is the currently recommended way to integrate Jenkins with Azure services. For more information, refer to the article Jenkins plug-ins for Azure.

Azure Container Instances (ACI) provides an on-demand, burstable, and isolated environment for running containerized workloads. Because of these attributes, ACI makes a great platform for running Jenkins build jobs at a large scale. This article shows you how to deploy an ACI and add it as a permanent build agent for a Jenkins controller.

For more information on Azure Container Instances, see About Azure Container Instances.


Prepare the Jenkins controller

  1. Browse to your Jenkins portal.

  2. From the menu, select Manage Jenkins.

  3. Under System Configuration, select Configure System.

  4. Verify that the Jenkins URL is set to the HTTP address of your Jenkins installation - http://<your_host>.<your_domain>:8080/.

  5. From the menu, select Manage Jenkins.

  6. Under Security, select Configure Global Security.

  7. Under Agents, specify Fixed port and enter the appropriate port number for your environment.

    Configuration example: Configure TCP port

  8. Select Save.

Create Jenkins work agent

  1. Browse to your Jenkins portal.

  2. From the menu, select Manage Jenkins.

  3. Under System Configuration, select Manage Nodes and Clouds.

  4. From the menu, select New Node.

  5. Enter a value for Node Name.

  6. Select Permanent Agent.

  7. Select OK.

  8. Enter a value for Remote root directory. For example, /home/jenkins/work

  9. Add a Label (Labels are used to group multiple agents into one logical group. An example of a label would be linux to group your Linux agents.) with the value of linux.

  10. Set Launch method to Launch agent by connecting to the master.

  11. Verify that all required fields have been specified or entered:

    Example Jenkins agent configuration

  12. Select Save.

  13. On the agent status page, you should see the JENKINS_SECRET and AGENT_NAME. The following screen shot shows how to identify the values. Both values are needed when you create the Azure Container Instance.

    The build-agent secret is displays after its successful creation.

Create Azure Container Instance with CLI

  1. Use az group create to create an Azure resource group.

    az group create --name my-resourcegroup --location westus
  2. Use az container create to create an Azure Container Instance. Replace the placeholders with the values obtained when you created the work agent.

    az container create \
      --name my-dock \
      --resource-group my-resourcegroup \
      --ip-address Public --image jenkins/inbound-agent:latest \
      --os-type linux \
      --ports 80 \
      --command-line "jenkins-agent -url http://jenkinsserver:port <JENKINS_SECRET> <AGENT_NAME>"

    Replace http://jenkinsserver:port, <JENKINS_SECRET>, and <AGENT_NAME> with your Jenkins controller and agent information. After the container starts, it will connect to the Jenkins controller server automatically.

  3. Return to the Jenkins dashboard and check the agent status.

    Agent has started successfully


    Jenkins agents connect to the controller via port 5000, ensure that port is allowed inbound to the Jenkins Controller.

Create a build job

Now, a Jenkins build job is created to demonstrate Jenkins builds on an Azure container instance.

  1. Select New Item, give the build project a name such as aci-demo, select Freestyle project, and select OK.

    Box for the name of the build job, and list of project types

  2. Under General, ensure that Restrict where this project can be run is selected. Enter linux for the label expression. This configuration ensures that this build job runs on the ACI cloud.

    "General" tab with configuration details

  3. Under Build, select Add build step and select Execute Shell. Enter echo "aci-demo" as the command.

    "Build" tab with selections for the build step

  4. Select Save.

Run the build job

To test the build job and observe Azure Container Instances manually start a build.

  1. Select Build Now to start a build job. Once the job starts you'll see a status that's similar to the following image:

    "Build History" information with job status

  2. Click build #1 in the Build History.

    "Console Output" view the build output from the console in the Build History

  3. Select Console Output to view the builds output.

    "Console Output" view the build output from the console in the builds output

Next steps