INSTALL.md

GoCD Microsoft Azure Elastic Agent Plugin

The plugin needs to be configured with elastic profile configurations in order to create VMs on azure.

Table of Contents

• Prerequisites
• Installation
• Configuration

Prerequisites

Go Server

• The GoCD server version 18.10.0 or higher.

Azure subscription

• You will need a valid Azure subscription with privileges to create Virtual machines inside it.

• There should be a virtual network created in the azure subscription, go-agent virtual machines will be created inside it.

  A virtual network enables Azure resources, such as virtual machines (VM), to communicate privately with each other and with the internet. Please note the EA created will need to communicate with your GoCD server.

  az network vnet create --name gocd-virtual-network --resource-group gocd-resource-group --subnet-name default

  After the successful creation of the virtual network please note the Virtual Network ID from the response which will be similar to

  { 
    "id": "/subscriptions/3986fa0c-d463-4qf7-b508-cc38db097f58/resourceGroups/gocd-resource-group/providers/Microsoft.Network/virtualNetworks/gocd-virtual-network"
  }

  Refer azure documentation for managing your Virtual Networks

• Create a new resource group which will contain all the go-agent virtual machines. A resource group is a container that holds related resources for an Azure solution. GoCD uses the resource group to create as a container in which it creates your Azure EA.

  az group create --name gocd-resource-group --location "Central US"

  On successful creation of a Resource Group

  {
      "id": "/subscriptions/3386fa3c-d463-4cf7-b508-cc38db097e58/resourceGroups/gocd-resource-group",
      "location": "centralus",
      "managedBy": null,
      "name": "gocd-resource-group",
      "properties": {
          "provisioningState": "Succeeded"
      },
      "tags": null
  }

  Refer azure documentation for managing your resource groups.

• Create a service principal with access to create network interfaces, virtual machines, network security groups and managed disks in the region of the virtual network. The service principal credentials are required to setup the plugin.

  Service principals are separate identities that can be associated with an account. The service principal [clientid/secret] is used for sdk authentication

  az ad sp create-for-rbac --name ServicePrincipalName --password PASSWORD

  On successful creation of a Service Principal

  {
      "appId": "f6a9bfde-414f-4700-a10c-07eafb7f1eaa",
      "displayName": "ServicePrincipalName",
      "name": "http://ServicePrincipalName",
      "password": "PASSWORD",
      "tenant": "cf03984b-4fa1-465f-b731-wecea9eece05"
  }

  Refer azure documentation for creating a service principal.

  By default a service principal will have a Contributor role. For more fine grained access control, ensure that the service principal has the following access:

  
  Microsoft.Compute/virtualMachines/*
  Microsoft.Network/networkInterfaces/*
  Microsoft.Compute/disks/*
  Microsoft.Compute/locations/*
  Microsoft.Resources/subscriptions/resourceGroups/read
  Microsoft.Network/virtualNetworks/read
  Microsoft.Network/virtualNetworks/subnets/read
  Microsoft.Network/virtualNetworks/subnets/join/*
  Microsoft.Network/networkSecurityGroups/read"
  Microsoft.Network/networkSecurityGroups/join/*
  

You can create a custom role using the below template. Ensure this role is assigned to the service principal.

  
  {
    "Actions": [
        "Microsoft.Compute/virtualMachines/*",
        "Microsoft.Network/networkInterfaces/*",
        "Microsoft.Compute/disks/*",
        "Microsoft.Compute/locations/*",
        "Microsoft.Resources/subscriptions/resourceGroups/read",
        "Microsoft.Network/virtualNetworks/read",
        "Microsoft.Network/virtualNetworks/subnets/read",
        "Microsoft.Network/virtualNetworks/subnets/join/*",
        "Microsoft.Network/networkSecurityGroups/read",
        "Microsoft.Network/networkSecurityGroups/join/*",
        "Microsoft.Resources/subscriptions/locations/read"
    ],
    "AssignableScopes": [
        "/subscriptions/{subscriptionId}"
    ],
    "DataActions": [],
    "Description": "Role for service principal used for GoCD Azure elastic agent plugin",
    "IsCustom": true,
    "Name": "gocd-azure-plugin-scope",
    "NotActions": [],
    "NotDataActions": []
}
  

Some useful commands

1. az group list : List resource groups for a user account
2. az account list-locations : List of allowed locations for deploying resources for an account
3. az network vnet list : List of virtual networks for a user account
4. az ad sp list --display-name : Details of the service principal

Related help topics

1. Getting Started with Microsoft Azure
2. Azure virtual machines
3. Azure service principal
4. Custom roles

Installation

• Copy the file build/libs/azure-elastic-agent-plugin-VERSION.jar to the GoCD server under ${GO_SERVER_DIR}/plugins/external and restart the server.
• The GO_SERVER_DIR is usually /var/lib/go-server on Linux and C:\Program Files\Go Server on Windows.

Configuring the Azure Elastic Agent Plugin

1. Configure the GoCD Azure Elastic Agent Plugin Settings: The plugin settings are used to provide global level configurations for the plugin. Configurations such as Azure credentials, Azure settings like Virtual Network, region, Go Server configuration are provided in plugin settings.

   

2. Configure an Elastic Profile for GoCD Azure Elastic Agent Plugin: The Elastic Agent Profile is used to define the configuration of the Azure instance. The profile is used to configure the platform, VM image, size and the custom scripts to be run on the instance.

   

3. Assign the Elastic Profile to a job