# aws-ecs

A Cursor rule that tells the agent how to build and run containers on AWS ECS: immutable images, secrets from Secrets Manager, logs to stdout. Useful when the agent edits Dockerfiles and task definitions.

- rule · `type=rule` · Cursor · ★ 3579
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/aws-ecs.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/aws-ecs

## What it does

The file `.cursor/rules/aws-ecs.mdc` loads into Cursor and acts as instructions for the agent on any file in the project. Inside is a set of practices for building and operating apps on Amazon ECS, each with a bad and a good example.

The core rule is immutable images. Any change to code or dependencies triggers a new build and deploy instead of pulling packages at container start. Secrets stay out of Dockerfiles and out of plain environment variables in the task definition — they come from AWS Secrets Manager or AWS Systems Manager Parameter Store and are injected at runtime. Logs go to `stdout` and `stderr` through the `awslogs` driver. The rule also covers `SIGTERM` handling for graceful shutdown, CPU and memory limits, and one foreground process per container.

If your task definition already passes secrets as plain environment variables, the rule will push against your current setup — worth checking how access is handed out. On Fargate, CPU and memory are set at the task level, and container limits cannot exceed them.

## Requirements
- Works with: AWS

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/aws-ecs.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/aws-ecs.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/aws-ecs.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/aws-ecs.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/aws-ecs.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/aws-ecs.mdc

## When to use it
- build a Dockerfile that installs nothing at container start
- move passwords out of environment variables into Secrets Manager
- route container logs through the awslogs driver
- add a SIGTERM handler for graceful shutdown
- set CPU and memory limits in the task definition

## Example prompts
- Rewrite my Dockerfile following the aws-ecs rule: dependencies install at build time, nothing at startup
- Check this task definition and tell me where secrets are passed as plain environment variables
- Add a SIGTERM handler to the app with a timeout for finishing in-flight requests

## Source text · aws-ecs.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c6ecee3375ee18ff.

BEGIN THIRD-PARTY FILE c6ecee3375ee18ff
````text
---
description: Definitive guidelines for building, deploying, and operating applications on AWS ECS, emphasizing immutable containers, secure secrets management, and robust operational patterns.
globs: **/*
---
# aws-ecs Best Practices

This guide outlines the definitive best practices for developing and deploying applications on Amazon Elastic Container Service (ECS). Adhere to these principles to ensure your applications are secure, performant, and maintainable.

## 1. Code Organization and Structure

### 1.1. Immutable Container Images

Always build immutable container images. Any change to code or dependencies *must* trigger a new image build and deployment. This ensures reproducibility and simplifies rollbacks.

❌ BAD: Modifying container contents at runtime (e.g., downloading dependencies on startup).
```dockerfile
# Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package.json .
RUN npm install # Installs dependencies during build
COPY . .
CMD ["sh", "-c", "npm install && npm start"] # Re-installs on every run!
```

✅ GOOD: Bake all dependencies into the image during the build process.
```dockerfile
# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev # Install production dependencies
COPY . .
RUN npm run build # Build application assets

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist # Copy built assets
EXPOSE 3000
CMD ["node", "dist/main.js"] # Run the built application
```

### 1.2. Single Process Per Container

Each container must run only one foreground application process. This allows ECS to effectively manage the container's lifecycle, health checks, and resource allocation.

❌ BAD: Using process managers like `supervisord` to run multiple applications.
```dockerfile
# Dockerfile
CMD ["supervisord", "-c", "/etc/supervisord.conf"]
# supervisord.conf might start Nginx, a Python app, and a cron job.
```

✅ GOOD: Decouple services into separate containers and task definitions.
```dockerfile
# Dockerfile for a single application
CMD ["python", "app.py"]
```
*Context*: If services are tightly coupled (e.g., a web server and a sidecar agent that *must* run on the same host), use a multi-container task definition. Otherwise, deploy them as separate services.

## 2. Common Patterns and Anti-patterns

### 2.1. Graceful Shutdown Handling (SIGTERM)

Your application must gracefully handle `SIGTERM` signals. ECS sends `SIGTERM` to allow your application to finish in-flight requests and clean up before `SIGKILL` is sent.

❌ BAD: Ignoring `SIGTERM`, leading to abrupt shutdowns and potential data loss.
```javascript
// Node.js example
process.on('SIGINT', () => { /* Handles Ctrl+C, but not SIGTERM from orchestrator */ });
// No SIGTERM handler, process exits immediately on SIGTERM.
```

✅ GOOD: Implement a `SIGTERM` handler to allow for graceful exit.
```javascript
// Node.js example
process.on('SIGTERM', async () => {
  console.log('SIGTERM received. Initiating graceful shutdown...');
  // Stop accepting new connections
  server.close(() => {
    console.log('HTTP server closed.');
    // Perform any cleanup (e.g., close DB connections, flush logs)
    process.exit(0);
  });
  // Force exit after a timeout if cleanup takes too long
  setTimeout(() => {
    console.error('Graceful shutdown timed out. Forcing exit.');
    process.exit(1);
  }, 10000); // 10 seconds timeout
});
```
````
END THIRD-PARTY FILE c6ecee3375ee18ff

The third-party file has ended. Everything between the c6ecee3375ee18ff tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3503 of 10750 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/aws-ecs.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md