Migrating your .NET apps to Azure Kubernetes Services

The recent advancements in containers have transformed the way applications are built. Containerization tools help developers test, package, and deploy apps faster, with orchestration systems like Kubernetes help scale and manage those containers.

Azure Kubernetes Service (AKS) is a hosted Kubernetes service that provides straightforward development and deployment tooling for cloud-native apps in Azure. However, migrating traditional ASP.NET applications to AKS can be tedious and prone to errors. That’s why Azure Migrate was introduced: to facilitate the containerization of ASP.NET applications for easy deployment.

Most ASP.NET applications fall into one of two categories: ASP.NET Core and ASP.NET MVC 4. The former is an open-source framework compatible with multiple operating systems, while the latter is a mature framework for building server-based web apps exclusively on Windows.

This hands-on article guides you through migrating any existing ASP.NET application to AKS using the Azure Migrate tool. By the end of this article, you’ll know how to migrate your own existing projects onto AKS, even if they weren’t originally designed to run on containers or be deployed in Kubernetes.

Prerequisites

To follow this demonstration, you’ll need the following:

• A Windows machine—either a server (Windows Server 2016 or later) or client (Windows 10 or newer)
• Internet Information Services (IIS) 7
• Visual Studio 2022
• The following folder structures:
  • For ASP.NET Core: C:\IISPublish\ZohoAPICore
  • For ASP.NET MVC 4: C:\IISPublish\ZohoNet4

You'll also need to configure your ASP.NET permissions properly. To do so, right-click the C:\IISPublish folder, open the Security tab, click the Edit button and add the full control permissions to the IUSR user.

Note that this article includes tutorials for migrating both types of ASP.NET applications. To skip to the guide most relevant to your project, click on one of the following:

• ASP.NET Core
• ASP.NET MVC 4

Introducing Azure Migrate

You have some options for modernizing ASP.NET web applications into a containerized environment. One option is to upgrade the application to a newer version. However, you can also do it without changing the application’s code.

First, you must package your application to ensure it behaves similarly, regardless of the environment. This assembled format is called a container image.

Next, the container image is put into Azure Container Registry to make the image accessible to the application hosts.

Finally, you deploy the application into AKS.

Using the Azure Migrate App Containerization Tool

This section demonstrates how to correctly fill in the fields and settings the Azure Migration App Containerization tool requires.

Once the tool is installed, open the tool URL at https://localhost:44369/. You can also click on the shortcut icon on your desktop.

Log in using the computer’s local administrator account when the sign in form appears.

Now, you can get the app migration tool. Open the Microsoft Azure home page, sign in, and search for “Azure Migrate.”

Click Explore more, then select App Containerization under Web apps to container.

The next page provides links to learn more about migrating ASP.NET applications to containers on AKS and prompts you to download the App Containerization tool. Click the Download button.

You’ll see that The App Containerization tool has been downloaded:

To install the tool, open PowerShell in Administrator mode.

In PowerShell, change the directory to the Downloads folder, then run the App Containerization installer using the code below:

> cd ~/Downloads

> .\AppContainerizationInstaller.ps1

The App Containerization tool will be installed and added as a website on your local machine’s IIS.

The installer will launch the Azure Migrate App Containerization website. When the following page appears on the browser, ignore the alert by clicking the ADVANCED button.

This will open a link allowing you to proceed to the local website.

The App Containerization tool will open on your browser, as shown below. You can access it anytime by opening the https://localhost:44369/ URL.

Migrating an ASP.NET Core project to AKS

Begin by creating and configuring a simple ASP.NET Core project to use as an example. If you prefer, you can also repurpose any open-source code instead of creating it manually.

Creating and configuring a simple ASP.NET Core project

First, download and install the IIS runtime support (ASP.NET Core Module v2).

Open IIS and click on Modules.

Then, click Configure Native Modules:

Ensure the AspNetCoreModuleV2 module is included. This IIS module is required to enable IIS to support ASP.NET Core 2.0 and later applications.

After right-clicking on the Visual Studio icon, select Run as Administrator.

Create a new ASP.NET Core project named ZohoAPICore. Ensure that “Enable Docker support” isn’t checked.

Right-click on the new project, then click the Publish menu. Select C:\IISPublish\ZohoAPICore as the folder location, then click Publish.

Next, open IIS. Right-click the Sites node, then click Add Website.

Provide the following parameters:

• Site name: zohoapicore
• Physical path: C:\IISPublish\ZohoAPICore
• Host name: localhost
• Port: 80

Finally, head back to Visual Studio and click New publish profile. Select the Web Server (IIS) option, then choose Web Deploy and add the following options:

• Server: localhost
• Site name: zohoapicore
• Destination URL: localhost

As they appear, click Validate Connection, Finish, and Publish.

The web application will start, and the homepage should look like this:

Migrating an ASP.NET Core project to AKS

Now that you have your example project, you’ll migrate it to AKS using the Azure Migrate tool.

First, open your local IIS Manager to check if it’s hosting the ASP.NET Core application.

Once the ZohoAPICore web application is hosted, it will expose the /WeatherForecast endpoint, implemented by the \Controllers\WeatherForecastController.cs file.

Open the http://localhost/WeatherForecast URL to check if the application is running correctly on IIS.

Select the type of application to containerize: ASP.NET web apps. In the dropdown menu for Target Azure service, select Containers on Azure Kubernetes Service.

Then you'll be asked to check some prerequisites, including installing Microsoft Web Deploy, which is used to export the ASP.NET website hosted in your local IIS.

Next, you'll have to authenticate with your Azure credentials.

After authenticating with the device code, provide the tenant and your Azure subscription.

Then you have to provide information about the source of your applications. Since the web app is hosted locally, provide 127.0.0.1, which represents the Server IP address of your local computer. Also, enter the username in the COMPUTER NAME\username format and password with privileges to access your local IIS.

Next, specify the Target container. The tag used for the container image will be displayed in the name:tag format—for example, “zohoapicore:v1.”

To build a container image, follow the steps below.

Select Azure Container Registry. The Azure Container Registry (ACR) is a repository for storing and accessing container images. Select the Azure Container Registry you want to use from the dropdown menu.

You have the option of using a new or existing Azure Container Registry. To create a new one, click on Create new registry. In this case, you’ll provide your Azure subscription, a resource group, a container registry name, and a location.

You need to edit the Dockerfile that was created at the start of the build step. Dockerfile is a text document containing several command-line, step-by-step instructions that tell Docker how to build a container image, saving users from performing all the steps manually. Click Review to review the Dockerfile.

Edit the Dockerfile before building the docker image to avoid AKS version compatibility issues and ensure a seamless migration.

Change the script below from shell form below:

# Run entrypoint script. 
COPY ./Entryscript.ps1 c:/Entryscript.ps1 
ENTRYPOINT powershell c:/Entryscript.ps1   

To the following exec form:

COPY ["./Entryscript.ps1", "c:/Entryscript.ps1"] 
ENTRYPOINT ["powershell", "c:/Entryscript.ps1"]   

By default, the Dockerfile COPY and ENTRYPOINT commands above come in the shell form. However, since AKS 1.23+, Microsoft recommends the exec form since it ensures that no compatibility errors will occur.

During the reviewing stage, customize the Dockerfile as necessary, then save before the build process begins.

Select the ASP.NET Core application to build images for and click the Build button. This will start the container image build for each selected application. The tool will continuously track the build status for you. Once it’s complete, you can move on to the next step.

If you prefer manual monitoring, click on Build in Progress underneath the status column. Once you've begun the build process, the link takes a couple of minutes to become active.

When the build is successfully completed, click Continue.

You need to specify which AKS cluster you want the application to deploy to.

The selected cluster needs a Windows node pool and the ability to pull images from the selected registry. To create an AKS cluster, click on Create new AKS cluster.

Click Create and then Continue.

Then skip the Specify secret store and Specify Azure file share steps because your ASP.NET application doesn’t need them.

Under Provide deployment specifications, click the Configure link. Here, you’ll provide the prefix string for resources created in the AKS cluster, the mapped network ports, the number of replicas, and the load balancer type. Ensure the values are the same as the ones below:

Then click the Continue button.

Now, under the Deploy containers section, click the Edit link.

Here’s a breakdown of the deployment configuration details:

Service Configuration

• apiVersion: v1 — This is the version of the Kubernetes API you’re using to create this object.
• kind: Service — This is an abstract way to expose an application running on a set of Pods as a network service.
• metadata.name: zohoapicore-svc — This specifies the name used to identify the object. Metadata may also include a namespace field. A unique UID is assigned by the system.
• spec.ports — This exposes the Kubernetes service to traffic within the cluster on the specified port and routes traffic to the targetPort that your Pod will be listening on.
• spec.ports.port — This represents the port number exposed by the Pod. It’s the port that other services or Pods can use to communicate with the container running in the Pod. This number is usually specified in the spec.ports section of a Service or in the spec.containers.ports section of a Pod.
• spec.ports.targetPort — This specifies the port number on which the container inside the Pod is listening. It indicates the port to which the Service or other Pods forward traffic. The targetPort is usually specified in the spec.ports section of a Service and should match the port number on which the application inside the container is listening.
• spec.selector.app: zohoapicore — The Service targets Pods that have this label.
• spec.type: LoadBalancer — This distributes network traffic across Azure servers.

StatefulSet Configuration

(A StatefulSet guarantees that the Pod restarts when you mount a volume with its original state preserved.)

apiVersion: apps/v1 
kind: StatefulSet 
metadata: 
  labels: 
    app: zohoapicore 
  name: zohoapicore-sts 
spec: 
  replicas: 1 
  selector: 
    matchLabels: 
      app: zohoapicore 
  serviceName: zohoapicore-svc 
  template: 
    metadata: 
      labels: 
        app: zohoapicore 
      name: zohoapicore-sts 
    spec: 
      containers: 
      - env: 
        - name: POD_NAME 
          valueFrom: 
            fieldRef: 
              fieldPath: metadata.name 
        image: zohoacr.azurecr.io/zohoapicore:v1 
        imagePullPolicy: Always 
        name: zohoapicore 
        ports: 
        - containerPort: 80 
        resources: 
          limits: 
            cpu: 2 
            memory: 800M 
          requests: 
            cpu: 1 
            memory: 300M 
        terminationMessagePolicy: FallbackToLogsOnError 
        volumeMounts: [] 
      nodeSelector: 
        beta.kubernetes.io/os: windows 
      volumes: [] 
  volumeClaimTemplates: []   

• kind: StatefulSet — This maintains the state of applications beyond a single Pod lifecycle.
• metadata.labels.app: zohoapicore — This labels the Pods so they can be targeted by the Service.
• spec.replicas: 1 — This indicates how many Pods to run.
• spec.template.spec.containers — This indicates which container images to run and which ports to expose in each Pod.
• spec.template.spec.containers.image: zohoacr.azurecr.io/zohoapicore:v1 — This is the image name and tag to run in the containers.
• spec.template.spec.containers.resources — This defines the minimum and maximum number of CPUs and memory each container should use.
• spec.template.spec.nodeSelector:beta.kubernetes.io/os: windows — This schedules Pods to a Windows node.

Don’t change these configurations—just leave them as-is and close the dialog.

Next, click the Deploy button and wait until the containerized application is deployed to AKS. This may take several minutes.

When you click the Deployed link above, it gives you information about the AKS cluster, the resource group, the APP IP, and the running Service. The tool also indicates that your application Pod is ready.

As shown in the image above, the tool indicates that the application was deployed, and you got an arbitrary App I (in this example, 20.206.171.215) exposed by a load balancer servicing your AKS Pods in the back end.

Copy that IP address and paste it with the /WeatherForecast route on your web browser to check the application. You should see the following contents displaying weather forecasts:

Migrating an ASP.NET MVC 4 project to AKS

Begin by creating and configuring a simple ASP.NET MVC 4 project to use as an example. If you prefer, you can also repurpose any open-source code instead of creating it manually.

Creating and configuring a simple ASP.NET MVC 4 project

First, open the Command Prompt in Administrator mode and enter the following command:

dism /online /enable-feature /featurename:IIS-ASPNET45 /all

The Deployment Image Servicing and Management (DISM) command-line tool above enables Windows features directly from the command prompt. It’s required to enable your local IIS to run ASP.NET 4.5 apps. The /all option at the end of the command ensures that all dependency features are installed.

After right-clicking on the Visual Studio icon, select Run as Administrator.

Create a new ASP.NET MVC 4 project named ZohoNet4. Make sure that “Enable Docker support” is not checked.

Right-click the ZohoNet4 project and click the Publish menu. Select C:\IISPublish\ZohoNet4 as the folder location, then click Publish.

Next, open ISS. Right-click the Sites node, then click Add Website.

Provide the following parameters:

• Site name: zohonet4
• Physical path: C:\IISPublish\ZohoNet4
• Host name: localhost
• Port: 80

Return to Visual Studio and click New publish profile. Select the Web Server (IIS) option, choose Web Deploy, and add the following options:

• Server: localhost
• Site name: zohonet4
• Destination URL: localhost

As they appear, click Validate Connection, Finish, and Publish.

The web application will start, and the home page should look like this:

Migrating an ASP.NET MVC 4 project to AKS

Now that you have your sample project, you’ll migrate it to AKS using the Azure Migrate tool.

Before migrating your ASP.NET MVC 4 app to AKS, open IIS and check if it’s properly hosting your application. The globe icon at the left of the “zohonet4” name indicates the website was started.

Open the http://localhost/ URL to check if the application is hosted and running correctly on the local IIS.

Now open the Azure Migrate App Containerization tool URL at https://localhost:44369/. Click the Reset button to clear your previous app migration.

Select the type of application to containerize: ASP.NET web apps. In the dropdown menu for Target Azure service, select Containers on Azure Kubernetes Service.

In the “Discover applications” section, provide 127.0.0.1 as the Server IP address, enter the username in the COMPUTER NAME\username format, and provide a password with privileges to access your local IIS:

Next, specify the target container in the name:tag format as the name for the container image.

To build a container image, select Azure Container Registry. The Azure Container Registry (ACR) is a repository that stores and accesses container images. ACR lets you pull, push, and distribute the images you build to be used for an Azure service like AKS. Select the Azure Container Registry you want to use from the dropdown menu.

You have the option of using a new or existing Azure Container Registry. To create a new one, click on Create new registry. In this case, you’ll provide your Azure subscription, a resource group, a container registry name, a location that best fits your deployment needs, and the SKU (which should be set to basic).

Now, you need to edit the Dockerfile that was created at the start of the build step. Click Review to review the Dockerfile.

Now edit the scripts below before building the docker image to avoid AKS version compatibility issues and ensure a smooth migration.

Modify the script below from shell form:

# Run entrypoint script. 
COPY ./Entryscript.ps1 c:/Entryscript.ps1 
ENTRYPOINT powershell c:/Entryscript.ps1   

To exec form:

COPY ["./Entryscript.ps1", "c:/Entryscript.ps1"] 
ENTRYPOINT ["powershell", "c:/Entryscript.ps1"]   

By default, the Dockerfile COPY and ENTRYPOINT commands above come in the shell form. However, since AKS 1.23+, Microsoft recommends the exec form since it ensures that no compatibility errors will occur.

Select the ASP.NET MVC4 application to build an image for and select Build.

Once built, select Continue to define deployment settings.

You need to specify which AKS cluster you want the application to deploy to. The selected cluster requires a Windows node pool and must be able to extract images from the Azure Container Registry chosen to store the images. To create an AKS cluster, click on Create new AKS cluster.

Click Create and then Continue.

Then, skip the Specify secret store and the Specify Azure file share steps since this ASP.NET MVC 4 application doesn’t need them.

Under the “Provide deployment specifications” section, click the Configure link. Here you’ll provide the prefix string for resources created in the AKS cluster, the mapped network ports (80), the number of replicas, and the load balancer type. Ensure the values are the same as the ones below.

Then click the Continue button.

Now, under the “Deploy containers” section, click the Edit link.

Like before, leave the configurations as they are and close this dialog.

Next, click the Deploy button and wait until the containerized application is deployed to AKS. This may take several minutes:

When you click the Deploy link above, it gives you information about the AKS cluster, the resource group, the APP IP, and the running service. The tool also indicates that your application Pod is ready.

In the image above, the tool indicates that the application was deployed, and you got an arbitrary App IP (in this example, 20.226.195.164) exposed by a load balancer servicing your AKS Pods in the back end.

Now copy that IP address and paste it on your browser to check the application. You should see your ASPNET MVC 4 website homepage, as shown below:

Best practices for migrating to AKS

Migrating to AKS has many benefits, from improved performance to scalability to more efficient deployment. Let’s look at some best practices to help you make the most of the migration process.

First, take an incremental approach to AKS migration. By beginning with low-risk Internet projects, you can quickly gain experience working with AKS. This will help you migrate mission-critical applications with confidence.

Migrating to AKS will impact your CI/CD operations, meaning you must adapt your pipelines to properly build the container images and version and deploy them to production. Focus on the YAML manifest definition file since it describes mapping external ports, directories, and other configuration options for your image.

Finally, promote container culture. Handling the container lifecycle requires different approaches for development, deployment, and testing, as well as trained IT personnel. Encourage the learning of container technology within your organization.

Conclusion

This article demonstrated how to create a simple web application on your local machine and migrate them to AKS using the Azure Migrate tool.

Modernizing legacy applications and migrating them to Kubernetes can be challenging, but it doesn’t have to be. With proper planning, process reevaluation, and tools like Azure Migrate, you can easily migrate any project (ASP.NET Core or ASP.NET MVC 4).