Containerizing a .NET application on Windows - AWS App2Container

Containerizing a .NET application on Windows

This tutorial takes you through the steps to containerize a legacy .NET application running in IIS on Windows using App2Container, and to deploy it on Amazon ECS, Amazon EKS, or AWS App Runner. You can complete all steps on the application server, or you can perform the initial steps on the application server and perform the containerization and deployment steps on a worker machine.

Prerequisites

Verify that you have completed the following prerequisites:

  • Your application environment meets all of the requirements that are listed for Windows in the Supported applications section.

  • You installed the AWS Tools for Windows PowerShell to configure the AWS profile on your server. See Configure your AWS profile in the Setting up section of this user guide for more information.

  • You installed the Docker engine on the server where you are running containerization and deployment steps. See Install the Docker engine in the Setting up section of this user guide for more information.

  • There are one or more applications running in IIS on the application server.

  • You are a Windows administrator on the application server (and worker machine, if using).

  • The application server or worker machine has PowerShell version 5.1 or later and at least 20-30 GB of free space.

Note

App2Container does not support applications running on Windows client operating systems, such as Windows 7 or Windows 10.

Step 1: Install App2Container

App2Container for Windows is packaged as a zip archive. The package contains a PowerShell script that installs App2Container. If you are using an application server and a worker machine, you must install App2Container on both.

To download and install App2Container for Windows

  1. Download the App2Container installation package, AWSApp2Container-installer-windows.zip.

  2. Extract the package to a local folder on the server and navigate to that folder.

  3. Run the install script from the folder where you extracted it, and follow the prompts.

    PS> .\install.ps1
  4. (Optional) To verify the authenticity of the download, use the Get-AuthenticodeSignature PowerShell command as follows to get the Authenticode Signature of the App2Container executable.

    PS> Get-AuthenticodeSignature C:\Users\Administrator\app2container\AWSApp2Container\bin\app2container.exe

Step 2: Initialize App2Container

On each server where you installed App2Container, run the init command as follows.

PS> app2container init

You are prompted to provide the following information. Choose <enter> to accept the default value.

  • Workspace directory path – A local directory where App2Container can store artifacts during the containerization process. The default is C:\Users\Administrator\AppData\Local\app2container.

  • AWS profile – Contains information needed to run App2Container, such as your AWS access keys. For more information about AWS profiles, see Configure your AWS profile.

    Note

    If App2Container detects an instance profile for your server, the init command prompts if you want to use it. If you don't specify any value, App2Container uses your AWS default profile.

  • Amazon S3 bucket – You can optionally provide the name of an Amazon S3 bucket where you can extract artifacts using the extract command. The containerize command uses the extracted components to create the application container if the Amazon S3 bucket is configured. The default is no bucket.

  • You can optionally upload logs and command-generated artifacts automatically to App2Container support when an app2container command crashes or encounters internal errors.

  • Permission to collect usage metrics – You can optionally allow App2Container to collect information about the host operating system, application type, and the app2container commands that you run. The default is to allow the collection of metrics.

  • Whether to enforce signed images – You can optionally require that images are signed using Docker Content Trust (DCT). The default is no.

Step 3: Analyze your application

On the application server, use the following procedure to prepare to containerize the application.

To prepare for containerization

  1. Run the inventory command as follows to list the ASP.NET applications that are running on your server.

    PS> app2container inventory

    The output includes a JSON object collection with one entry for each application. Each application object will include key/value pairs as shown in the following example.

    "iis-app-id": { "siteName": My site name, "bindings": "http/*:80:", "applicationType": "iis", "discoveredWebApps": [ "app1", "app2" ] }
  2. Locate the application ID for the application to convert in the JSON output of the inventory command, and then run the analyze command as follows, replacing iis-app-id with the application ID that you located.

    PS> app2container analyze --application-id iis-app-id

    The output is a JSON file, analysis.json, stored in the workspace directory that you specified when you ran the init command.

  3. (Optional) You can edit the information in the containerParameters section of analysis.json as needed before continuing to the next step.

Step 4: Transform your application

The transform phase depends on whether you are running all steps on the application server or using the application server for the analysis and a worker machine for containerization and deployment.

To containerize the application on the application server

If you are using an application server for all steps, run the containerize command as follows.

PS> app2container containerize --application-id iis-app-id

The output is a set of deployment files stored in the workspace directory that you specified when you ran the init command.

To containerize the application on a worker machine

If you are using a worker machine for containerization and deployment, use the following procedure to transform the application.

  1. On the application server, run the extract command as follows.

    PS> app2container extract --application-id iis-app-id
  2. If you specified an Amazon S3 bucket when you ran the init command, the archive is extracted to that location. Otherwise, you can manually copy the resulting archive file to the worker machine.

  3. On the worker machine, run the containerize command as follows.

    PS> app2container containerize --input-archive drive:\path\extraction-file.zip

    The output is a set of deployment artifacts that are stored in the workspace directory that you specified when you ran the init command.

Step 5: Deploy your application

Run the generate app-deployment command as follows to deploy the application on AWS.

PS> app2container generate app-deployment --application-id iis-smarts-51d2dbf8

You have now created deployment artifacts for your application! You can find the deployment artifacts that the generate app-deployment command created for you in the local directory for your application.

Applications using Windows authentication

For applications using Windows authentication, you can use the gMSAParameters inside of the deployment.json file to set the gMSA-related artifacts automatically during generation of your AWS CloudFormation template.

Perform the actions in the list below once per Active Directory domain before you update the gMSA parameters.

  • Set up a secret in SecretsManager that stores the Domain credentials with the following key value pairs:

    Key Value
    Username <DomainNetBIOSName>\<DomainUser>
    Password <DomainUserPassword>
  • For the VPC with the Domain Controller, verify that the DHCP options are set to reach the Domain Controller. The options for DomainName and DomainNameServers must be set correctly. See DHCP options sets for more information about how to set DHCP options.

Step 6: Clean up

To remove App2Container from your application server or worker machine, delete the C:\Users\Administrator\app2container folder where it is installed, and then remove this folder from your path.

To clean up your AWS profile, see Removing Credential Profiles in the AWS Tools for Windows PowerShell User Guide.