ASP.NET Core Kubernetes Tutorial for AKS

In this ASP.NET Core Kubernetes tutorial, I’ll walk through these steps:

Additionally, I’m going to cover some optional, but very helpful topics:

Prerequisites to get the most out of this tutorial:

Kubernetes deployments use container images. There are many options for private container registries (like Azure Container Registry), but to keep things simple for this tutorial, I’ll be using plain old Docker Hub.

First, I’ll start by building a Docker image from the ASP.NET Core Microservice I created in the previous blog post. From Visual Studio, this is as easy as right-clicking on Dockerfile and selecting “Build Docker Image”.

Once the image is built, it will appear in your local Docker image repository. You can see this repository from the command line by using “docker images”:

The next step is to push this image out to Docker hub (please review if you’ve not used Docker hub before). I pushed my image to Docker with the docker push mattgroves/hellomicroservice command. You will most likely want to tag your images with release numbers to make sure that Kubernetes is pulling the exact version you want to deploy.

If you want to skip this step, you can use my Docker image as an example: mattgroves/hellomicroservice.

Now that you have published a Docker image, we can start to write the YAML files for a Kubernetes deployment. This tutorial will not cover everything there is to know about Kubernetes, but it will point out noteworthy sections as much as possible. For this tutorial, there will be three total YAML files created to be along with the YAML files that ship with the Couchbase Operator.

Each of these YAML files corresponds to a Kubernetes resource. Kubernetes will orchestrate the cluster based on what resources you create in the cluster.

The ASP.NET Core Microservice resource and the Couchbase Cluster resource will each result in one or more “pods” being created on the Kubernetes cluster. Other types of resources are “secrets” (to manage and store sensitive information) and “services” (to expose a set of pods), and many others.

Look back to hello-microservice.yaml again. Under env, notice the name/value pair of “Couchbase__ConnectionString” and “couchbase://cb-hellomicroservices-srv”. Instead of giving ASP.NET Core IP address or URLs of Couchbase Server nodes, I’m using a connection string to direct it to a DNS SRV entry.

In a Couchbase Cluster, the actual pods running Couchbase have potential to change their names on a regular basis. Therefore, it’s recommended to use DNS SRV to locate the Couchbase service. Fortunately, the Couchbase Autonomous Operator creates a DNS SRV entry for us automatically.

We’ll soon be able to see it in the Kubernetes Dashboard, but in the meantime, just note that it will be the name of the Couchbase Cluster plus “-srv”. So in our case, it’s “cb-hellomicroservices-srv”.

I’ve made one minor change to the ASP.NET Core Microservice since the previous blog post: I’m now using the Couchbase.Extensions.DnsDiscovery library.

Besides adding this library from NuGet, and using ConnectionString instead of Server in appsettings.json, the only other change that needs to be made is to AddCouchbaseDnsDiscovery within the ConfigureServices method.

It’s as easy as that. For more about DNS SRV, check out SRV records in the Kubernetes documentation.

At this point, we’re ready to deploy to AKS. To review, here are the ingredients we have so far:

To deploy to AKS, I followed the Quickstart: Deploy an Azure Kubernetes Service cluster using the Azure CLI in the Microsoft documentation. Here is a brief summary of the steps I followed:

(If you want to use your local command line, make sure you have azure-cli installed. Otherwise, you can use the Azure Cloud Shell).

First, login to Azure: az login. You will be prompted to enter your credentials in your web browser.

After you have logged in, first create a “resource group”. This is an organization group within Azure. Specify a data center (I used eastus).

az group create --name helloMicroserviceGroup --location eastus

Next, create an AKS cluster using the resource group you just created. There are many options for this. To keep this exercise relatively low cost and simple, I chose to create 3 nodes using the Standard_B2s VM size. For production deployments of Couchbase, you will likely need/want more powerful sizes.

az aks create --resource-group helloMicroserviceGroup --name helloMicroserviceAks --node-count 3 --node-vm-size Standard_B2s --enable-addons monitoring --generate-ssh-keys

This step will take some time to run. Expect Azure to take around 10 minutes to setup this Kubernetes AKS cluster.

Once the cluster is created, use get-credentials to let kubectl know which cluster it will be using.

az aks get-credentials --resource-group helloMicroserviceGroup --name helloMicroserviceAks

At this point, it’s time to create some Kubernetes resources. The first six YAML files can be downloaded under “Kubernetes” couchbase.com/downloads.

Next, use the three YAML files that were created in this tutorial:

To see the state of your Kubernetes pods, use kubectl get pods. The Couchbase pods will take a few minutes to become ready.

In the above deployment, none of the Kubernetes deployments are actually exposed outside of Kubernetes. One way we can check to make sure the microservice is working is by using the kubectl port-forward command. This will create a localhost “tunnel” to the given pod.

For example, let’s create a tunnel from localhost port 5000 to the ASP.NET Core microservice running on port 80:

kubectl port-forward <hello-microservice-app-deployment-…​> 5000:80

At this point, you can access the microservice by using http://locahost:5000 in your browser.

Similarly, you can setup a tunnel to the built-in web based Couchbase Server UI:

kubectl port-forward cb-hellomicroservices-0000 8091:8091

And now you can access the Couchbase cluster by using http://localhost:8091.

The port-forward command can be helpful to developers and operations, but keep reading to see how to expose a Kubernetes service to the internet.

While port-forwarding can give us access to pods outside of the Kubernetes cluster, what happens when the pods inevitably crash, die and are reborn with new IP addresses, pod names, etc? Kubernetes allows us to create “services” to address one or more pods logically.

A service can be specified in the YAML files, just as the deployments are.

A service can also be created by using kubectl expose. For instance, I can expose a load balancer service that provides access to however many ASP.NET Core pods that my deployment has created:

kubectl expose deployments hello-microservice-app-deployment --port=80 --type=LoadBalancer

When the service is created, it will create an external IP address. You can view service information with kubectl get services.

Open that IP address in a web browser (20.NN.NN.21 in my example), and it will be load balanced access to the pods in your deployment. As you scale up or down (i.e. change the number of replicas), the service will remain the same and continue to provide access.

Kubernetes has its own UI dashboard than can be useful to get a visualization of the big picture without having to remember a bunch of command lines commands. To access the Kubernetes dashboard for AKS:

Create a ClusterRoleBinding for the Kubernetes dashboard to enable access:

kubectl create clusterrolebinding kubernetes-dashboard --clusterrole=cluster-admin --serviceaccount=kube-system:kubernetes-dashboard

Then, use Azure’s aks browse to start the dashboard:

az aks browse --resource-group helloMicroserviceGroup --name helloMicroserviceAks

This should also automatically trigger your web browser to open the dashboard:

From the dashboard, you can view all the pods, services, secrets, nodes, and more.

If you have been following along on AKS, don’t forget to remove the resource group when you are done. Otherwise, it will continue to run on your Azure account and charge you for compute time. You can remove the entire resource group from this tutorial with one command:

az group delete --name helloMicroserviceGroup

There was a lot of ground covered in this ASP.NET Core Kubernetes tutorial, but hopefully enough to point you in the right direction and get you started with a “Hello, world” example.

As in the last blog post, this ASP.NET Core Kubernetes tutorial is a product of a couple of live coding streams on Twitch. You can view part 1 and part 2 on YouTube. And if you have questions, you’re welcome to stop by the live stream on Twitch next time and chat!

Kubernetes is a very broad topic. There are a lot of directions you could go from here. Here are a few links that you might want to check out: