Manage on-premises container applications by setting up Amazon ECS Anywhere with the AWS CDK - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resources

Manage on-premises container applications by setting up Amazon ECS Anywhere with the AWS CDK

Created by Dr. Rahul Sharad Gaikwad (AWS)

Code repository: amazon-ecs-anywhere-cdk-samples

Environment: PoC or pilot

Technologies: Modernization; Containers & microservices; DevOps; Hybrid cloud; Infrastructure

Workload: All other workloads

AWS services: AWS CDK; Amazon ECS; AWS Identity and Access Management

Summary

Amazon ECS Anywhere is an extension of the Amazon Elastic Container Service (Amazon ECS). You can use ECS Anywhere to deploy native Amazon ECS tasks in an on-premises or customer-managed environment. This feature helps reduce costs and mitigate complex local container orchestration and operations. You can use ECS Anywhere to deploy and run container applications in both on-premises and cloud environments. It removes the need for your team to learn multiple domains and skill sets, or to manage complex software on their own.

This pattern demonstrates the steps to set up ECS Anywhere by using AWS Cloud Development Kit (AWS CDK) stacks.

Prerequisites and limitations

Prerequisites 

Limitations 

Product versions

  • AWS CDK Toolkit version 2

  • npm version 7.20.3 or later

  • Node.js version 16.6.1 or later

Architecture

Target technology stack  

  • AWS CloudFormation

  • AWS CDK

  • Amazon ECS Anywhere

  • AWS Identity and Access Management (IAM)

Target architecture 

The following diagram illustrates a high-level system architecture of ECS Anywhere setup using the AWS CDK with TypeScript, as implemented by this pattern.

  1. When you deploy the AWS CDK stack, it creates a CloudFormation stack on AWS.

  2. The CloudFormation stack provisions an Amazon ECS cluster and related AWS resources.

  3. To register an external instance with an Amazon ECS cluster, you must install AWS Systems Manager Agent (SSM Agent) on your virtual machine (VM) and register the VM as an AWS Systems Manager managed instance. 

  4. You must also install the Amazon ECS container agent and Docker on your VM to register it as an external instance with the Amazon ECS cluster.

  5. When the external instance is registered and configured with the Amazon ECS cluster, it can run multiple containers on your VM, which is registered as an external instance.

Automation and scale

The GitHub repository that is provided with this pattern uses the AWS CDK as an infrastructure as code (IaC) tool to create the configuration for this architecture. AWS CDK helps you orchestrate resources and set up ECS Anywhere.

Tools

Code

The source code for this pattern is available on GitHub, in the Amazon ECS Anywhere CDK Samples repository. To clone and use the repository, follow the instructions in the next section.

Epics

TaskDescriptionSkills required

Verify the AWS CDK version.

Verify the version of the AWS CDK Toolkit by running the following command:

cdk --version

This pattern requires AWS CDK version 2. If you have an earlier version of the AWS CDK, follow the instructions in the AWS CDK documentation to update it.

DevOps engineer

Set up AWS credentials.

To set up credentials, run the aws configure command and follow the prompts:

$aws configure
AWS Access Key ID [None]: <your-access-key-ID>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: <your-Region-name>
Default output format [None]:
DevOps engineer
TaskDescriptionSkills required

Clone the AWS CDK code repository.

Clone the GitHub code repository for this pattern by using the command:

git clone https://github.com/aws-samples/amazon-ecs-anywhere-cdk-samples.git
DevOps engineer

Bootstrap the environment.

To deploy the AWS CloudFormation template to the account and AWS Region that you want to use, run the following command:

cdk bootstrap <account-number>/<Region>

For more information, see Bootstrapping in the AWS CDK documentation.

DevOps engineer
TaskDescriptionSkills required

Install package dependencies and compile TypeScript files.

Install the package dependencies and compile the TypeScript files by running the following commands:

$cd amazon-ecs-anywhere-cdk-samples
$npm install
$npm fund

These commands install all the packages from the sample repository. 

Important: If you get any errors about missing packages, use one of the following commands:

$npm ci

—or—

$npm install -g @aws-cdk/<package_name>

For more information, see npm ci and  npm install in the npm documentation.

DevOps engineer

Build the project.

To build the project code, run the command:

npm run build

For more information about building and deploying the project, see Your first AWS CDK app in the AWS CDK documentation.

DevOps engineer

Deploy the project.

To deploy the project code, run the command:

cdk deploy
DevOps engineer

Verify stack creation and output.

Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation, and choose the EcsAnywhereStack stack. The Outputs tab shows the commands to run on your external VM.

DevOps engineer
TaskDescriptionSkills required

Set up your VM by using Vagrant.

For demonstration purposes, you can use HashiCorp Vagrant to create a VM. Vagrant is an open-source utility for building and maintaining portable virtual software development environments. Create a Vagrant VM by running the vagrant up command from the root directory where Vagrantfile is placed. For more information, see the Vagrant documentation.

DevOps engineer

Register your VM as an external instance.

1. Log in to the Vagrant VM by using the vagrant ssh command. For more information, see the Vagrant documentation.

2. Create an activation code and ID that you can use to register your VM with AWS Systems Manager and to activate your external instance. The output from this command includes ActivationId and ActivationCode values: 

aws ssm create-activation --iam-role EcsAnywhereInstanceRole | tee ssm-activation.json

3. Export the activation ID and code values:

export ACTIVATION_ID=<activation-ID>
export ACTIVATION_CODE=<activation-code>

4. Download the installation script to your on-premises server or VM:

curl -o "ecs-anywhere-install.sh" "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh" && sudo chmod +x ecs-anywhere-install.sh

5. Run the installation script on your on-premises server or VM:

sudo ./ecs-anywhere-install.sh \
    --cluster test-ecs-anywhere \
     --activation-id $ACTIVATION_ID \
     --activation-code $ACTIVATION_CODE \
    --region <Region>

For more information about setting up and registering your VM, see Registering an external instance to a cluster in the Amazon ECS documentation.

DevOps engineer

Verify the status of ECS Anywhere and the external VM.

To verify whether your virtual box is connected to the Amazon ECS control plane and running, use the following commands:

aws ssm describe-instance-information
aws ecs list-container-instances --cluster $CLUSTER_NAME
DevOps engineer
TaskDescriptionSkills required

Clean up and delete resources.

After you walk through this pattern, you should remove the resources you created to avoid incurring any further charges. To clean up, run the command:

cdk destroy
DevOps engineer

Related resources