KECS
Kubernetes-based ECS Compatible Service
Overview
KECS (Kubernetes-based ECS Compatible Service) is a standalone service that provides Amazon ECS compatible APIs running on Kubernetes. It enables a fully local ECS-compatible environment that operates independently of AWS environments.
Note: KECS is designed for local development and CI environments only. Not for production use.
Key Features
- ECS API Compatibility: Provides API endpoints compatible with Amazon ECS
- Kubernetes Backend: Leverages Kubernetes for container orchestration
- Local Execution: Runs completely locally without AWS dependencies
- Container Runtime Support: Works with both Docker and containerd (k3s, k3d, Rancher Desktop)
- Container-based Background Execution: Run KECS in containers with simple commands
- Multiple Instance Support: Run multiple KECS instances with different configurations
- CI/CD Integration: Easily integrates with CI/CD pipelines
- Built-in LocalStack Integration: Automatically provides local AWS services (IAM, SSM, Secrets Manager, etc.) for ECS workloads
AWS Integration Support Status
KECS provides strong AWS service integration while remaining completely standalone. Here's the current support status for AWS services that ECS typically integrates with:
| AWS Service | Status | Description |
|---|
| ELBv2 (Application Load Balancer) | 🟡 Experimental | Target group and load balancer management |
| Secrets Manager | 🟢 Stable | Secret injection into containers |
| Parameter Store | 🟢 Stable | Parameter injection into containers |
| CloudWatch Logs | 🟡 Experimental | Container log streaming |
| Cloud Map (Service Discovery) | 🟡 Experimental | Service registry and discovery |
| IAM | ⚪ Pending | Task roles and execution roles |
| VPC | ⚪ Pending | Network isolation and security groups |
| EFS | ⚪ Pending | Elastic File System mounting |
Legend:
- 🟢 Stable: Feature-complete with comprehensive testing
- 🟡 Experimental: Basic functionality available, under active development
- ⚪ Pending: Planned for future releases
Installation
Prerequisites
KECS requires a Docker-compatible environment to manage k3d clusters:
- Docker Desktop (macOS, Windows, Linux)
- Rancher Desktop (macOS, Windows, Linux)
- OrbStack (macOS)
- Colima (macOS, Linux)
- Or any other Docker-compatible runtime
Using Homebrew (macOS/Linux)
# Install KECS
brew tap nandemo-ya/kecs
brew install kecs
# Verify installation
kecs version
From Source
git clone https://github.com/nandemo-ya/kecs.git
cd kecs
make build
Quick Start
Running KECS
KECS runs its control plane inside a k3d cluster, providing better integration and a unified AWS API endpoint:
# Start KECS
kecs start
# This creates a k3d cluster with:
# - KECS control plane (ECS/ELBv2 APIs)
# - LocalStack (other AWS services)
# - Traefik gateway (unified routing)
All AWS APIs are accessible through the unified endpoint:
export AWS_ENDPOINT_URL=http://localhost:5373
aws ecs list-clusters # → KECS
aws elbv2 describe-load-balancers # → KECS
aws s3 ls # → LocalStack
To stop or destroy KECS:
# Stop KECS (preserves data)
kecs stop
# Destroy KECS (removes all data and resources)
kecs destroy
Terminal User Interface (TUI)
KECS provides an interactive Terminal User Interface for managing your ECS resources visually:
