STOPSIGNAL is now available on Amazon ECS Fargate

Source: Dev.to

Fargate Now Supports “STOP SIGNAL”

Amazon ECS Fargate now sends the STOPSIGNAL command defined in your Dockerfile to containers.

• Announcement:
• Graceful shutdown guide:
• OCI compliance: By adhering to the OCI standard, specifying STOPSIGNAL in the Dockerfile guarantees graceful shutdowns on Fargate, Kubernetes, and local Docker, improving portability.

Previously, achieving a graceful shutdown on ECS Fargate required custom logic to handle SIGTERM. Middleware often has fixed behavior when receiving a stop signal (e.g., Nginx: ).

Fargate runs on AWS’s proprietary managed host OS (microVM/Firecracker), which may limit direct access to low‑level signal handling. If you have more details, feel free to share.

The source repository for verification is:

Sample Application

A simple Express server demonstrates handling of custom stop signals.

// server.js
const express = require('express');
const app = express();
const PORT = process.env.PORT || 8080;
const SHUTDOWN_DELAY_MS = parseInt(process.env.SHUTDOWN_DELAY_MS, 10) || 10000;

app.get('/', (req, res) => {
  res.send('Running and waiting for stop signal...');
});

const server = app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

// --- Signal Handlers ---
process.on('SIGTERM', () => {
  handleShutdown('SIGTERM');
});

process.on('SIGINT', () => {
  handleShutdown('SIGINT');
});

// SIGKILL cannot be caught

function handleShutdown(signal) {
  console.log(`[${signal} RECEIVED] Graceful shutdown initiated.`);

  // Stop accepting new connections
  server.close(() => {
    console.log('HTTP server closed.');
  });

  // Simulate cleanup work
  console.log(`Starting cleanup. Waiting for ${SHUTDOWN_DELAY_MS / 1000} seconds...`);

  setTimeout(() => {
    console.log(`[${signal} SUCCESS] Cleanup complete. Exiting cleanly.`);
    process.exit(0);
  }, SHUTDOWN_DELAY_MS);
}

Test Application Behavior

• Receives SIGINT and performs a 10‑second cleanup.
• Logs [SIGINT RECEIVED] in CloudWatch Logs.
• ECS task definition stopTimeout set to 15 seconds for verification.
• After a cdk deploy (forcing task recreation), the container receives SIGTERM as expected.

Dockerfile

Adding STOPSIGNAL to the Dockerfile is sufficient to change the signal used for graceful shutdown.

# Dockerfile
FROM node:22-slim

# ... other instructions ...

STOPSIGNAL SIGINT

CMD ["node", "server.js"]

After deploying, running cdk deploy again forces task recreation, and the container correctly catches SIGINT.

Implications

This custom stop‑signal support is more than just an extra parameter—it shows that AWS Fargate now fully complies with the OCI (Open Container Initiative) standard for container runtimes. Consequently, operators can bring standard images used elsewhere directly to Fargate, achieving consistent graceful‑shutdown behavior across environments.