nandemo-ya-kecs

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: