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
This pattern demonstrates the steps to set up ECS Anywhere by using AWS Cloud Development Kit (AWS CDK)
Prerequisites and limitations
Prerequisites
An active AWS account.
AWS Command Line Interface (AWS CLI), installed and configured. (See Installing, updating, and uninstalling the AWS CLI in the AWS CLI documentation.)
AWS CDK Toolkit, installed and configured. (See AWS CDK Toolkit in the AWS CDK documentation, and follow the instructions to install version 2 globally.)
Node package manager (npm), installed and configured for the AWS CDK in TypeScript. (See Downloading and installing Node.js and npm
in the npm documentation.)
Limitations
For limitations and considerations, see External instances (Amazon ECS Anywhere) in the Amazon ECS documentation.
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.
When you deploy the AWS CDK stack, it creates a CloudFormation stack on AWS.
The CloudFormation stack provisions an Amazon ECS cluster and related AWS resources.
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.
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.
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.
![ECS Anywhere setup using the AWS CDK with TypeScript.](/images/prescriptive-guidance/latest/patterns/images/pattern-img/3ed63c00-40e7-4831-bb9d-63049c3490aa/images/ff7dc774-830d-4b9f-8262-7314afe7a033.png)
Automation and scale
The GitHub repository
Tools
AWS Cloud Development Kit (AWS CDK) is a software development framework that helps you define and provision AWS Cloud infrastructure in code.
AWS Command Line Interface (AWS CLI) is an open-source tool that helps you interact with AWS services through commands in your command-line shell.
Code
The source code for this pattern is available on GitHub, in the Amazon ECS Anywhere CDK Samples
Epics
Task | Description | Skills required |
---|---|---|
Verify the AWS CDK version. | Verify the version of the AWS CDK Toolkit by running the following command:
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
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Clone the AWS CDK code repository. | Clone the GitHub code repository for this pattern by using the command:
| 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:
For more information, see Bootstrapping in the AWS CDK documentation. | DevOps engineer |
Task | Description | Skills required |
---|---|---|
Install package dependencies and compile TypeScript files. | Install the package dependencies and compile the TypeScript files by running the following commands:
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:
—or—
For more information, see npm ci | DevOps engineer |
Build the project. | To build the project code, run the command:
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:
| DevOps engineer |
Verify stack creation and output. | Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation | DevOps engineer |
Task | Description | Skills required |
---|---|---|
Set up your VM by using Vagrant. | For demonstration purposes, you can use HashiCorp Vagrant | DevOps engineer |
Register your VM as an external instance. | 1. Log in to the Vagrant VM by using the 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
3. Export the activation ID and code values:
4. Download the installation script to your on-premises server or VM:
5. Run the installation script on your on-premises server or VM:
For more information about setting up and registering your VM, see Registering an external instance to a cluster | 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:
| DevOps engineer |
Task | Description | Skills 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:
| DevOps engineer |