Create a Docker Swarm cluster using Azure Container Service

Feel free to contact me on Twitter @jcorioland if you have any question about this article

Edit : this post has been updated for the Azure Container Service General Availiblity. See announcement here.


Microsoft has announced the general availability of Azure Container Service (ACS) that allows to deploy in an easy way a cluster of virtual machines that can host containers.

If you have not heard about Azure Container Service yet, you may want watch these videos first:

Azure Container Services supports two different orchestrators for the cluster

  • Docker Swarm: It uses the native Docker stack so you can directly use Docker commands to deploy Docker containers.
  • DC/OS: a datacenter operating system that can run containers in different formats, inluding Docker images. DC/OS is also used to deploy and run well known distributed systems like HDFS, Spark, Kafka, Cassandra… and is used at scale by organizations like AirBnb, Twitter, Netflix…

In this blog post, I will explain how you can use Azure Container Service to deploy in a few steps a Docker Swarm based cluster in Azure but if you want to deploy a DC/OS one, the procedure is very similar.

Generate an SSH RSA Key

Microsoft is working on the implementation of a container technology for the next version of Windows Server, but Azure Container Service supports only Linux workloads currently, so you will need an SSH key to connect the cluster once it is created. There are several ways to create a new key, depending on the system you are running on.

Because I am running Windows, I will detail the process to generate your key on this system. If you are running Linux on Mac and don’t know how to generate SSH keys, check this article on the GitHub documentation.

I have chosen to use the GitHub for Windows tools, because they are super easy to use. Once installed, just launch Git Bash, type ssh-keygen in the console and press Enter:


By default, ssh-keygen creates the public/private rsa key pair in a .ssh folder in your user’s profile root. The default name for these files are id_rsa (private) and (public) but you can choose to override by the name of your choice:


Press enter. You will be asked for a passphrase to protect your key.

Note: keep your passphrase in mind or somewhere secure, you will be asked for it when connecting to the cluster using SSH!

Once done, check the two files have been generated:


You are now ready to create your first cluster using Azure Container Service!

Note: if you are running the last Windows Insider version of Windows 10, you can now run Bash on Ubuntu on Windows ! So you don’t need to install GitHub for Windows. Just open a Bash shell and use the ssh tools directly:


Create a new Docker Swarm cluster on Azure Container Service

You can create a new Azure Container Service instance using the Azure portal, Azure CLI or PowerShell. In this blog post, I will focus on the Azure Portal.

Go to and log in with your Azure Account. Click the + New button and search for “container”:


Click on Azure Container Service. In the results view, click on the Azure Container Service line:


Then, click on the Create button. An assistant will open to help you to configure your new cluster.

In the first step, you have to enter the name of the user that will be administrator of the cluster and past de SSH public key that has been generated previously. You also have to choose the Azure subscription, a resource group (create a new one is recommanded) and the location where the cluster will be deployed:


Click OK to go to step 2 where you can choose between the two orchestrators: DC/OS or Swarm (the one I have selected here):


In the next step you have to set some settings for Azure Container Service, like the number of masters, nodes, the virtual machines size to use and a DNX prefix that will be used on each resource that will be created:


Click OK and wait for the final validation. You can also download the Azure Resource Manager template that has been generated by the portal. You will be able to use this template if you want to deploy another cluster using Azure CLI or PowerShell:


In the last section, click the Create button. Depending on the number of masters/agents you have asked for, the cluster creation may take a little while…

Once the deployment is completed, you can access your new Azure Container Service:


For now, the Container Service view of the portal has no special feature, but you can click on the resource group link to browse all the resources that have been created:


Click on the Resources pane to get a full view of these resources.

In the Essentials pane, click on the last deployment to get more information about it. In the Deployment History section click on the last entry to get the deployment’s output information:


This pane displays a summary of your cluster and you can also get the ssh command that will allow you to connect to the master nodes.

Connect to the Swarm master virtual machine

Connecting to the swarm master is really simple using the SSH command in the output information produced by the deployment, as explained above.

If you are on Linux or Mac, open a terminal. If you are on Windows, you can continue to use Git Bash that provides also an SSH client.

Just paste the command copied from the portal:


Note: if you have not used the default name / directory when generating your SSH key in the first step of this blog post, you should indicate the path to the private key to the ssh command.

You will be asked to enter your passphrase and then, you are connected to the Swarm master:


Once connected, you can use the Docker command to work with your Swarm cluster. The Docker Swarm socket is listening to the endpoint. For exemple, you can type the command docker info with the -H option to get information about your Swarm cluster:


Deploying your first Docker container

Now that your cluster in ready, you can deploy your first Docker container! In this sample I have chosen to create a new Docker container based on the official Nginx image available in the Docker Hub Repository.

To start a new container based on this image, you can type the following command:

docker -H run --name hello-nginx -d -p 80:80 nginx

Note: It may take a few minutes the first time, while the image is downloaded.

The command above asks Swarm to run a new container, based on the nginx image and expose the port 80 of the container on the port 80 of the Docker agent.

Then, you can check that the container is running using:

docker -H ps -a


Finally, you can test that your NGINX server is working by browsing the DNS linked to the public IP address of the agents’ load balancer. To get this DNS, just go in the resources that compose your container service in the Azure portal, and click on the public IP address of the agents:


Browse it, and you should see the home page of NGINX:


If you want to expose the application on another port, you should configure inbound rules in the network security group that was created for the Docker agent (by default, 80 is authorized):



You have now a fully functional Docker Swarm cluster based on Azure Container Service! As you can see, it is now really simple to create this kind of cluster in Microsoft Azure.



Comments (21)

  1. Excellent Article. Must spread this as it container the most critical piece of information export DOCKER_HOST=tcp:// . Thank you again!

    1. thanks for your feedback 🙂

  2. kv says:

    the correct command is
    azureuser@swarm-master-6466D73C-0:~$ docker -H run –name hello-ngix -d -p 80:80 nginx

    do note the double dash before name

    1. yes WordPress formats double dash as simple dash 🙁 next time I’ll do captures! thanks for the feedback

  3. Hey,
    Good enough detail for a newbie to get walk on..
    Can you post process for deploy application as service ?


      1. Thanks Julien,
        I read the documentation you provided but actually issue not with container or bundled app issue is with when i try to create docker service with below command it always give me error.
        If this is really a swarm cluster so why its asking me to join the cluster or initialize the cluster.

        As additional information i am issuing this command from Swarm Master.

        root@weuionamgmt:~# docker service create –replicas 2 –name crawling -p 80:1500 -p 29:22 –update-delay 10s –update-parallelism 1 crawling/crawlingv1.6 Error response from daemon: This node is not a swarm manager. Use “docker swarm init” or “docker swarm join” to connect this node to swarm and try again.

  4. Sumit Kute says:

    Nice Article and help me to setup things. One thing I experienced, when you generate RSA using putty and try to use in Git Bash to connect to Swarm cluster, it does not works. I have to generate the RSA using Git Bash and then only it works. Can you guide how to run docker compose on swarm master when you are developing using windows machine.

    1. Hi, thanks for you feedback. When working on Windows, you can use putty to create the SSH tunnel. This is documented here: Hope this helps

      1. Tim Wong says:

        I just started working with ACS and am having a hell of a time with SSH tunneling. I’m using putty and have setup everything according to My ACS is orchestrated using docker swarm and for some reason when I run something like “docker info” or “docker ps” after the tunnel is setup (over port 2375), the tunneling does not persist and no results come back. The error from putty is very generic, but am hitting a roadblock here…

        1. Hi Tim, I never encountered this error. Do you observe any connection lost if you connect directly on one of the master using ssh ?

  5. Subramani says:

    How did you know “The Docker Swarm socket is listening to the endpoint?? Also what would be the equivalent command in ACS /SWARM for docker compose? E.g.

    > git clone
    > cd doctor
    # start the services
    > docker-compose up -d
    # get the container name of the web service
    > docker ps
    # setup the database in a one-off command
    > docker exec doctor_web_1 bundle exec rake db:setup

  6. Hello,
    For the endpoint, it is in the documentation:
    You can use docker-compose with ACS, it’s pure Docker Swarm. You do not need an equivalent.

    1. Subramani says:

      SO when I do a docker-compose up -d, it launches the container on the master server and not on the swarm. Would you know the -H equivalent of making docker-Compose host a container on a swarm node?

      1. Yes, just do -H :2375 or set the DOCKER_HOST env variable to :2375

  7. Samuel says:

    Hi Julien,

    As the article was written almost 1 year ago, I have 2 questions:

    1) In the last section you mentioned “If you want to expose the application on another port, you should configure inbound rules in the network security group that was created for the Docker agent (by default, 80 is authorized)”. If you login to the latest Azure portal, there seems no ‘inbound security rule settings’ in your 2nd last image. Could you please help where could I find now?

    2) Now I also want to create container via docker-compose.yml file. (e.g. create magento/mariadb containers). How could I write the command now? I tried: “docker-compose -H up” but it seems doesn’t like it. If I remove “-H” I think containers will be created on master rather than agent.

    Thanks a lot!

    1. Samuel says:

      Also Julien,

      If I use different port for your example like: docker -H run –-name hello-nginx2 -d -p 82:82 nginx

      Then I couldn’t open it via:

    2. Hi,
      1) you need to go in the load balancer settings and edit the load balancing rules from there. The UI had small changes since I write this blog post. To be able to access your service on port 82 you need to create a load balancing rule on port 82 (this will help, I think:
      2) you are right. if you do not use the flag -H it will create the containers on the master. Use -H :2375 or set the DOCKER_HOST env variable to :2375

      1. Prakhar Rastogi says:

        Nice Article.. Thanks for explaining

  8. Guy Harwood says:

    Hi Julien,

    What we be best practice on ACS for Ning all traffic over HTTPS? should this be configured on the agent load balancer or a container running nginx etc?

    1. Hi Guy, this is not related to ACS but more to your workload. Actually, a container can run any workloads that supports https, so I thing this should be configured on your app / proxy (you quoted nginx). And of course you have to open the port 443 and create a load balancing rule in the agent LB – as for any other network rule.

Skip to main content