ASP.NET app containerization and migration to Azure App Service

In this article, you'll learn how to containerize ASP.NET applications and migrate them to Azure App Service using the Azure Migrate: App Containerization tool. The containerization process doesn’t require access to your codebase and provides an easy way to containerize existing applications. The tool works by using the running state of the applications on a server to determine the application components and helps you package them in a container image. The containerized application can then be deployed on Azure App Service.

The Azure Migrate: App Containerization tool currently supports -

  • Containerizing ASP.NET apps and deploying them on Windows containers on App Service.
  • Containerizing ASP.NET apps and deploying them on Windows containers on Azure Kubernetes Service. Learn more
  • Containerizing Java Web Apps on Apache Tomcat (on Linux servers) and deploying them on Linux containers on AKS. Learn more
  • Containerizing Java Web Apps on Apache Tomcat (on Linux servers) and deploying them on Linux containers on App Service. Learn more

The Azure Migrate: App Containerization tool helps you to -

  • Discover your application: The tool remotely connects to the application servers running your ASP.NET application and discovers the application components. The tool creates a Dockerfile that can be used to create a container image for the application.
  • Build the container image: You can inspect and further customize the Dockerfile as per your application requirements and use that to build your application container image. The application container image is pushed to an Azure Container Registry you specify.
  • Deploy to Azure App Service: The tool then generates the deployment files needed to deploy the containerized application to Azure App Service.

Note

The Azure Migrate: App Containerization tool helps you discover specific application types (ASP.NET and Java web apps on Apache Tomcat) and their components on an application server. To discover servers and the inventory of apps, roles, and features running on on-premises machines, use Azure Migrate: Discovery and assessment capability. Learn more

While all applications won't benefit from a straight shift to containers without significant rearchitecting, some of the benefits of moving existing apps to containers without rewriting include:

  • Improved infrastructure utilization: With containers, multiple applications can share resources and be hosted on the same infrastructure. This can help you consolidate infrastructure and improve utilization.
  • Simplified management: By hosting your applications on modern managed platform like AKS and App Service, you can simplify your management practices. You can achieve this by retiring or reducing the infrastructure maintenance and management processes that you'd traditionally perform with owned infrastructure.
  • Application portability: With increased adoption and standardization of container specification formats and platforms, application portability is no longer a concern.
  • Adopt modern management with DevOps: Helps you adopt and standardize on modern practices for management and security and transition to DevOps.

In this tutorial, you'll learn how to:

  • Set up an Azure account.
  • Install the Azure Migrate: App Containerization tool.
  • Discover your ASP.NET application.
  • Build the container image.
  • Deploy the containerized application on App Service.

Note

Tutorials show you the simplest deployment path for a scenario so that you can quickly set up a proof-of-concept. Tutorials use default options where possible, and don't show all possible settings and paths.

Prerequisites

Before you begin this tutorial, you should:

Requirement Details
Identify a machine to install the tool A Windows machine to install and run the Azure Migrate: App Containerization tool. The Windows machine could be a server (Windows Server 2016 or later) or client (Windows 10) operating system, meaning that the tool can run on your desktop as well.

The Windows machine running the tool should have network connectivity to the servers/virtual machines hosting the ASP.NET applications to be containerized.

Ensure that 6-GB space is available on the Windows machine running the Azure Migrate: App Containerization tool for storing application artifacts.

The Windows machine should have internet access, directly or via a proxy.

Install the Microsoft Web Deploy tool on the machine running the App Containerization helper tool and application server if not already installed. You can download the tool from here
Application servers Enable PowerShell remoting on the application servers: Log in to the application server and Follow these instructions to turn on PowerShell remoting.

If the application server is running Window Server 2008 R2, ensure that PowerShell 5.1 is installed on the application server. Follow the instruction here to download and install PowerShell 5.1 on the application server.

Install the Microsoft Web Deploy tool on the machine running the App Containerization helper tool and application server if not already installed. You can download the tool from here
ASP.NET application The tool currently supports

- ASP.NET applications using Microsoft .NET framework 3.5 or later.
- Application servers running Windows Server 2008 R2 or later (application servers should be running PowerShell version 5.1).
- Applications running on Internet Information Services (IIS) 7.5 or later.

The tool currently doesn't support

- Applications requiring Windows authentication (AKS doesn’t support gMSA currently).
- Applications that depend on other Windows services hosted outside IIS.

Prepare an Azure user account

If you don't have an Azure subscription, create a free account before you begin.

Once your subscription is set up, you'll need an Azure user account with:

  • Owner permissions on the Azure subscription
  • Permissions to register Azure Active Directory apps

If you just created a free Azure account, you're the owner of your subscription. If you're not the subscription owner, work with the owner to assign the permissions as follows:

  1. In the Azure portal, search for "subscriptions", and under Services, select Subscriptions.

    Search box to search for the Azure subscription.

  2. In the Subscriptions page, select the subscription in which you want to create an Azure Migrate project.

  3. In the subscription, select Access control (IAM) > Check access.

  4. In Check access, search for the relevant user account.

  5. In Add a role assignment, click Add.

    Search for a user account to check access and assign a role.

  6. In Add role assignment, select the Owner role, and select the account (azmigrateuser in our example). Then click Save.

    Opens the Add Role assignment page to assign a role to the account.

  7. Your Azure account also needs permissions to register Azure Active Directory apps.

  8. In Azure portal, navigate to Azure Active Directory > Users > User Settings.

  9. In User settings, verify that Azure AD users can register applications (set to Yes by default).

    Verify in User Settings that users can register Active Directory apps.

  10. In case the App registrations settings is set to No, request the tenant/global admin to assign the required permission. Alternately, the tenant/global admin can assign the Application Developer role to an account to allow the registration of Azure Active Directory App. Learn more.

Download and install Azure Migrate: App Containerization tool

  1. Download the Azure Migrate: App Containerization installer on a Windows machine.

  2. Launch PowerShell in administrator mode and change the PowerShell directory to the folder containing the installer.

  3. Run the installation script using the command

    .\AppContainerizationInstaller.ps1
    

Launch the App Containerization tool

  1. Open a browser on any machine that can connect to the Windows machine running the App Containerization tool, and open the tool URL: https://machine name or IP address: 44369.

    Alternately, you can open the app from the desktop by selecting the app shortcut.

  2. If you see a warning stating that says your connection isn’t private, click Advanced and choose to proceed to the website. This warning appears as the web interface uses a self-signed TLS/SSL certificate.

  3. At the sign in screen, use the local administrator account on the machine to sign in.

  4. Select ASP.NET web apps as the type of application you want to containerize.

  5. To specify target Azure service, select Containers on Azure App Service. Default load-up for App Containerization tool.

Complete tool pre-requisites

  1. Accept the license terms, and read the third-party information.
  2. In the tool web app > Set up prerequisites, do the following steps:
    • Connectivity: The tool checks that the Windows machine has internet access. If the machine uses a proxy:
      • Click on Set up proxy to specify the proxy address (in the form IP address or FQDN) and listening port.
      • Specify credentials if the proxy needs authentication.
      • Only HTTP proxy is supported.
      • If you've added proxy details or disabled the proxy and/or authentication, click on Save to trigger connectivity check again.
    • Install updates: The tool will automatically check for latest updates and install them. You can also manually install the latest version of the tool from here.
    • Install Microsoft Web Deploy tool: The tool will check that the Microsoft Web Deploy tool is installed on the Windows machine running the Azure Migrate: App Containerization tool.
    • Enable PowerShell remoting: The tool will inform you to ensure that PowerShell remoting is enabled on the application servers running the ASP.NET applications to be containerized.

Sign in to Azure

Click Sign in to log in to your Azure account.

  1. You'll need a device code to authenticate with Azure. Clicking on sign in will open a modal with the device code.

  2. Click on Copy code & sign in to copy the device code and open an Azure sign in prompt in a new browser tab. If it doesn't appear, make sure you've disabled the pop-up blocker in the browser.

    Modal showing device code.

  3. On the new tab, paste the device code and complete sign in using your Azure account credentials. You can close the browser tab after sign in is complete and return to the App Containerization tool's web interface.

  4. Select the Azure tenant that you want to use.

  5. Specify the Azure subscription that you want to use.

Discover ASP.NET applications

The App Containerization helper tool connects remotely to the application servers using the provided credentials and attempts to discover ASP.NET applications hosted on the application servers.

  1. Specify the IP address/FQDN and the credentials of the server running the ASP.NET application that should be used to remotely connect to the server for application discovery.

    • The credentials provided must be for a local administrator (Windows) on the application server.
    • For domain accounts (the user must be an administrator on the application server), prefix the username with the domain name in the format <domain\username>.
    • For local accounts (the user must be an administrator on the application server), prefix the username with the hostname in the format <hostname\username>.
    • You can run application discovery for up to five servers at a time.
  2. Click Validate to verify that the application server is reachable from the machine running the tool and that the credentials are valid. Upon successful validation, the status column will show the status as Mapped.

    Screenshot for server IP and credentials.

  3. Click Continue to start application discovery on the selected application servers.

  4. Upon successful completion of application discovery, you can select the list of applications to containerize.

    Screenshot for discovered ASP.NET application.

  5. Use the checkbox to select the applications to containerize.

  6. Specify container name: Specify a name for the target container for each selected application. The container name should be specified as <name:tag> where the tag is used for container image. For example, you can specify the target container name as appname:v1.

Parameterize application configurations

Parameterizing the configuration makes it available as a deployment time parameter. This allows you to configure this setting while deploying the application as opposed to having it hard-coded to a specific value in the container image. For example, this option is useful for parameters like database connection strings.

  1. Click app configurations to review detected configurations.

  2. Select the checkbox to parameterize the detected application configurations.

  3. Click Apply after selecting the configurations to parameterize.

    Screenshot for app configuration parameterization ASP.NET application.

Externalize file system dependencies

You can add other folders that your application uses. Specify if they should be part of the container image or are to be externalized to persistent storage through Azure file share. Using external persistent storage works great for stateful applications that store state outside the container or have other static content stored on the file system.

  1. Click Edit under App Folders to review the detected application folders. The detected application folders have been identified as mandatory artifacts needed by the application and will be copied into the container image.

  2. Click Add folders and specify the folder paths to be added.

  3. To add multiple folders to the same volume, provide comma (,) separated values.

  4. Select Azure file share as the storage option if you want the folders to be stored outside the container on persistent storage.

  5. Click Save after reviewing the application folders. Screenshot for app volumes storage selection.

  6. Click Continue to proceed to the container image build phase.

Build container image

  1. Select Azure Container Registry: Use the dropdown to select an Azure Container Registry that will be used to build and store the container images for the apps. You can use an existing Azure Container Registry or choose to create a new one using the Create new registry option.

    Screenshot for app ACR selection.

Note

Only Azure container registries with admin user enabled are displayed. The admin account is currently required for deploying an image from an Azure container registry to Azure App Service. Learn more

  1. Review the Dockerfile: The Dockerfile needed to build the container images for each selected application are generated at the beginning of the build step. Click Review to review the Dockerfile. You can also add any necessary customizations to the Dockerfile in the review step and save the changes before starting the build process.

  2. Trigger build process: Select the applications to build images for and click Build. Clicking build will start the container image build for each application. The tool keeps monitoring the build status continuously and will let you proceed to the next step upon successful completion of the build.

  3. Track build status: You can also monitor progress of the build step by clicking the Build in Progress link under the status column. The link takes a couple of minutes to be active after you've triggered the build process.

  4. Once the build is completed, click Continue to specify deployment settings.

    Screenshot for app container image build completion.

Deploy the containerized app on Azure App Service

Once the container image is built, the next step is to deploy the application as a container on Azure App Service.

  1. Select the Azure App Service plan: Specify the Azure App Service plan that the application should use.

    • If you don’t have an App Service plan or would like to create a new App Service plan to use, you can choose to create on from the tool by clicking Create new App Service plan.
    • Click Continue after selecting the App Service plan.
  2. Specify secret store: If you had opted to parameterize application configurations, then specify the secret store to be used for the application. You can choose Azure Key Vault or App Service application settings for managing your application secrets. Learn more

    • If you've selected App Service application settings for managing secrets, then click Continue.
    • If you'd like to use an Azure Key Vault for managing your application secrets, then specify the Azure Key Vault that you'd want to use.
      • If you don’t have an Azure Key Vault or would like to create a new Key Vault, you can choose to create on from the tool by clicking Create new Azure Key Vault.
      • The tool will automatically assign the necessary permissions for managing secrets through the Key Vault.
  3. Specify Azure file share: If you had added more directories/folders and selected the Azure file share option for persistent storage, then specify the Azure file share to be used by Azure Migrate: App Containerization tool during the deployment process. The tool will copy over the application directories/folders that are configured for Azure Files and mount them on the application container during deployment. 

    • If you don't have an Azure file share or would like to create a new Azure file share, you can choose to create on from the tool by clicking Create new Storage Account and file share.
  4. Application deployment configuration: Once you've completed the steps above, you'll need to specify the deployment configuration for the application. Click Configure to customize the deployment for the application. In the configure step you can provide the following customizations:

    • Name: Specify a unique app name for the application. This name will be used to generate the application URL and used as a prefix for other resources being created as part of this deployment.
    • Application configuration: For any application configurations that were parameterized, provide the values to use for the current deployment.
    • Storage configuration: Review the information for any application directories/folders that were configured for persistent storage.

    Screenshot for deployment app configuration.

  5. Deploy the application: Once the deployment configuration for the application is saved, the tool will generate the Kubernetes deployment YAML for the application.

    • Click Review to review the deployment configuration for the applications.

    • Select the application to deploy.

    • Click Deploy to start deployments for the selected applications

      Screenshot for app deployment configuration.

    • Once the application is deployed, you can click the Deployment status column to track the resources that were deployed for the application.

Troubleshoot issues

To troubleshoot any issues with the tool, you can look at the log files on the Windows machine running the App Containerization tool. Tool log files are located at C:\ProgramData\Microsoft Azure Migrate App Containerization\Logs folder.

Next steps

  • Containerizing ASP.NET web apps and deploying them on Windows containers on AKS. Learn more
  • Containerizing Java web apps on Apache Tomcat (on Linux servers) and deploying them on Linux containers on AKS. Learn more
  • Containerizing Java web apps on Apache Tomcat (on Linux servers) and deploying them on Linux containers on App Service. Learn more