Getting started with AWS App2Container
AWS App2Container is a tool that helps you break down the work of moving your applications into containers, and configuring them to be hosted in AWS using the Amazon ECS, Amazon EKS, or App Runner container management services.
The following sections demonstrate the initial setup of your containerization environment, starting with prerequisites and initial workflow decisions. Then we take you step by step through containerizing a basic application using App2Container. We generate the artifacts that you can use to deploy it on Amazon ECS, Amazon EKS, or AWS App Runner, and then we clean up.
Note
To avoid creating billable AWS resources, we stop before the final deployment. You can review the deployment artifacts that are created by the generate app-deployment command to see what we would create.
For an overview of the command phases that includes summary information and command reference links for all of the App2Container commands, see the App2Container command reference.
Contents
Understand 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
.
Decide where containerization will run
To use App2Container on the server where the applications are running, you must set up an AWS profile, 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.
-
You prefer to use a dedicated server to run the containerization and deployment steps.
-
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.
Prerequisites: Set up your servers
Before you use App2Container for the first time, make sure that your application environment meets all of the requirements that are listed for your operating system (OS) platform in the Supported applications section of this guide.
Choose the tab that matches your operating system (OS) platform to continue:
To run on a Linux platform, App2Container has the following additional requirements for the servers where you run App2Container commands. This includes application servers and the worker machine, if you have one configured.
-
There are one or more Java applications running on each application server whose inventory is the subject of the analyze or remote analyze command.
-
You have root access on the servers.
-
The servers have tar and at least 20 GB of free space.
Complete the following tasks before you use App2Container for the first time.
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
Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.
When you sign up for an AWS account, an AWS account root user is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform tasks that require root user access.
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 different 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.
Note
You 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.
For Linux application servers, you can use SSH key-based or SSH certificate-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.
Certificate-based connections
By default, App2Container trusts the certificate, and does not verify its
validity before connecting to your application server. To change this
behavior, set the acceptCerts
attribute to
false
in the init.json
file.
Configure your AWS profile
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.
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 configuring your AWS profile. 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 configure your AWS profile, follow the instructions on the tab that matches your command line tool.
To install the AWS CLI and set up your AWS profile, follow these steps:
-
Install the AWS CLI according to the instructions in the AWS Command Line Interface User Guide. For more information, see Installing the AWS CLI.
-
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.
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 Dockerfiles 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.
Use the following procedure to install Docker on Linux.
To install the Docker engine
-
Install Docker version 17.07 or later
Choose your Linux distribution from the following options, and follow instructions to download and install the Docker engine, using the links provided.
- 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
.
-
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 finished downloading, it displays a "Hello" message followed by information on how this command verified your installation of Docker.
Step 1: Install App2Container
To get started with App2Container, the first step is to download and install the application. To help ensure a successful installation, you can verify the integrity and authenticity of the binary file before installing it.
Tip
For Amazon EC2 instances, you can perform Step 1, Step 2, Step 3, and Step 4 by using an AWS Systems Manager Automation runbook. For more information, see App2Container Automation runbook.
If you prefer, you can replatform your applications running on Amazon EC2 to containers and
deploy them to Amazon ECS on AWS Fargate with a console-based experience by using the
Replatform applications to Amazon ECS template in the Migration Hub Orchestrator console
Choose the tab that matches your operating system (OS) platform to continue:
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 use an application server and a worker machine, you must install App2Container on both.
To download and install App2Container for Linux
-
Download the installation file 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
.
-
-
Extract the package to a local folder on the server.
$
sudo tar xvf AWSApp2Container-installer-linux.tar.gz
-
Run the install script that you extracted from the package and follow the prompts.
$
sudo ./install.sh
To check the downloaded tar.gz installer archive for integrity, you can validate the SHA256 hash of the local file against the published hash file.
Verify the integrity of the download
-
Generate hashes to verify
From the directory where you downloaded your tar.gz installer, run the following command to generate the hash of the downloaded tar.gz file.
$
sha256sum AWSApp2Container-installer-linux.tar.gz
9482952019adb6df96c7be773aa20ecb8de559083b99c270c67c34da56dd8dee AWSApp2Container-installer-linux.tar.gz
-
Verify hashes against the public file
Download the App2Container hash file from Amazon S3 with the following link, and compare the contents to the hash that you generated in step 1:
-
Download the App2Container hash file from Amazon S3:AWSApp2Container-installer-linux.tar.gz.sha256
.
-
To verify the authenticity of the download, run the following commands to download the certificate and signature files, and verify the signature.
Verify the authenticity of the download
-
Download the App2Container certificate:
curl -o app2container.cert https://app2container-keys.s3.us-east-1.amazonaws.com/latest/app2container.cert
-
Download the App2Container signature file:
curl -o app2container.sig https://app2container-release-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/app2container.sig
-
Verify the signature:
openssl dgst -sha256 -verify app2container.cert -signature app2container.sig /usr/bin/app2container
Step 2: Initialize App2Container
The containerization process consists of several distinct phases. This step focuses on the initialization phase, during which you initialize App2Container's global settings, and configure remote command settings if you are using a worker machine.
The init command performs one-time initialization tasks for App2Container. This interactive command prompts for the information required to set up the local App2Container environment. Run this command before you run any other App2Container commands. For more information, see the init command reference page.
If you are using a worker machine to run commands remotely on application servers, you must also run the remote configure command on the worker machine. For more information, see the remote configure command reference page.
Choose the tab that matches your operating system (OS) platform to continue:
On each server where you installed App2Container, run the init 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.
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
After you have completed setup and initialization tasks on your servers, you can begin to analyze your applications. During the analysis phase, you take inventory of the applications running on your application servers, and analyze specific applications within your inventory.
Choose the tab that matches your operating system (OS) platform to continue:
On the application server, follow these steps to prepare to containerize the applications.
Prepare for containerization
-
Run the inventory 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 ...", "applicationType": "java-apptype
" } -
Locate the application ID for the application to containerize in the JSON output of the inventory command, and then run the analyze 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 file,
analysis.json
, stored in the workspace directory that you specified when you ran the init command. -
(Optional) You can edit the information in the
containerParameters
section ofanalysis.json
as needed before continuing to the next step.
Step 4: Transform your application
Now that your application has gone through the analysis phase, it's ready for containerization. The transform phase creates the containers that your application runs in after you deploy it to Amazon ECS, Amazon EKS, or App Runner, if eligible. For more information about how App2Container integrates with container management services and other products, see Product and service integrations for AWS App2Container.
Choose the tab that matches your operating system (OS) platform to continue:
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 command as follows.
$
sudo app2container containerize --application-id
java-app-id
The output is a set of deployment files that are 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.
-
On the application server, run the extract command as follows.
$
sudo app2container extract --application-id
java-app-id
-
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.
-
On the worker machine, run the containerize command as follows.
$
sudo app2container containerize --input-archive /
path
/extraction-file
.tarThe 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
After your application has gone through containerization, it's ready to deploy to Amazon ECS, Amazon EKS, or App Runner, if eligible. When you run the generate app-deployment command, App2Container creates an Amazon ECR repository where it stores your application container artifacts for deployment. It also creates deployment configuration files that you can deploy as follows:
-
You can customize the deployment files, and have complete control over the deployment by running the AWS commands for your destination container management environment. When you run the generate app-deployment command without the
--deploy
option, App2Container returns instructions that you can use to deploy manually. -
If you're sure that you won't need to customize your deployment files, App2Container can optionally deploy your application containers directly to the container management environment that you have configured. To choose this option, run the generate app-deployment command with the
--deploy
option. You can verify the settings that App2Container used for the deployment by reviewing the deployment configuration files.
The deployment phase includes the option to create a deployment pipeline using the generate pipeline command. That step is not covered here, in order to prevent any unexpected charges for AWS resources. For more information, see app2container generate pipeline command in the command reference section.
Choose the tab that matches your operating system (OS) platform to continue:
Run the generate app-deployment 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 find the deployment artifacts that the generate app-deployment command created for you in the local directory for your application.
Step 6: Clean up
If you explored deployment options outside of the steps that we covered for this tutorial, make sure that you tear down any application stacks that might have been created, and verify that you have removed any artifacts that were created in the process.
Choose the tab that matches your operating system (OS) platform to continue:
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.