Guide: Getting Started with .NET Core Microservices using Kubernetes, Docker and Microsoft Azure Container Registry (ACR)

Posted by Nilay Parikh and last modified on Tue Jun 12, 2018.

Containers provides unique value for Microservices implementation. I am not trying to open a debate on computing options in the article. The scope of the article is to enable you and get you started with .NET Core Microservices using Kubernetes and Azure Container Registry.

What is Kubernetes and Azure Container Service ?

Kubernetes is an open source system for automating deployment, scaling, and management of containerized applications. Kubernetes is the production ready container orchestration open-source system. The Kubernetes project is becoming very popular among enterprise scale implementation for its execution ability. Automatic Binpacking, Self-healing, Scaling, Service Discovery, Automation, Configuration & Secret Management and Orchastrative Abilities are some of exciting selling points of the Kubernetes project.

Kubernetes is available (Generally Available) on Azure Container Service ( reference ). Azure Container Service (ACS) is a container hosting environment optimised for Azure, and it leverages the technologies such as Docker, Apache Mesos and open source components of DCOS.

Development Pipeline with Visual Studio, .NET Core and Docker

Docker would play a vital role as part of your development pipeline. Azure Container Registry supports docker format. Therefore, the journey would be similar as DockerHub. Development Pipeline can benefit by tagging images for target environments (i.e. :dev, :int, :sys, :preprod, :prod). Ideally, I recommend keeping the Container Images light-weight as possible and prefer layering them instead of going two step backwards by creating a monolithic image. I am restraining myself opening up the topic, but I will try to write a separate blog post on the subject.

The article splits into following sections,

Step by Step Guide to Setup Kubernetes in Microsoft Azure (Azure Container Service)

This section will show how to setup Azure Container Service instance using Kubernetes as Orchestrator. I am opting for easiest way that I can recommend for getting started with Kubernetes. However, more complex deployments can benefit from Azure Resource Manager based provisioning and custom configuration. Following steps are performed using Azure CLI 2.0, please visit the reference documentation .

Login using Azure CLI

There are different ways to connect to your Azure Subscription using Azure CLI; I have used the interactive login for ease. You can choose between username/password or service principal. Please, refer Microsoft Documentation for advance use scenarios.

az login

Create Kubernetes Instance using Azure CLI

Following az acs create with --orchestrator-type=kubernetes switch provision instance of Kubernetes (Azure Container Service). You can configure agent size (Azure VM) and initial agent count. --generate-ssh-keys would generate SSH public key to connect the Linux instances. The command would use the existing key if exists at ...\.ssh\

az acs create --orchestrator-type=kubernetes --resource-group <<your resource group>> --name=<<name of an instance>>
  --dns-prefix=<<dns prifix>> --agent-vm-size=Standard_A0 --agent-count=3 --generate-ssh-keys
  --admin-username <<username>> --admin-password <<password>> --verbose

On successful provision, you would receive following console output.

Use existing SSH public key file: C:\Users\*********\.ssh\
Microsoft.Network is already registered
Microsoft.Compute is already registered
Microsoft.Storage is already registered
waiting for AAD role to propagate.done
Starting long running operation 'Starting acs create'
Long running operation 'Starting acs create' completed with result {'id': '/subscriptions/<<your subscription id>>/resourceGroups/<<your resource group>>/providers/Microsoft.Resources/deployments/azurecli00000000.0000000000', 'name': 'azurecli00000000.0000000000', 'properties': <azure.mgmt.resource.resources.v2017_05_10.models.deployment_properties_extended.DeploymentPropertiesExtended object at 0x04176C30>}
  "id": "/subscriptions/<<your subscription id>>/resourceGroups/<<resource group>>/providers/Microsoft.Resources/deployments/azurecli00000000.0000000000",

Install Kubernetes Cli (kubectl.exe)

You use kubectl to connect to the Kubernetes cluster, the Kubernetes, command-line client. If you do not already have kubectl installed, you can install it with the following command. For detail reference visit kubernetes documentation .

az acs kubernetes install-cli

Downloading client to C:\Program Files (x86)\kubectl.exe from

Get Credentials for Setup Kubernetes Instance

You can run the following command to download master kubernetes configuration. Run the following command to download the master Kubernetes cluster configuration to the ~/.kube/config.

az acs kubernetes get-credentials --resource-group=<<your azure resource group>> --name=<<name of an instance>>

Get Kubernetes Nodes

At this point, you can expect to see kubernetes configured, up and running.

kubectl.exe get nodes

NAME                    STATUS                     AGE       VERSION
k8s-agent-7698b182-0    Ready                      28m       v1.5.3
k8s-master-7698b182-0   Ready,SchedulingDisabled   33m       v1.5.3

Setup Azure Container Registry

Azure Container Registry allows storing container images for all types of container deployments. It supports deployments including Kubernetes, DC/OS, Docker Swarm, and Azure services such as App Service, Service Fabric and others. Teams can manage the configuration of apps and images isolated from the hosting environment. It is very useful for DevOps friendly organisations and CI/CD pipeline. Azure Container Registry is a free service. However, you can be charged for resources utilisation such as storage and data transfer.

You can create Azure Container Registry using the following command. Additionally, you can use --storage-account-name to configure specific storage account.

az acr create --name <<your registry name>> --resource-group <<your resource group>>
  --location westeurope --sku Basic --admin-enabled true

Once provision using --admin-enabled, the switch would enable the admin user, and you can retrieve the password from Azure Portal. Username would be same as Registry Name.

Setup Development Pipeline using Visual Studio, Azure Container Registry and Docker

For this article, I have opted for a simple pipeline. However, you can design and build production grade CI/CD workflows using Jenkins, VSTS, Teamcity, Travis CI, Codeship. Secondly, if you are using Visual Studio 2017 then worth exploring Continuous Delivery Tools

Create Visual Studio Sample Project

I have created basic .NET Core Web Application\WebApi with Docker file and Docker compose definitions. You can download from Github/BlogSamples.Containers or create your own container.

Once the image is deployed to local Docker instance, you can use following commands to login and push local Docker image to Azure Container Registry.

Push a Docker Image to Azure Container Registry

Azure Container Registry maintain Linux and Windows images as a private Docker registry, you can also use Docker CLI with ACS because Azure Container Registry is compatible with the open-source Docker Registry v2.

docker login **** -u ****np -p "*********************SYywhRU"
docker tag docker.dotnet.core.helloworld:dev  ****
docker push  ****

On successful completion of the command docker push, you would see the image and dependencies are successfully uploaded to Azure Container Registry.

The push refers to a repository [****]
6366d48d16f9: Pushed
5da491fa2f9f: Pushed
f79c4622fc32: Pushed
8d63de0aed82: Pushed
edff68e6f343: Pushed
23792dc48b82: Pushed
8d4d1ab5ff74: Pushed
latest: digest: sha256:5a38d0385198e95aa7f4229b413cd06e107eabeb5d338ded89ea4abf6857cc95 size: 1787

Deploy to Kubernetes from Azure Container Registry (ACS)

You are ready to deploy your first container. You can either use kubectl commandline utility or user interface. Run kubectl proxy to access kubernetes Admin UI or APIs on the client machine. The command will create ssh tunnelling between the master node and client machine. You can access the user interface on 8001 port.

kubectl proxy

Starting to serve on

Lets deploy the first container. Refer Kubernetes Cheatsheet for an advance use. It would be useful to read docker to kubectl reference documentation.

kubectl.exe run bloghelloworld --image ****

deployment "bloghelloworld" created

The following command would create a service for recently deployed bloghelloworld, which serves on port 8081. Also, make sure that serving ports are accessible from Azure Load Balancer or other networking services.

kubectl expose deployments bloghelloworld --port=8081 --type=LoadBalancer


Any views or opinions expressed are solely those of the author and do not represent any other person or organisation. THE ARTICLE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL THE AUTHOR(S) OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY.