Deploying Docker EE on Azure & solving common issues

We are in the era of cloud computing. Many customers are rushing to accelerate their digital transformation. In the same time the cloud providers are getting better and better by the minute. Literally!

That leaves a lot of the IT leaders no choice but to think carefully about their strategies to move to the cloud. One of the things that is very popular now is containers.

In the context of digital transformation and cloud migration its appealing for the following reasons:

1- Provides an abstraction layer from the underlying infrastructure layer.

That gives organizations the flexibility of moving their workloads easily and host them in different infrastructure anytime whether it is on-premises or in the cloud. So, you are not locked-in to a specific cloud provider nor to your own on-premises datacenter.

2- Gives you the ability to optimize the usage of your infrastructure by increasing the density of your workloads

3- It’s a great architecture for implement continuous integration, continuous deployment pipeline.

One of the great containers platforms out there is Docker. It’s supported in Azure. You can deploy a Docker DC/OS container cluster leveraging the Azure Container Service.

You also have the option of Deploying the enterprise version of Docker that is available on the Marketplace.

In this article, I will cover how to deploy a Docker EE (Standard/Advanced) cluster in Azure and I will touch on a common error that users fall into that breaks their deployment.

The deployment of a Docker EE cluster in Azure is straight forward.

To deploy a Docker EE cluster, you need the following

1. Azure subscription
2. Azure Application principal
3. RSA SSH Key

Azure subscription

This will allow you to leverage the Azure cloud services and create virtual machines, database …etc. You need a subscription to be able to deploy the virtual machines and other resources required to host your Docker cluster. Luckily you can get a free trail one here.

Azure Application principal

Azure App principal aka Azure AD Application refers to an identity object (resource) that can be created in Azure AD that allows applications (Code or script) to authenticate and be authorized (similar to Azure AD users) to access Azure resources or any resources that Azure AD integrates with.

In simple terms, think of it as a service account used by applications to access resources that are linked with your Azure AD directory. Similar to a service account, an App principal will have the following:

• Principal name --> User Name
• App principal ID or (App ID) --> User ID
• App Secret --> Password

Check the additional resources section at the end of the article for link to a resource with more details.

Why do we need an App Principal for a Docker cluster?

It’s used by the Docker orchestrator to manage your cluster in Azure. Docker uses the App principal (Service principal) to be authorized to access the Azure subscription via the Azure APIs to change your cluster underlying infrastructure when required. For example, scale up or down the number of nodes (VMs) and/or configure the azure load balancer.

RSA SSH Key

Used to SSH to your manager nodes.

Steps to deploy a Docker EE cluster

1. Create an Azure resource group
2. Create an App Principal
3. Assign the App Principal from step #2 a permission on the group created on step #1
4. Create your DockerEE cluster using the app principal created in step #2 and select the resource group created in step #1

 

First: Create a resource group

1- Go to https://Portal.Azure.com

2- Click on the + sign from the left nav to add a new resource | select or type resource group

3- Provide Resource group name, Subscription and Resource group location

             

Create resource group [Azure CLI]

 

 ahmed@Azure:~$ az group create -n DockerEECDemo --location southcentralus

 

Second: Create an App principal

 

1. Go to https://Portal.Azure.com
2. Click (or search for) the Azure Active Directory icon from the left nav | select or type App registration | New application registration
3. Provide a Name, leave the default settings of Application type = “Web app/API” and provide any random URL at Sign-on URL field
4. Press Create

 

Then you need to issue a key for the app principal

1. Click on Settings | Keys
2. Type a Description for the key and choose the Expires time | Press Save
3. Copy the Application ID = [Principal App ID] & Key Value = [Principal App Secret] to somewhere safe as you will need to use them later

 

Third: Assign permission to the new App Principal to the resource group

 

This step is forgotten by most people. If this step is not performed and your App principal doesn’t have inherited contribute permissions on the resource group, your DTR portal provisioning will silently fail and will never load.

Steps to grant the App principal contribute permission

1. Go to the resource group you have created | Click on Access Control (IAM) from the left nav | Add
2. Select the role Contributor | find the created app principal using the field Select | select the right one from the list of results
3. Press Save

Forth: Create DockerEE cluster

 

Now you are ready to create your DockerEE cluster. Assuming you already has an RSA SSH key pair generated. If not, please follow this article for directions on how to get that done.

1- Go to https://Portal.Azure.com

2- Click on the + sign from the left nav to add a new resource | search for Docker EE for Azure (Standard/Advanced)

3- Select Docker EE for Azure (Standard/Advanced) from the search results

4- Press Create

5- Provide the following values

• Swarm Name: dockerswarm
• Service Principal App ID: You should have that from the earlier steps
• Service Principal App Secret: You should have that from the earlier steps
• SSH public key: Your RSA SSH public Key
• Subscription: Your azure subscription name
• Resource group: The resource group created in the steps above
• Location: Select which Azure region you want your cluster deployed to. Usually this defaults to the location settings of the resource group.

6- Press OK

7- Then provide the rest of the values including the Docker Datacenter License Key. Be aware that the key doesn’t get validated, so it will not complain if you put in the wrong key. You need to enter the entire text from the license file you received from Docker. You can update the key after the cluster is created. Check the common issues section at the end of the article for more details.

8- Press OK

9- Go over the summary and if everything looks good press OK

10- Press Purchase

 

The provisioning time will be different depending on the region and time of provisioning but usually its done between 5-10 minutes. The azure portal will notify you when the cluster has been provisioned successfully.

You may need to wait another 15 minutes or so after the cluster is provisioned to allow for the DTR to be configured.

You can navigate to the resource group where you have created your Docker cluster to inspect all the Azure resources created:

Now you have successfully deployed a DockerEE cluster

 

Common questions

 

1. How can I find out what the DTR URL is?

Navigate to the resource group where the cluster is created as shown above and find a resource of type Public IP address with the name dockerswarm -dtrLoadBalancer-public-ip

Click on that resource | then copy the DNS name

You can browse the URL: https://dtrlb-nlo5xsvfj5ty2.southcentralus.cloudapp.azure.com

That should prompt you to login …

2. Which storage account the DTR is using? How can I change it?

You can see the Azure storage account information that is used by DTR and change it from the DTR portal under Settings | Storage

https://DTR_URL/admin/settings/storage

 

3. Can I script the deployment of the cluster?

Yes. Docker have created an excellent bash script for that.

You run the following command:

 $ docker run -ti docker4x/create-sp-azure sp-name [rg-name rg-region]

Then this using the Azure CLI you run this command:

 $ az group create  --name DockerGroup --location centralus --deployment-name docker.template --template-file <templateurl>

 

Common issues

 

1. You get the following error at the homepage of the DTR portal “Warning: Unlicensed copy. Please register your license on the Settings page”

Resolution

This means your license key is invalid. You need to update the license key as follows:

Navigate to the settings page | General tab| Press on Apply new license

https://DTR_URL/admin/settings

Select the new license key (*.lic) file and press Open

Once its loaded successfully, it should look like this:

3. Trying to load the DTR portal but its not working (getting timeout error)

Resolution

Make sure you have waited at least 15 mins after the cluster has been deployed to allow Docker to provision and configure the load balancer and IP config for the DTR endpoint.

If it still doesn’t work, make sure you have granted access the App principal used in creating the cluster to the resource group where the cluster has been provisioned.

If not, you can fix the permissions and redeploy a new cluster. Check the steps above for provisioning a new Docker cluster.

4. The Docker cluster deployment job failed due to a VM didn’t start on time

This happens when a VM takes longer than expected to start so the deployment job timesout.

Resolution

If that happens I would suggest deleting the cluster and re-deploying a new one. Obviously, you can go a restart the VM (that failed to start on time), however, from my experience that results on issues in configuring DTR. So it’s better to re-deploy.

Additional resources

• Docker EE best practices & considerations
• Application and service principal objects in Azure Active Directory
• Docker for Azure Setup & Prerequisites

Comments

• Anonymous
  April 18, 2017
  Thanks for the detailed article. I have few questions if you can help with:1. I've created a cluster with 3 masters and 5 worker nodes. I don't see a way to ssh into the agent/worker nodes? However, for master the SSH Load balancer can be used2. When I compare the deployment with ACS - Swarm. I could find it to be better, as Masters can also be scaled at later point on time. But in ACS, the number of masters should be fixed while creating the cluster and can not be changed later. Not sure if this expected in ACS release in near future.Thanks,Sachin