AWS CDK AWS ECS Constructs (v1)

1.204.0 · deprecated · verified Fri Apr 17

The `aws-cdk-aws-ecs` package provides AWS Cloud Development Kit (CDK) constructs for defining Amazon Elastic Container Service (ECS) resources in Python. It is part of AWS CDK v1. While functional, AWS CDK v2 is the recommended and actively developed version, which consolidates all constructs into `aws-cdk-lib`. This package is largely superseded by `aws-cdk-lib`'s ECS constructs.

Common errors

```
jsii.errors.JavaScriptError: Cannot find module 'aws-cdk-lib'
```
cause Attempting to use a CDK v1 package (like `aws-cdk-aws-ecs`) in an environment or project configured for CDK v2, or vice versa.

fix Standardize on either CDK v1 (using `aws-cdk.*` packages) or CDK v2 (using `aws-cdk-lib`). Ensure your `cdk.json` and `package.json` (if applicable) align with your chosen version.
```
NameError: name 'ecs' is not defined
```
cause Missing or incorrect import statement for the 'aws_ecs' module.

fix Ensure you have `from aws_cdk import aws_ecs as ecs` at the top of your file. If you intended to use CDK v2, you would `pip install aws-cdk-lib` and import `from aws_cdk import aws_ecs as ecs` from the v2 library.
```
TypeError: __init__() got an unexpected keyword argument 'env' (when passing 'env' directly to 'core.App')
```
cause In AWS CDK v1, the 'env' parameter should typically be passed to the `Stack` constructor, not directly to `core.App()`. `core.App()` itself does not accept an 'env' argument.

fix Pass `env=core.Environment(account="...", region="...")` to your `core.Stack` constructor, not `core.App()`. The `App` is the container, the `Stack` defines the resources within a specific environment.

Warnings

breaking AWS CDK v1 (which this package is part of) is largely superseded by AWS CDK v2. V2 consolidates all core constructs into a single package, 'aws-cdk-lib', and has a different module structure. Mixing v1 and v2 packages or attempting to use v1 constructs with a v2 application will lead to errors.
Fix: For new projects, use `aws-cdk-lib` and its ECS constructs (e.g., `from aws_cdk import aws_ecs as ecs`). For existing v1 projects, ensure all CDK packages are `aws-cdk.*` and avoid `aws-cdk-lib`. Consider migrating to v2 for long-term support and features.
gotcha CDK v1 constructs often require explicit imports for base modules like 'core', 'aws_ec2', 'aws_iam', etc., in addition to the specific 'aws_ecs' module. Forgetting these can lead to 'NameError' or 'AttributeError'.
Fix: Always include `from aws_cdk import core` and other required base service modules (e.g., `from aws_cdk import aws_ec2`, `from aws_cdk import aws_iam`) alongside `from aws_cdk import aws_ecs`.
gotcha CDK v1 resources, especially during development, might not always clean up fully upon `cdk destroy` if there are dependencies like S3 buckets not explicitly removed or if the stack fails mid-deletion. This can incur unexpected costs.
Fix: Manually inspect AWS console for orphaned resources after `cdk destroy` failures. For S3 buckets, ensure `auto_delete_objects=True` and `removal_policy=core.RemovalPolicy.DESTROY` are set if you want them to be deleted with the stack (use with caution in production).

Install

pip install aws-cdk-aws-ecs aws-cdk.core Install AWS CDK v1 ECS and Core

Imports

aws_ecs
wrong:
```
from aws_cdk_lib import aws_ecs
```
correct:
```
from aws_cdk import aws_ecs
```
This package is for AWS CDK v1. The `aws_cdk_lib` namespace is for v2.
core
wrong:
```
from aws_cdk_lib import core
```
correct:
```
from aws_cdk import core
```
AWS CDK v1 core constructs like App and Stack are in `aws_cdk.core`.
aws_ec2
wrong:
```
from aws_cdk_lib import aws_ec2
```
correct:
```
from aws_cdk import aws_ec2
```
Specific service constructs are imported directly under `aws_cdk` in v1.

Quickstart

This quickstart defines an AWS CDK v1 stack that creates an ECS Fargate cluster and deploys a simple Fargate service with a sample container image. It demonstrates importing `aws_ecs`, `aws_ec2`, and `core` constructs as expected in v1. Ensure `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` (or `AWS_ACCOUNT_ID`/`AWS_REGION`) environment variables are set.

import os
from aws_cdk import (
    core,
    aws_ecs as ecs,
    aws_ec2 as ec2,
    aws_ecr as ecr,
    aws_iam as iam,
)

class MyEcsFargateStack(core.Stack):
    def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Look up an existing VPC or create a new one
        vpc = ec2.Vpc(self, "MyVpc", max_azs=2)

        cluster = ecs.Cluster(self, "MyFargateCluster", vpc=vpc)

        # Create a Task Definition
        task_definition = ecs.FargateTaskDefinition(
            self, "MyTaskDef",
            memory_limit_mib=512,
            cpu=256
        )

        # Add a container to the task definition
        # Using a public image for simplicity, replace with your ECR image if needed
        image_name = os.environ.get('ECR_IMAGE_NAME', 'amazon/amazon-ecs-sample')
        task_definition.add_container(
            "MyContainer",
            image=ecs.ContainerImage.from_registry(image_name),
            port_mappings=[ecs.PortMapping(container_port=80, host_port=80)]
        )

        # Create a Fargate Service
        ecs.FargateService(
            self, "MyFargateService",
            cluster=cluster,
            task_definition=task_definition,
            desired_count=1
        )

app = core.App()
MyEcsFargateStack(app, "MyEcsFargateStack",
    env=core.Environment(
        account=os.environ.get("CDK_DEFAULT_ACCOUNT", os.environ.get("AWS_ACCOUNT_ID")),
        region=os.environ.get("CDK_DEFAULT_REGION", os.environ.get("AWS_REGION"))
    )
)
app.synth()

view raw JSON →