benwsapp/aws-ssm-minimal repository overview

⁠aws-ssm-minimal – Minimal Session Manager Sidecar

⁠Overview

aws-ssm-minimal is a purpose-built container image for running the AWS Systems Manager (SSM) agent as a sidecar in compute environments that do not ship with SSM pre-installed (for example, ECS Fargate tasks, EKS Pods, or plain OCI runtimes). The image bundles:

• A lightweight TTL wrapper written in Go that supervises the agent, adds a configurable time-to-live, forwards signals, and performs activation clean-up when the container exits.
• A non-root build of the official aws/amazon-ssm-agent⁠ compiled directly in the Docker build.
• CA certificates and nothing else—no package manager, shell, or extraneous tooling—keeping the runtime attack surface extremely small (FROM scratch).

⁠Key features

• Drop-in SSM agent: The agent binary is built from source at image build time. No need to volume-mount packages or preinstall the agent in your base image.
• TTL enforcement: Configure TTL_SECONDS (default 3600) to have the sidecar gracefully shut down after a fixed lifetime. TTL_SHUTDOWN_GRACE_SECONDS (default 15) controls how long to wait after sending SIGTERM before force killing the agent.
• Managed instance clean-up: On TTL expiry or container exit, the wrapper deregisters the managed instance and deletes the SSM activation so you avoid cluttering your account with stale entries.
• Non-root runtime: The image runs as UID/GID 65533 by default, aligning with restrictive security policies and PodSecurity standards.
• Minimal footprint: Based on scratch with only the compiled binaries and certificates. Ideal for sidecar deployments where resource overhead matters.

⁠Configuration

Environment variables:

• MANAGED_INSTANCE_ROLE_NAME (required) – IAM role name to associate with the managed instance. Attach the standard AmazonSSMManagedInstanceCore policy (plus any extra permissions your sessions need).
• TTL_SECONDS – Runtime lifetime in seconds before the wrapper initiates shutdown (default 3600).
• TTL_SHUTDOWN_GRACE_SECONDS – Grace period between sending SIGTERM and SIGKILL to the agent (default 15).

⁠Example (ECS/Fargate)

{
  "name": "eks-private-access",
  "image": "ghcr.io/your-org/aws-ssm-minimal:latest",
  "essential": false,
  "environment": [
    { "name": "MANAGED_INSTANCE_ROLE_NAME", "value": "MyManagedInstanceRole" },
    { "name": "TTL_SECONDS", "value": "1800" }
  ]
}

Required IAM permissions for the task role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:CreateActivation",
        "ssm:DeleteActivation",
        "ssm:DeregisterManagedInstance"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::<account-id>:role/MyManagedInstanceRole"
    }
  ]
}

Managed instance role:

• Trusts ssm.amazonaws.com in its assume-role policy.
• Has AmazonSSMManagedInstanceCore (plus any custom permissions you require for the session).

⁠Getting started

1. Pull the image: docker pull benwsapp/aws-ssm-minimal:latest
2. Run the sidecar alongside your workload, supplying MANAGED_INSTANCE_ROLE_NAME.
3. Connect using AWS Systems Manager Session Manager once the sidecar registers as a managed instance.

⁠Support & issues

File GitHub issues for bugs or feature requests at your repository hosting this Dockerfile. This image is not an official AWS distribution but compiles the OSS agent directly from Amazon’s source.