DevOps is about increasing efficiency and eliminating barriers. There’s a lot of convenience in deploying directly from Visual Studio Team Services into the Azure cloud. With plugin based build and release pipelines, it’s very easy to quickly configure a release and see the results online. You can quickly configure a release to deploy to Azure; the wizards and settings will automatically configure the necessary permissions and credentials in the two systems. Everything just works … unless you’re running VSTS in a separate account or environment from the target Azure subscription. In this post, I’m going to walk you through the black art of manually connecting VSTS to an Azure subscription to enable automated release and deployment pipelines.
Getting started in VSTS
To demonstrate the problem and how to fix it, we’re going to create a very simple Release pipeline. In VSTS, begin by opening Build & Release. From there, you can choose Releases and create a new release definition by pressing the large “+” on the page. Choose to create a release definition.
Begin with an empty definition.
For the purposes of this demo, you do not need to associate it with any build artifacts. You can select Choose Later.
Next, add a task to the release. Choose to add an Azure File Copy task.
As you start to configure this task, the problem will become apparent. You can only select a Subscription configured to work with your VSTS instance. You will need to click Manage to begin the process of adding a new Service Endpoint to your VSTS account. A service endpoint is essentially a way to connect VSTS to an external system such as Azure. When you attempt to add a new Azure Resource Manager service endpoint, VSTS will display the details of the subscriptions it knows are available to you. If the Azure subscription you want to use is not automatically visible to VSTS, then you will have to configure the connection. This is done manually using the advanced settings. Near the bottom of the dialog, click the link in the instructions that says “use the full version of the endpoint dialog”.
Configuring this is not as difficult as it seems, but there are a few steps involved. Let’s walk through the fields and where you find those values in your Azure subscription. The Connection Name is a friendly name that will be displayed to you whenever you need to use the Azure service. I recommend that you consider making this an intuitive name, such as the name of the subscription. If Environment is available, this is the specific type of Azure cloud being connected. Unless you are using one of Microsoft’s Azure Government clouds, then you can use the default setting (AzureCloud). For the remaining steps, you will need to login to the Azure environment you are wanting to connect. Once logged in, you will be able to find and configure the remaining values.
Configuring Azure for VSTS
The Subscription ID and Subscription Name fields can be found by opening the Subscriptions blade. If you’re not sure where to find it, take advantage of the Search Resources feature found at the top of each page in the Azure portal. When you open the Subscriptions blade, the values you need will be displayed on the screen. Copy these two values to the dialog.
Next, we need to open the Azure Active Directory blade. Open the Properties menu blade. Copy the Directory ID field to the Tenant ID. The Tenant ID is a reference to the Azure Active Directory (AAD) instance within the subscription.
Next, we need to get values for the two fields related to the Service Principal. A Service Principal (SPN) is essentially an account registration which will have permissions within Azure. By assigning a principal and key, VSTS will be able to authenticate with Azure Active Directory. To do this, we need to create an application and register it within AAD.
While still in the Active Directory blade, open the App Registrations menu blade and select New application registration. In the Create dialog, give the application a friendly name, such as VSTS Connection. Use the default Application Type (Web app/API). The sign-on URL must be unique, but otherwise can have any value. I prefer to use a naming convention that indicates I’m using the application exclusively as an SPN from VSTS. After you have created the application, the Properties menu for the new application will show you the Application ID. Copy the value from Application ID to the Service Principal Client ID field.
The final value we need is the Service Principal Key. This key is an access key for your application to connect to Azure. Open the Keys menu in your newly created application. In the empty field, type a descriptive name for the key you are wanting to create. Set the expiration time for an appropriate amount of time. Press Save to commit your changes. The application’s key is displayed. Copy this value to Service Principal Key.
Although you have the values needed to configure VSTS, there is one more step – giving the application permissions on Azure. Without this step, VSTS will be able to connect to Azure but won’t have permission to utilize any of the resources. Each resource in Azure has a menu blade for Access control (IAM). Following a principal of least privilege, you might consider assigning the permissions at the Resource Group level. Unfortunately, you would find that the particular task we selected – File Copy – fails. In order to be able to use a storage account with just a name (no credentials), this task queries all of the available storage accounts in order to find the requested account. Next, it retrieves the connection details and keys. To do this requires permissions at the subscription level.
For this reason, VSTS SPNs usually have their permissions applied in the Subscription blade. When VSTS can connect and automatically configure the SPN, it will grant permission at this level. More specifically, it will assign the Contributor role, granting it more extensive access to the account. To keep everything simple, we will do the same.
Open the Subscription blade and select the targeted subscription. Within that blade, open the Access control (IAM) menu. Click Add to grant our application permission. Choose the Contributor role. Under select, type the name of the application that you created. At the time of this writing, there is an odd bug with auto-complete in Azure. You will have to type the complete name of the application in order for the auto-complete to locate your application. Once it appears, click the application to mark it as selected. Then, press Save to confirm your changes and confirm the updated permissions.
Return to VSTS and test your connection. At this point, the Service Endpoint should verify and show as able to connect.
You can now save the Endpoint and begin using this Azure subscription in your Build and Release tasks. Return to our File Copy task and refresh the subscription drop down. You will see your Azure subscription is now available.
Now you know how to connect external Azure accounts to your VSTS environment. Along the way, you’ve hopefully also gained some understanding of setting up an application in Azure and configuring it’s permissions. Happy DevOp’ing!