cdk-ecs-service-extensions

2.0.0 verified Fri May 01 auth: no python

A CDK construct library (v2.0.0) that provides extensions to easily build and deploy ECS services with common patterns like Service Connect, Firelens, AppMesh, etc. Part of the AWS CDK ecosystem, maintained by cdklabs, with periodic releases.

pip install cdk-ecs-service-extensions

Common errors

error ImportError: cannot import name 'QueueExtension' from 'cdk_ecs_service_extensions' ↓

cause Extension classes are not exported from the top-level package; they are in a submodule 'extensions'.

fix

Change import to: from cdk_ecs_service_extensions.extensions import QueueExtension

error jsii.errors.JSIIError: Class 'Service' does not have a property 'environment' ↓

cause Incorrect usage; the Service construct expects 'environment' as a parameter, not as a property.

fix

Pass the Environment object as the 'environment' parameter when creating the Service, e.g., Service(..., environment=my_env)

error ModuleNotFoundError: No module named 'aws_cdk' ↓

cause This library requires AWS CDK v2; 'aws_cdk' is an old v1 module.

fix

Install CDK v2: pip install aws-cdk-lib. Then import aws_cdk as cdk.

error AttributeError: 'Service' object has no attribute 'task_definition' ↓

cause The Service construct may not expose the underlying task definition directly; you need to access it through extensions or use the 'EcsService' property.

fix

Use service.service (the underlying ECS service) or consult extensions for task definition modifications.

Warnings

breaking Version 2.0.0 is a major rewrite that requires AWS CDK v2 (aws-cdk-lib). CDK v1 is not supported. Check your CDK version before upgrading. ↓

fix Upgrade to CDK v2 and use aws-cdk-lib instead of @aws-cdk/* packages.

breaking The import paths changed in v2. Extensions must be imported from the 'extensions' submodule (e.g., from cdk_ecs_service_extensions.extensions import QueueExtension). ↓

fix Update imports: use 'cdk_ecs_service_extensions.extensions' for extension classes.

gotcha The library assumes you use the 'Environment' construct to manage VPC and cluster. If you use your own VPC/cluster, you may need to adapt. The 'Service' construct expects an 'environment' parameter. ↓

fix Create an Environment object (which creates a VPC and ECS cluster) and pass it to the Service.

deprecated Some extensions like 'AppMeshExtension' may be deprecated or require additional configuration. Check the GitHub README for current list. ↓

fix Refer to the official documentation for the list of supported extensions.

Imports

ServiceExtension

from cdk_ecs_service_extensions import ServiceExtension

QueueExtension

from cdk_ecs_service_extensions.extensions import QueueExtension

FirelensExtension

wrong

from cdk_ecs_service_extensions import FirelensExtension

correct

from cdk_ecs_service_extensions.extensions import FirelensExtension

Extension classes are in submodule 'extensions'

Service

from cdk_ecs_service_extensions import Service

Environment

from cdk_ecs_service_extensions import Environment

Quickstart

Minimal app showing Environment, Service, and common extensions.

import aws_cdk as cdk
from cdk_ecs_service_extensions import Environment, Service
from cdk_ecs_service_extensions.extensions import ServiceExtension, QueueExtension, FirelensExtension, ContainerExtension

app = cdk.App()
stack = cdk.Stack(app, 'MyStack')

# Create an environment (VPC, cluster)
env = Environment(stack, 'MyEnv')

# Create a service with extensions
service = Service(
    stack, 'MyService',
    environment=env,
    extensions=[
        ContainerExtension(image=cdk.aws_ecs.ContainerImage.from_registry('amazon/amazon-ecs-sample')),
        QueueExtension(),
        FirelensExtension(),
    ]
)

app.synth()