Why Configuring Service Endpoints In Visual Studio Team Services Is A Good Thing

First published on MSDN on Sep 30, 2016

Authored by Alex Mang

The entire DevOps story with the Microsoft Stack is expanding its reach to more and more services and with an ever-growing set of advanced features. During this article, I will cover the benefits and ways to configure Service Endpoints within either Visual Studio Team Services and Team Foundation Service, in order to create a highly coupled ALM story for your apps.

What are Service Endpoints?

Back in the days of Team Foundation Services (2013 and prior to that), everyone was asking for a way to make Release Management expand to other project types rather than .NET and VB/C++. Taken this feedback (along with many other requests) Microsoft rewrote Team Build. Personally, I believe the entire DevOps story using the Microsoft Stack has become more mature than ever and ready to solve the most complex requirements your application has. In order to achieve this type of extensibility, Team Build allows one to add features in two ways: (1) by installing extensions which can either be wrote and uploaded by yourself or by installed from the Visual Studio Marketplace or by (2) taking advantage of the TFX Command Line Interface which allows you to add custom designed tasks. The latter is especially useful when it comes to creating a single-task functionality as an atomic process part of the build or release definition, rather than leverage several tasks individually. This ensures that in the situation of build and release processes which have to do the same tasks over and over again a few times are easily configurable and thus reduces the error-prone nature of a highly-configurable workflow system, such as Team Build.

The beauty of these tasks are that they are not exclusively designed to Microsoft-specific products and services - in fact, most of the tasks which have to deal with external services will specify the external service's endpoint in the form of a connection setting which is team-project wide. Again, this helps prevent errors related to connection strings and such.

These connection settings are known as Service Endpoints and can be configured from the Settings pane of any team project, both in Visual Studio Team Services and Team Foundation Services, under the Services tab.

Interesting Facts About Configuring Service Endpoints

One of the most interesting Service Endpoints I ever had to configure were related to either Azure and Visual Studio Team Services - and between the two of them, I do have to admit that the latter seems like the most illogical one: why would you add within a Visual Studio Team Services tenant a set connection settings to... itself? I'll cover that in just a minute!

The shared opinion among ALM experts when it comes to release pipelines is that there should *ALWAYS* exist a least two environments (usually three!) to deploy the application two. In addition, in my personal opinion, it is absolutely necessary to make sure that these environments are exactly the same infrastructure-wise and therefore, should the architectural changes be incorrect, you will fail fast rather than late in the pipeline. Besides that, always make sure that there are no changes from the architectural perspective between these environments. A common way to use these environments is based on the reach and scope of the testing process. Usually, a DEV environment will be created first to make sure that besides the integration tests, the application which is due to be delivered is compliant to all the acceptance criteria; and considering that there's only so much you can do when it comes to integration testing, Selenium tests and so on, having a completely working environment to test upon from a dev's perspective is absolutely necessary.

If you deploy your application to Azure, whether you're deploying it to IaaS (VMs) or Web Apps, a connection to Azure will be necessary. Based on the task type, you will have to configure one of the following two Service Endpoints for Azure: Azure Classic or Azure Resource Manager. The difference comes from the nature of the service you're deploying or the type of cmdlets the tasks is going to call during its execution - of course, the difference itself comes from the changed nature of the entire Azure ecosystem.

Configuring a Service Endpoint For Azure Classic

There are two ways to configure a Service Endpoint for Azure Classic: credentials and certificate based. Here's how they work!

Credentials configuration steps

In order to configure an Azure Classic Service Endpoint using a set of credentials:

1. Type in a 'Connection Name' - this can be anything you want and will represent the friendly name shown in the tasks' (which require an Azure Classic Service Endpoint) properties. This does NOT represent the Azure Subscription name!

1. Select the Environment - commonly, you will select 'Azure Cloud' for this, but should you need to configure a Service Endpoint to any Chinese Azure regions, the German ones or the US Government ones, please select accordingly.

1. For the 'Server Url', just type in 'https://management.core.windows.net/' (actually, this should pop up by default). Should you deploy to Azure Stack instead of the Public Azure cloud, this is the setting you want to change!

1. Subscription ID represents the globally unique identifier of you subscription. You can copy this value even from within the Azure Portal, by opening up the subscriptions blade - it has the following format: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'

1. Type in the Subscription Name exactly as it shows in the Subscriptions blade in the Azure Portal. If you ever change the name of the subscription, make sure you update the Service Endpoint configuration accordingly - otherwise, the tasks dependent of this setting will fail.

1. Username and password are *NOT* the credentials a Microsoft Account, but for an Azure Active Directory Account (also known as any of the following Work or School Account, Organization Account, Office 365 Account) account, with administrator privileges in the directory the subscription is associated to.

Certificate Based configuration steps

Because of the nature of ever changing password of user credentials (hopefully!) and the requirement to use an elevated account part of the directory, I usually recommend against the aforementioned method. Instead, the use of a certificate based configuration is preferred. In order to configure an Azure Classic Service Endpoint using a certificate based configuration:

1. Type in the values for 'Connection Name', 'Environments', 'Server Url', 'Subscription ID' and 'Subscription Name' just like in the steps mentioned for the credentials-based connection.

1. For the 'Management Certificate' setting, head over to the https://manage.windowsazure.com/publishsettings webpage, select the directory associated to the subscription and click 'Download'. This will generate a new certificate, associate it to your subscription and transfer it over to your computer via a XML-based file with the .publishsettings extension. From within this file, locate the <Subscription> XML node with the value of the Name attribute is the name of your subscription and copy the value of the ManagementCertificate to your clipboard. Afterwards, paste this value in the 'Management Certificate' setting in the 'Add new Azure Classic Connection' pop-up window.

As a best practice, mark the name of the automatically-generated certificate correspondingly within the Azure Management Portal, so that you can easily locate it should you ever require to remove it. By default, the name of the certificate will map to the name of the subscription and it will be nearly impossible to tell which certificate to select when you want to have one revoked.

Configuring a Service Endpoint For Azure Resource Manager

Whilst adding a connection for Azure Classic might seem somewhat criptic because of the large number of setting and little available documentation, when it comes to ARM connections, a thorough blog post on MSDN explains the steps you need to take: https://blogs.msdn.microsoft.com/b/visualstudioalm/archive/2015/10/04/automating-azure-resource-group-deployment-using-a-service-principal-in-visual-studio-online-build-release-management.aspx .

As a quick review, please be reminded that if you've backed your Visual Studio Team Services tenant to Azure, you will automatically see the subscription ID and name as required fields - otherwise, go ahead and manually configure the integration of you VSTS tenant towards Azure. This can be either achieved by manually creating a Service Principal within the Azure Active Directory directory the subscription is associated to and afterwards by configuring the service principal as a subscription contributor - don't worry if this service principal doesn't show up automatically as it will right after you type in the name of the Service Principal.

Configuring a Service Endpoint For Visual Studio Team Services

Indeed, it might sound strange to configure a connection towards VSTS from the settings pane of a team project which exists inside the same VSTS tenant. However, if you want to take advantage of tasks related to web testing or load testing your application (which is another yet feature of VSTS), you will need to configure the connection to VSTS within the task itself. The curious part however is that the list of service endpoint types doesn't contain 'Visual Studio Team Services' (or any of it former names); instead, a generic service endpoint type is required.

When you configure a new Generic Connection, some settings are required:

1. For 'Connection Name' type in any name you find appropriate: this will be the friendly name that will show up in the list of existing generic connections

1. For Server Url, type in the secured HTTP root endpoint of your VSTS tenant, such as https:// <vststenant> .visualstudio.com .

1. For username and password/token, rather than typing in the Microsoft Account which hold the VSTS tenant values (like you'd be inclined to believe), you will have to type in the alternate credentials associated to your Visual Studio Profile. Remember, a Visual Studio Profile is the same across all VSTS tenants and therefore you will have to use this alternate credential set for all connections to any of your VSTS tenants.

In order to configure the alternate credentials, click on your name in the upper-right corner, select Security and click on the 'Alternate authentication credentials' link in the upper-left corner. Make sure the 'Enable alternate authentication credentials' setting is checked, type in a name and the chosen password twice. Click 'Save' and you're all set.

Conclusions

The use of Service Endpoints enables many new scenarios and allows TFS and VSTS communicate with external services. It may sound strange that VSTS requires a connection both towards Azure (considering that VSTS is commonly backed by an Azure account, as a best practice) and VSTS (because... what?!), but in fact this enables even more scenarios such as one in which to share a single VSTS tenant and Azure subscription to pay for cloud load tests but still isolate team projects among multiple VSTS tenants.

Want to keep the conversation going? Leave a comment below!