AWS App2Container

(1)

AWS App2Container

User Guide

(2)

AWS App2Container: User Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is AWS App2Container?

AWS App2Container (A2C) is a command line tool to help you lift and shift applications that run in your on-premises data centers or on virtual machines, so that they run in containers that are managed by Amazon ECS, Amazon EKS, or AWS App Runner.

Moving legacy applications to containers is often the starting point toward application modernization.

There are many beneﬁts to containerization:

• Reduces operational overhead and infrastructure costs

• Increases development and deployment agility

• Standardizes build and deployment processes across an organization

Contents

• How App2Container works (p. 1)

• Accessing AWS through App2Container (p. 2)

• Pricing (p. 2)

How App2Container works

You can use App2Container to generate container images for one or more applications running on Windows or Linux servers that are compatible with the Open Containers Initiative (OCI). This includes commercial oﬀ-the-shelf applications (COTs). App2Container does not need source code for the application to containerize it.

You can use App2Container directly on the application servers that are running your applications, or perform the containerization and deployment steps on a worker machine.

App2Container performs the following tasks:

• Creates an inventory list for the application server that identiﬁes all running ASP.NET (Windows) and Java applications (Linux) that are candidates to containerize.

• Analyzes the runtime dependencies of supported applications that are running, including cooperating processes and network port dependencies.

• Extracts application artifacts for containerization and generates a Dockerﬁle.

• Initiates builds for the application container.

• Generates AWS artifacts and optionally deploys the containers on Amazon ECS, Amazon EKS, or AWS App Runner. For example:

• a CloudFormation template to conﬁgure required compute, network, and security infrastructure to deploy containers using Amazon ECS, Amazon EKS, or AWS App Runner.

• An Amazon ECR container image, Amazon ECS task deﬁnitions, or AWS CloudFormation templates for Amazon EKS or AWS App Runner that incorporate best practices for security and scalability of the application by integrating with various AWS services.

• When deploying directly, App2Container can upload AWS CloudFormation resources to an Amazon S3 bucket, and create a CloudFormation stack.

• Optionally creates a CI/CD pipeline with AWS CodePipeline and associated services, to automate building and deploying your application containers.

(7)

Accessing AWS through App2Container

When you initialize App2Container, you provide it with your AWS credentials. This allows App2Container to do the following:

• Store artifacts in Amazon S3, if you conﬁgured it to do so.

• Create and deploy application containers using AWS services such as Amazon ECS, Amazon EKS, and AWS App Runner.

• Create CI/CD pipelines using AWS CodePipeline.

Pricing

App2Container is oﬀered at no additional charge. You are charged only when you use other AWS services to run your containerized application, such as Amazon ECR, Amazon ECS, Amazon EKS, and AWS App Runner. For more information, see AWS Pricing.

(8)

Supported applications for Linux

Applications you can containerize using AWS App2Container

App2Container supports the following application types:

• Java applications (Linux)

• ASP.NET applications (Windows, Linux)

For supported application frameworks, App2Container targets only the application ﬁles and

dependencies that are needed for containerization, thereby minimizing the size of the resulting container image. This is known as application mode.

If App2Container does not ﬁnd a supported framework running on your application server, or if you have other dependent processes running on your server, App2Container takes a conservative approach to identifying dependencies. This is known as process mode. For process mode, all non-system ﬁles on the application server are included in the container image.

For more details on application and framework support, expand the section that matches the platform that your application runs on.

Important

App2Container does not containerize database layer components. If your application requires access to a database, you must conﬁgure your application container to have access to the database server.

Supported applications for Linux

App2Container supports identiﬁcation and containerization of Java and ASP.NET applications running on Linux.

Supported Linux distributions:

• Ubuntu

• CentOS

• RHEL

• Amazon Linux

For supported frameworks, and other language-speciﬁc details, choose the tab that matches the language your application is written in.

Java

For Java applications, App2Container identiﬁes Java processes, and can generate container images that replicate the running state of each process. App2Container determines which ﬁles to include in the application container image, based on the Java application framework.

Application mode is supported for the following Java application frameworks:

Supported frameworks

• Tomcat

• TomEE

• JBoss (standalone mode)

(9)

NoteContainerization is not supported for Java applications running on frameworks that are using Cluster/HA mode.

ASP.NET

For ASP.NET applications running on Linux, App2Container detects the .NET runtime version and containerizes the application using the corresponding runtime base images.

Supported .NET Core runtime versions

• .NET Core 3.1 – uses SDK version 3.1 as the base image for generic .NET Core applications (or the highest version if multiple versions are used). Single ﬁle applications use SDK:latest.

• .NET Core 5 – uses SDK version 5.0 as the base image for generic .NET Core applications (or the highest version if multiple versions are used). Single ﬁle applications use SDK:latest.

• .NET Core 6 – uses SDK version 6.0 as the base image for generic .NET Core applications (or the highest version if multiple versions are used). Single ﬁle applications use SDK:latest.

NoteProcess mode is not supported for ASP.NET applications running on .NET Core.

Supported applications for Windows

App2Container supports containerization of ASP.NET applications deployed on IIS, including IIS-hosted WCF applications, running on Windows Server 2016, Windows Server 2019, or Windows Server Core 2004. It uses Windows Server Core as a base image for its container artifacts, matching the Windows Server Core version to the operating system (OS) version of the server where you run containerization commands.

If you use a worker machine to containerize your application, the version matches your worker machine OS. If you are running containerization directly on application servers, the version matches your application server OS.

If your applications are running on Windows Server 2008 or 2012 R2, you might still be able to use App2Container by setting up a worker machine for containerization and deployment steps.

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

Application framework and system requirements

• Containerization commands must run on Windows OS versions that support containers: Windows Server 2016 or 2019, or Windows Server Core 2004. This can be the worker machine, if you conﬁgure one, or the application server.

• If you use a worker machine to run containerization commands, App2Container supports Windows Server 2008 and up for the application server.

• IIS 7.5 or later.

• .NET framework version 3.5 or later.

• Docker version 17.07 or later (to install).

Supported applications

• Simple ASP.NET applications running in a single container

• A Windows service running in a single container

• Complex ASP.NET applications that depend on WCF, running in a single container or multiple containers

(10)

Complex Windows .NET apps

• Complex ASP.NET applications that depend on Windows services or processes outside of IIS, running in a single container or multiple containers

• Complex, multi-node IIS or Windows service applications, running in a single container or multiple containers

Unsupported applications

• ASP.NET applications that use ﬁles and registries outside of IIS web application directories

• ASP.NET applications that depend on features of a Windows operating system version prior to Windows Server Core 2016

Containerizing complex Windows .NET applications with App2Container

Containerization for complex multi-tier Windows .NET applications requires careful planning. When functionality is shared between the root application and one or more lower-level or system applications, you need to make decisions about packaging, deployment, and orchestration for all of the components.

To summarize how AWS App2Container works to containerize a complex Windows .NET application, we'll visit each step in the App2Container workﬂow, and call out the highlights and things to consider.

Step 1: Setup and initialization

Setup and initialization are the same for complex Windows .NET applications as for other types of applications. Setup tasks include installing software, conﬁguring your AWS proﬁle and IAM permissions, and deciding which servers the App2Container commands should run on. To learn more about

setting up your environment before running App2Container for the ﬁrst time, see Setting up AWS App2Container (p. 15).

After you have completed the setup tasks, but before you use App2Container for the ﬁrst time, you must initialize the servers where you plan to run App2Container commands. To learn more about initialization and worker machine conﬁguration, see the Initialize (p. 93) section in the App2Container command reference (p. 93).

Step 2: Analysis phase

After you have completed setup and initialization tasks on your servers, App2Container helps you to take an inventory of your running applications, and perform analysis to determine what should be included in your application containers.

Inventory

The first step in the analysis phase is to take an inventory of your applications. When you run the app2container inventory command (or the app2container remote inventory command, if you have configured a worker machine), App2Container detects the applications that are running in IIS. It also detects the Windows services that could be configured as dependent application components.

App2Container identifies each IIS application or Windows service as a separate application, with its own application ID in the inventory.json file. App2Container makes an effort to exclude basic operating system services that you would not want to add to your containers. However, even when these services are excluded, the inventory list can still be quite long.

To narrow the results of the app2container inventory or app2container remote inventory commands, you can specify what type of application you are looking for with the --type option:

(11)

• To run an inventory of your IIS applications, you can set the --type option to "iis".

• To run an inventory of your Windows services, you can set the --type option to "service".

If you don't want App2Container to ﬁlter inventory results at all, you can use the --nofilter option.

This option prevents App2Container from ﬁltering out default system services when building the inventory list. For more information and command syntax, see the inventory (p. 116) or remote inventory (p. 124) command in the command reference section.

Analysis

When you run the app2container analyze or app2container remote analyze commands, App2Container analyzes the application component that you specify with the --application-id parameter.

App2Container creates the folder structure for the application component, inside of the App2Container directory on your application server or worker machine. It produces the analysis.json file, and saves it to the new folder structure, along with other artifacts that are required for containerization. The analysis.json file is where you begin to define your container structure.

TipRun the app2container analyze or app2container remote analyze command for every component in your multi-tier application before you conﬁgure your container structure.

You can implement the following container structures for a multi-tier Windows .NET application:

• Multiple application components running in separate containers (recommended)

In this scenario, each application component in your multi-tier Windows .NET application runs in a separate container. Relationships between the root application and up to two dependent applications are configured in the deployment.json file for the root application. This file is produced during the containerization phase.

When your application components are running in separate containers, leave the additionalApps array in the analysis.json ﬁle empty for all components.

• Multiple application components running in a single container

In this scenario, the application components in a multi-tier Windows .NET application run together in one container. We recommend that packaging multiple application components in a single container is only done when there are cross-dependencies between the components.

To specify multiple application components running in a single container, you can include up to ﬁve dependent component application IDs in the additionalApps array in the analysis.json ﬁle for the root application.

NoteThis conﬁguration has the following limitations:

• Only the port that is defined for the root application is exposed to outside traffic through your load balancer. Ports that are defined for other application components are exposed only from the container, and are not accessible through the load balancer.

• If you are using remote commands on a worker machine, all of the application components in a multi-tier application must be running on the same application server if you want them to run in a single container.

To learn more about configuring containers, see Configuring application containers (p. 32). To compare configuration examples for a simple .NET application, and for complex multi-tier .NET applications, expand the Containers running on Windows section, and explore the example tabs.

For more information and command syntax, see the analyze (p. 96) or remote analyze (p. 118) command in the command reference section.

(12)

Step 3: Containerization

This phase creates containers for your application, based on the output of the analysis phase and on your conﬁguration in the analysis.json ﬁle.

Extract

If you are using a worker machine to run App2Container commands, or if you want to store an application archive for reference, this phase starts with an app2container extract or app2container remote extract command. Because this has no eﬀect on the conﬁguration for multi-tier application containers, we will not cover that here.

Containerize

The app2container containerize command performs the following tasks for the application that's speciﬁed in the --application id parameter:

• Extracts application artifacts from the server it runs on, or reads from an extract archive. For complex multi-tier applications, the extract includes all artifacts that are needed for all of the components running in the container.

• Generates a Dockerﬁle and a container image, based on the application artifacts and the application settings in the analysis.json ﬁle.

• Creates the deployment.json ﬁle that deﬁnes initial settings for container deployment during the deployment phase.

You must run the app2container containerize command for the root application container, and for each additional application component that runs in a separate container. Do not run the command for any components that are included in the root application container. The command displays real-time task completion messages, followed by instructions for next steps. This includes the AWS commands that you run if you are deploying manually.

To conﬁgure the deployment.json ﬁle for a complex multi-tier application, refer to the following scenario that describes your implementation:

• Multiple application components running in separate containers

In this scenario, each application component is running in a separate container, and each has its own deployment ﬁle. Before running the generate app-deployment command, conﬁgure the

deployment.json ﬁle for the root application to include all dependent applications or services in the dependentApps array, including the application ID, private root domain, and DNS record name for each one.

• Multiple application components running in a single container

If you are running multiple application components in a single container, the process for conﬁguring the deployment.json ﬁle is the same as for any other containerized application. Leave the dependentApps array empty.

Note

If you are deploying to a speciﬁc VPC, make sure that all components point to that VPC in the vpcId parameter in the reuseResources array in the deployment.json ﬁle.

To learn more about configuring your deployment.json file, see Configuring container deployment (p. 45). For more information and command syntax for creating your application container, see the containerize (p. 97) command in the command reference section.

(13)

Step 4: Deployment

Deployment steps for complex Windows .NET applications with multiple application components running in a single container are handled the same as any other application deployment. For more information and command syntax for deploying your application container, see the generate app- deployment (p. 102) command in the command reference section.

The remainder of the content in this section applies to complex Windows .NET applications that have multiple application components running in separate containers, similar to the application example shown in the following diagrams:

Amazon ECS deployment

(14)

Step 4: Deployment

Amazon EKS deployment

(15)

Normally, you run the generate app-deployment command for each application container that you create. However, with complex Windows .NET applications that have dependent applications running in separate containers, App2Container takes care of some of that for you. When you run the generate app-

(16)

Step 4: Deployment

deployment command for the root application, App2Container completes the following tasks for the root application and each of its dependent application components:

• Checks for AWS and Docker prerequisites.

• Creates an Amazon ECR repository.

• Pushes the container image to the Amazon ECR repository.

• Generates the following artifacts, depending on your target container management service:

Amazon ECS

• An Amazon ECS task deﬁnition.

• The ecs-master.yml ﬁle that you can use for Amazon ECS deployment.

Amazon EKS

• The Kubernetes eks-master.yml ﬁle that you can use for Amazon EKS deployment.

• The eks_deployment.yaml and eks_service.yaml ﬁles that you can use with the kubectl command.

• Generates a pipeline.json ﬁle.

Additionally, if you use the --deploy option, App2Container takes care of all of those deployments in the order in which they need to run, and conﬁgures shared infrastructure settings. When App2Container handles the deployment for you, it follows these conventions:

• The root application and all dependent application components are deployed to the same cluster.

• All dependent application components are conﬁgured with an internal load balancer only.

• Each application component has its own Amazon ECS or Amazon EKS service running in a shared cluster.

If you want to customize the deployment artifacts, you can deploy manually, using the AWS Management Console or AWS CLI when you are ready.

For deployment steps, choose the tab that matches your deployment scenario.

Automated (A2C)

Follow these steps if you are using the App2Container automated deployment.

1. Verify that the values are set correctly in the deployment.json ﬁles for all of your application components, before running the generate app-deployment command for your root application, as follows:

• None of the application components in the multi-tier application should specify reuseCfnStack.

• Dependent application components should not specify any of the following parameters:

vpcId, gMSAParameters.

• The following parameters can be speciﬁed in the root application, and App2Container applies the same values for all dependent application components: vpcId, resourceTags, and gMSAParameters.

2. The following example shows the generate app-deployment command for the root application in our sample multi-tier application, using the --deploy option, with the --application- id parameter set to the application ID for the root application. This example handles the full deployment for all application components.

(17)

PS> app2container generate app-deployment --deploy --application-id iis- colormvciis-b69c09ab --profile admin-profile

√ AWS prerequisite check succeeded

√ Docker prerequisite check succeeded

... [more notifications as deployment steps are completed for each dependent

application component, followed by the root application and shared configurations]

Deployment successful for application iis-colormvciis-b69c09ab The URL to your Load Balancer Endpoint is:

a2c-i-Publi-1A2BCD3EFGRW-4567890123.us-west-2.elb.amazonaws.com

Successfully created Amazon ECS stack a2c-iis-colormvciis-b69c09ab-ECS. Check the AWS CloudFormation Console for additional details.

3. Set up a pipeline for your application stack using app2container:

app2container generate pipeline --application-id iis-colormvciis-b69c09ab

The ﬁrst deployment for a dependent application component creates shared AWS resources, such as the VPC and Amazon ECS or Amazon EKS cluster. After the ﬁrst dependent application component is successfully deployed, App2Container updates deployment artifacts for all of the other application components to reference the shared AWS resources prior to completing the remaining deployments.

Manual (AWS CLI)

Follow these steps to customize your deployment ﬁles and use the AWS CLI to deploy manually.

We do not include AWS Management Console instructions here. However, you can follow the same general order of operations in the console.

1. Verify that the values are set correctly in the deployment.json ﬁles for all of your application components, before running the generate app-deployment command for your root application, as follows:

• None of the application components in the multi-tier application should specify reuseCfnStack.

• Dependent application components should not specify any of the following parameters:

vpcId, gMSAParameters.

• The following parameters can be speciﬁed in the root application, and App2Container applies the same values for all dependent application components: vpcId, resourceTags, and gMSAParameters.

2. The following example shows the generate app-deployment command for the root application in our sample multi-tier application, with the --application-id parameter set to the application ID for the root application. The --deploy option is not used in this case, as we plan to customize deployment ﬁles and then deploy using AWS CLI commands to control deployment for each application component.

NoteApp2Container creates deployment artifacts for all application components in the complex Windows .NET application when you run the generate app-deployment command for the root application.

Use the generate app-deployment command, specifying the application ID for your root application, as follows:

PS> app2container generate app-deployment --application-id iis-colormvciis-b69c09ab --profile admin-profile

√ AWS prerequisite check succeeded

(18)

Step 4: Deployment

√ Docker prerequisite check succeeded

... [more notifications as deployment steps are completed for each dependent component, followed by the root application and shared configurations]

CloudFormation templates and additional deployment artifacts generated successfully for application iis-colormvciis-b69c09ab

You're all set to use AWS CloudFormation to manage your application stack.

Next Steps:

1. Create application stacks for first dependent application using the AWS CLI or the AWS Console. AWS CLI commands:

aws cloudformation deploy --template-file C:\Users\Administrator\AppData

\Local\app2container\iis-dependentappb-12345bcd\EcsDeployment\ecs-master.yml -- capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND --stack-name a2c-iis- dependentappb-12345bcd-ECS

2. Required! Reuse the VpcId, ClusterId and PublicSubnets from above

CloudFormation console outputs and assign them in master templates of service- colorwindowsservice-69f90194, iis-colormvciis-b69c09ab

If your other dependent application(s) that share the same root domain, also assign HostedZoneId to their master template(s).

Create application stacks for remaining applications using the AWS CLI or the AWS Console. AWS CLI commands:

\Local\app2container\service-colorwindowsservice-69f90194\EcsDeployment\ecs- master.yml --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND --stack-name a2c-service-colorwindowsservice-69f90194-ECS

\Local\app2container\iis-colormvciis-b69c09ab\EcsDeployment\ecs-master.yml -- capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND --stack-name a2c-iis- colormvciis-b69c09ab-ECS

3. Set up a pipeline for your application stack using app2container:

app2container generate pipeline --application-id iis-colormvciis-b69c09ab 3. Review the deployment artifacts that were generated in the prior step, and customize the YAML

deployment templates and other deployment artifacts as needed.

Manual deployment follows this step, beginning with one of the dependent applications. The ﬁrst deployment creates any shared infrastructure that is required.

Note

If you are using an existing VPC, the vpcId that you speciﬁed in the

deployment.json ﬁle for the root application should be reﬂected in the YAML deployment templates for all of the dependent applications.

4. To deploy your ﬁrst dependent application and create shared infrastructure, run the following command in the AWS CLI, using your dependent application's details.

PS> aws cloudformation deploy --template-file C:\Users\Administrator\AppData

\Local\app2container\iis-dependentappb-12345bcd\EcsDeployment\ecs-master.yml -- capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND --stack-name a2c-iis- dependentappb-12345bcd-ECS

5. After your ﬁrst stack is ready (stack status is CREATE_COMPLETE), update the YAML deployment templates for all remaining application components in your application to reference the

following shared infrastructure in the parameters for existing resources:

• VpcId

• PublicSubnets

(19)

• ClusterId

Additionally, for any remaining dependent applications, update the following references:

• DomainName

• RecordName

• ExistingHostedZoneId – update this if dependent applications share the root domain, or if they are using an existing domain.

• RecordExist – set this to "true" (string) if the record already exists in the hosted zone. If you are creating a new domain, set this to "false". The default value is "true".

6. Deploy any remaining dependent applications, using your application component information and the updated YAML deployment templates, with the cloudformation deploy command.

The following command example deploys the service component in our sample multi-tier application.

PS> aws cloudformation deploy --template-file C:\Users\Administrator\AppData\Local

\app2container\service-colorwindowsservice-69f90194\EcsDeployment\ecs-master.yml -- capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND --stack-name a2c-service- colorwindowsservice-69f90194-ECS

7. After you've created all of your dependent component stacks, deploy your root application with the cloudformation deploy command. The following command example deploys the root application in our sample multi-tier application.

PS> aws cloudformation deploy --template-file C:\Users\Administrator\AppData\Local

\app2container\iis-colormvciis-b69c09ab\EcsDeployment\ecs-master.yml --capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND --stack-name a2c-iis-colormvciis- b69c09ab-ECS

TipIt can take a few minutes to spin up a CloudFormation stack, along with the other infrastructure that is created for your deployment. You can use one of the following methods to check the stack status for your deployment:

• Sign in to the AWS Management Console and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

In the console, you can see stacks that are being created, as well as existing stacks. For more information, see Viewing AWS CloudFormation stack data and resources on the AWS Management Console in the AWS CloudFormation User Guide.

• Use one of these AWS CloudFormation commands in the AWS CLI: list-stacks or describe- stacks. For more information, see Available Commands in the AWS CLI Command Reference.

• Use one of these AWS CloudFormation API commands: ListStacks or DescribeStacks. For more information, see Actions in the AWS CloudFormation API Reference.

(20)

Sign up for AWS

Setting up AWS App2Container

Complete these tasks before you use App2Container for the ﬁrst time.

Tasks

• Sign up for AWS (p. 15)

• Decide where containerization will run (p. 15)

• Grant permissions to run AWS App2Container commands (p. 16)

• Enable remote access for a worker machine (optional) (p. 16)

• Conﬁgure your AWS proﬁle (p. 17)

• Install the Docker engine (p. 18)

Sign up for AWS

When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS. You are charged only for the services that you use.

If you do not have an AWS account already, use the following procedure to create one.

To create an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Decide where containerization will run

To use App2Container on the server where the applications are running, you must set up an AWS proﬁle, install App2Container, and install the Docker engine. If your server does not meet the requirements to containerize your application and deploy it to AWS, or if you do not want to install the Docker engine on the application server, you can set up and use a worker machine. On the worker machine, you can run the steps to containerize your application and deploy it to AWS, or you can set up connectivity between the worker machine and the application servers to run remote commands from the worker machine, targeting the application servers.

The following are example situations where you might decide to set up a worker machine:

• Your application servers are running in an on-premises data center and they do not have internet access.

• Your application server is running on a Windows operating system that does not support containers.

For more information, see Supported applications (p. 3).

• You prefer to use a dedicated server to run the containerization and deployment steps.

(21)

• You want to consolidate your work by using a worker machine to run commands for all of your application servers.

When you set up a worker machine to handle the steps to containerize and deploy your applications, it must have the same operating system platform as your application server (Linux or Windows), and the operating system must support containers. We recommend that you launch an Amazon EC2 instance as the worker machine, using an Amazon Machine Image (AMI) that is optimized for Amazon ECS.

Grant permissions to run AWS App2Container commands

App2Container needs access to AWS services in order to run most of its commands. There are two very diﬀerent sets of permissions needed to run app2container commands.

• The general purpose IAM user, group, or role can run all of the commands except commands that are run with the --deploy option.

• For deployment, App2Container must be able to create or update AWS objects for container management services (Amazon ECR with Amazon ECS, Amazon EKS, or AWS App Runner), and to create CI/CD pipelines with AWS CodePipeline. This requires elevated permissions that should only be used for deployment.

We recommend that you create general purpose IAM resources, and if you plan to use App2Container to deploy your containers or create pipelines, that you create separate IAM resources for deployment.

For instructions on how to set up your IAM resources for App2Container, and policy examples that include resources and actions that App2Container needs access to, see Identity and access management in App2Container (p. 81).

NoteYou can use an instance profile to pass an IAM role to an Amazon EC2 instance. App2Container detects if there is an instance profile associated with the application server or worker machine when you run the init command. If it detects an instance profile, the init command prompts if you want to use it.

To find out more about using instance profiles, see Using instance profiles in the IAM User Guide.

Enable remote access for a worker machine (optional)

To enable your worker machine to run remote commands for your application servers, you must ensure that the worker machine can connect.

For the required setup to enable remote access, choose the operating system tab that matches your application server.

Linux

For Linux application servers, you can use SSH key-based or SSH Certiﬁcate-based connections. You must ensure that there is network connectivity between the worker machine and the application server, and verify that your worker machine can connect.

(22)

Conﬁgure your AWS proﬁle

Windows

To connect to a Windows application server from a Windows Server 2016 or 2019 worker machine, use the WinRM protocol. Your application server must meet the requirements that are listed for Windows in the Supported applications (p. 3) section of this user guide.

Note

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

1. Worker machine

To ensure that you can run PowerShell scripts on the worker machine, set the PowerShell Execution Policy to one of the following values:

RemoteSigned Example:

PS> Set-ExecutionPolicy RemoteSigned

Unrestricted Example:

PS> Set-ExecutionPolicy Unrestricted 2. Application servers

Complete the following steps on each application server to enable remote access from the worker machine.

1. Ensure network connectivity to the application server over WinRM port 5986.

2. Download the WinRMSetup.ps1 PowerShell script to your application server from the following location: WinRMSetup.ps1.

NoteChecksum ﬁles for this script can be downloaded using the following links:

• WinRMSetup.ps1.sha256

• WinRMSetup.ps1.md5

3. Download the New-SelfsignedCertiﬁcateEx.ps1 PowerShell script from the Microsoft Technet gallery. The WinRMSetup.ps1 PowerShell script from step 2 uses it to generate a self-signed certiﬁcate.

NoteThis script must run from the same directory where the WinRMSetup.ps1 PowerShell script from step 2 is located.

4. Run the WinRMSetup.ps1 PowerShell script on the application server. The script ensures that WinRM is enabled, and generates self-signed certiﬁcates that are used to secure the connection from the worker machine.

Conﬁgure your AWS proﬁle

AWS App2Container requires command line access to AWS resources for containerization and

deployment commands. It uses information from your AWS profile to configure access to AWS resources for your account. To run App2Container commands, you must install and configure a command line tool on the application servers and worker machines where you run the commands.

(23)

Note

• AWS Tools for Windows PowerShell is required for running App2Container commands in PowerShell on a Windows server.

• Tools for Windows PowerShell comes pre-installed on Windows-based Amazon Machine Images (AMIs). If your application server or worker machine is an Amazon EC2 instance that was launched from one of these AMIs, you can skip to conﬁguring your AWS proﬁle. See Shared credentials in the AWS Tools for Windows PowerShell User Guide for more details.

To install the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell command line tools, and to conﬁgure your AWS proﬁle, follow the instructions on the tab that matches your command line tool.

AWS CLI

To install the AWS CLI and set up your AWS proﬁle, follow these steps:

1. Install the AWS CLI according to the instructions in the AWS Command Line Interface User Guide.

For more information, see Installing the AWS CLI.

2. To configure your AWS default profile, use the aws configure command. For more information, see Configuration basics in the AWS Command Line Interface User Guide.

Tools for Windows PowerShell

To install Tools for Windows PowerShell and set up your AWS proﬁle, follow these steps:

1. Install the Tools for Windows PowerShell according to the instructions in the AWS Tools for Windows PowerShell User Guide. For more information see Installing the AWS Tools for Windows PowerShell.

2. To set up your AWS default proﬁle, use the Initialize-AWSDefaultConﬁguration cmdlet. For more information about shared credentials in Tools for Windows PowerShell, see Shared credentials in the AWS Tools for Windows PowerShell User Guide.

After you containerize your applications, you can also use the AWS CLI or Tools for Windows PowerShell to deploy them on AWS, though we recommend using the --deploy option with the generate app- deployment and generate pipeline commands to do your deployment.

Install the Docker engine

App2Container uses the Docker engine (Docker CE) to create container images and generate Dockerﬁles that run the containers hosted on Amazon ECS, Amazon EKS, or AWS App Runner. You must install the Docker engine on the application server or worker machine that you'll use to containerize the application using the containerize command.

Install Docker on Linux

Use the following procedure to install Docker on Linux.

To install the Docker engine 1. Install Docker

Choose your Linux distribution from the following options, and follow instructions to download and install the Docker engine, using the links provided.

(24)

Install the Docker engine

Amazon Linux

To download and install the Docker engine on Amazon Linux instances, see Docker basics for Amazon ECS in the Amazon Elastic Container Service Developer Guide. This works with any Amazon Linux instance.

RHEL

Recent versions of RHEL do not natively support the Docker engine. However, you can still download and install the Docker engine on RHEL to create containers that will be hosted and run on Amazon ECS, Amazon EKS, or AWS App Runner. To do this, follow the instructions given for CentOS on the Docker website: Install Docker engine.

All other supported distributions (CentOS, Ubuntu)

To download and install the Docker engine for other supported Linux distributions, follow the instructions for your Linux distribution on the Docker website: Install Docker engine.

2. Verify the Docker installation

To verify that your Docker installation was successful, run the following command.

$ docker run -it hello-world

When the command runs, it pulls the latest hello-world application from the Docker repository, if applicable. When the application has ﬁnished downloading, it displays a "Hello" message followed by information on how this command veriﬁed your installation of Docker.

Install Docker on Windows

Use the following procedure to install Docker on Windows.

To install the Docker engine

1. Install Docker version 17.07 or later

To download and install the Docker engine on Windows, see Get started: Prep Windows for containers (Install Docker section).

2. Verify the Docker installation

To verify that your Docker installation was successful, run the following command.

PS> docker run -it hello-world

When the command runs, it pulls the latest hello-world application from the Docker repository, if applicable. When the application has ﬁnished downloading, it displays a "Hello" message followed by information on how this command veriﬁed your installation of Docker.

(25)

Getting started with AWS App2Container

AWS App2Container is a tool that helps you break down the work of moving your applications into containers, and conﬁguring them to be hosted in AWS using the Amazon ECS, Amazon EKS, or App Runner container management services. Explore the resources listed below to help you get started with containers. Or to get started using App2Container commands, skip to the tutorial for the operating system that your application runs on.

Understanding Docker containers

The following resources can help you get the most out of your application containers by understanding what goes into them.

• To learn more about Docker containers on AWS, see What is Docker?.

• Use the Docker command line reference to look up Docker commands. See Use the Docker command line.

Tutorials

These tutorials walk you through the basics of using App2Container to containerize your applications.

• Containerizing a Java application on Linux (p. 20)

• Containerizing a .NET application on Windows (p. 24)

Containerizing a Java application on Linux

This tutorial takes you through the steps to containerize a legacy Java application on Linux 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.

Tasks

• Prerequisites (p. 20)

• Step 1: Install App2Container (p. 21)

• Step 2: Initialize App2Container (p. 22)

• Step 3: Analyze your application (p. 22)

• Step 4: Transform your application (p. 23)

• Step 5: Deploy your application (p. 23)

• Step 6: Clean up (p. 24)

Prerequisites

Verify that you have completed the following prerequisites:

(26)

Step 1: Install App2Container

• Your application environment meets all of the requirements that are listed in the Supported applications (p. 3) section.

• You installed the AWS CLI and configured the AWS profile on your server. See Configure your AWS profile (p. 17) 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 (p. 18) in the Setting up section of this user guide for more information.

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

• You have root access on the application server (and worker machine, if using).

• The application server (and worker machine, if using) has tar and 20 GB of free space.

Step 1: Install App2Container

App2Container for Linux is packaged as a tar.gz archive. The archive contains an interactive shell script that installs App2Container on your server. If you are using an application server and a worker machine, you must install App2Container on both.

To download and install App2Container for Linux 1. Download the installation ﬁle in one of the following ways:

• Use the curl command to download the App2Container installation package from Amazon S3.

$ curl -o AWSApp2Container-installer-linux.tar.gz https://app2container-release- us-east-1.s3.us-east-1.amazonaws.com/latest/linux/AWSApp2Container-installer- linux.tar.gz

• Use your browser to download the installer from the following URL: https://app2container- release-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/AWSApp2Container-installer- linux.tar.gz.

2. Extract the package to a local folder on the server.

$ sudo tar xvf AWSApp2Container-installer-linux.tar.gz

3. Run the install script that you extracted from the package and follow the prompts.

$ sudo ./install.sh

You can check the downloaded tar.gz installer archive for integrity by validating the MD5 and SHA256 hashes of the local ﬁle against the published hash ﬁles.

To verify the authenticity of the download 1. Generate hashes to verify

From the directory where you downloaded your tar.gz installer, run the following commands to generate the hash of the downloaded tar.gz ﬁle.

$ md5sum AWSApp2Container-installer-linux.tar.gz

db91552c07b582efe23d87ef4c4d7f44 AWSApp2Container-installer-linux.tar.gz

$ sha256sum AWSApp2Container-installer-linux.tar.gz

9482952019adb6df96c7be773aa20ecb8de559083b99c270c67c34da56dd8dee AWSApp2Container- installer-linux.tar.gz

(27)

2. Verify hashes against public ﬁles

Download the App2Container hash ﬁles from Amazon S3 using the following links, and compare the contents to the hashes that you generated in step 1:

• AWSApp2Container-installer-linux.tar.gz.md5.

• AWSApp2Container-installer-linux.tar.gz.sha256.

Step 2: Initialize App2Container

On each server where you installed App2Container, run the init (p. 113) command as follows.

$ sudo 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 /root/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 (p. 17).

Note

If App2Container detects an instance proﬁle 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 proﬁle.

• 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 conﬁgured. 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 (p. 116) command as follows to list the Java applications that are running on your server.

$ sudo 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.

"java-app-id": { "processId": pid,

"cmdline": "/user/bin/java ...",

(28)

Step 4: Transform your application

"applicationType": "java-apptype"

}

2. Locate the application ID for the application to convert in the JSON output of the inventory command, and then run the analyze (p. 96) command as follows, replacing java-app-id with the application ID that you located.

$ sudo app2container analyze --application-id java-app-id

The output is a JSON ﬁle, analysis.json, stored in the workspace directory that you speciﬁed 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 are 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 (p. 97) command as follows.

$ sudo app2container containerize --application-id java-app-id

The output is a set of deployment ﬁles that are stored in the workspace directory that you speciﬁed 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 (p. 100) command as follows.

$ sudo app2container extract --application-id java-app-id

2. If you speciﬁed 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 ﬁle to the worker machine.

3. On the worker machine, run the containerize (p. 97) command as follows.

$ sudo app2container containerize --input-archive /path/extraction-file.tar The output is a set of deployment artifacts that are stored in the workspace directory that you speciﬁed when you ran the init command.

Step 5: Deploy your application

Run the generate app-deployment (p. 102) command as follows to deploy the application on AWS.

$ sudo app2container generate app-deployment --application-id java-app-id

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

(29)

Step 6: Clean up

To remove App2Container from your application server or worker machine, delete the /usr/local/

app2container folder where it is installed, and then remove this folder from your path.

To clean up your AWS profile, use the aws configure set command. For more information, see Set and view configuration settings in the AWS Command Line Interface User Guide.

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.

Tasks

• Prerequisites (p. 20)

• Step 1: Install App2Container (p. 24)

• Step 2: Initialize App2Container (p. 25)

• Step 3: Analyze your application (p. 25)

• Step 4: Transform your application (p. 26)

• Step 5: Deploy your application (p. 27)

• Step 6: Clean up (p. 27)

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 (p. 3) section.

• You installed the AWS Tools for Windows PowerShell to configure the AWS profile on your server. See Configure your AWS profile (p. 17) 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 (p. 18) 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.

NoteApp2Container 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.

(30)

Step 2: Initialize App2Container

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 (p. 113) 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 (p. 17).

NoteIf App2Container detects an instance proﬁle 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 proﬁle.

• 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 conﬁgured. 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 (p. 116) command as follows to list the ASP.NET applications that are running on your server.

(31)

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 (p. 96) 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 ﬁle, analysis.json, stored in the workspace directory that you speciﬁed 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 (p. 97) command as follows.

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

The output is a set of deployment ﬁles stored in the workspace directory that you speciﬁed 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 (p. 100) command as follows.

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

2. If you speciﬁed 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 ﬁle to the worker machine.

3. On the worker machine, run the containerize (p. 97) command as follows.

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

(32)

Step 5: Deploy your application

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

Step 5: Deploy your application

Run the generate app-deployment (p. 102) 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 ﬁnd 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 ﬁle 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 proﬁle, see Removing Credential Proﬁles in the AWS Tools for Windows PowerShell User Guide.

(33)

Conﬁguring your application

Containerizing your application and creating pipelines with App2Container requires configuration throughout the process. This section of the guide describes the configuration files that are created by app2container commands, the fields that they contain, and which fields are configurable.

App2Container commands primarily generate JSON conﬁguration ﬁles, using standard JSON notation.

Field details for the ﬁles included here indicate where there are speciﬁc requirements for the values.

App2Container also generates YAML format CloudFormation templates when you run the generate app- deployment command. However, those are not covered in this section, as their content is dictated by the target container management environment, such as Amazon ECS, Amazon EKS, or AWS App Runner.

For more information about how App2Container works with these services, see Product and service integrations for AWS App2Container (p. 61).

Creating IAM resources is also covered separately, under the Security section. For more information and instructions about how to set up IAM resources for App2Container, see Identity and access management in App2Container (p. 81).

You can consolidate your containerization workload by configuring connections to your application servers to run containerization workflows remotely, using App2Container remote commands from your worker machine. Prior to running remote commands, you must configure the connections that the worker machine uses for its target application servers. For more information on configuring connections, see the remote configure (p. 120) command reference page.

Contents

• Manage secrets for AWS App2Container (p. 28)

• Conﬁguring application containers (p. 32)

• Conﬁguring container deployment (p. 45)

• Conﬁguring container pipelines (p. 57)

Manage secrets for AWS App2Container

App2Container uses AWS Secrets Manager to manage the credentials for connecting your worker machine to application servers in order to run remote commands. Secrets Manager encrypts your secrets for storage, and provides an Amazon Resource Name (ARN) for you to access the secret. When you run the remote conﬁgure command, you provide the secret ARN for App2Container to use to connect to your target server when running the remote command. For more information about Secrets Manager, see What Is AWS Secrets Manager?

Create remote access secrets (console)

The secret that App2Container uses to connect to an application server varies, based on the application server's operating system platform. To see more information about storing secrets for your application server, choose the platform section that matches.

Application server platform

• Create a remote access secret for Linux (p. 29)

• Create a remote access secret for Windows (p. 29)

AWS App2Container

AWS App2Container

User Guide

AWS App2Container: User Guide

Table of Contents

What is AWS App2Container?

How App2Container works

Accessing AWS through App2Container

Pricing

Applications you can containerize using AWS App2Container

Supported applications for Linux

Supported applications for Windows

Containerizing complex Windows .NET applications with App2Container

Step 1: Setup and initialization

Step 2: Analysis phase

Step 3: Containerization

Step 4: Deployment

Setting up AWS App2Container

Sign up for AWS

Decide where containerization will run

Grant permissions to run AWS App2Container commands

Enable remote access for a worker machine (optional)

Conﬁgure your AWS proﬁle

Install the Docker engine

Install Docker on Linux

Install Docker on Windows

Getting started with AWS App2Container

Understanding Docker containers

Tutorials

Containerizing a Java application on Linux

Prerequisites

Step 1: Install App2Container

Step 2: Initialize App2Container

Step 3: Analyze your application

Step 4: Transform your application

Step 5: Deploy your application

Step 6: Clean up

Containerizing a .NET application on Windows

Prerequisites

Step 1: Install App2Container

Step 2: Initialize App2Container

Step 3: Analyze your application

Step 4: Transform your application

Step 5: Deploy your application

Step 6: Clean up

Conﬁguring your application

Manage secrets for AWS App2Container

Create remote access secrets (console)