aws-init

README

aws-init

A lightweight init process for containers that securely resolves AWS Secrets Manager and AWS SSM Parameter Store values at runtime.

Full documentation: pkg.go.dev/cmecca.io/aws-init

Installation

go get cmecca.io/aws-init@latest

Usage

aws-init command [args...]

Set environment variables with aws-secret: prefixes:

export DATABASE_URL="aws-secret:myapp/prod#database_url"
export API_KEY="aws-secret:myapp/api"
aws-init python app.py

Flags

• -v show version
• -h health check

Secret Formats

Secrets Manager:

SIMPLE_SECRET=aws-secret:myapp/api
JSON_KEY=aws-secret:myapp/config#database_url

Parameter Store:

PARAMETER=aws-secret:/aws/reference/secretsmanager/myapp/token

Authentication

Uses standard AWS credential chain (IRSA, instance profile, etc).

License

See LICENSE for terms.

Disclaimer

Per the NOTICE, this is a personal project developed in my individual capacity. It is not affiliated with or endorsed by Amazon Web Services, Inc.

aws-init was built with Go 1.23

Documentation

Overview

Package main provides process execution and signal handling functionality.

This file contains functions for executing child processes with proper signal forwarding, process group management, and graceful shutdown handling.

Signal Handling

The executor forwards these signals to child processes:

• SIGTERM, SIGINT, SIGQUIT (termination signals)
• SIGUSR1, SIGUSR2 (user-defined signals)

Graceful Shutdown

When SIGTERM is received:

1. Forward SIGTERM to child process and process group
2. Wait up to 10 seconds for graceful shutdown
3. Send SIGKILL if process hasn't exited

Process Groups

Child processes are started in their own process group to ensure proper signal propagation to all descendants.

Package main provides aws-init, a lightweight init process that resolves AWS secrets at runtime and executes commands with proper signal handling.

aws-init is designed to run as PID 1 in containers, resolving AWS Secrets Manager and Parameter Store values at startup before launching the target application.

Usage

aws-init command [args...]
aws-init -v
aws-init -h

Environment Variables

Environment variables with aws-secret: prefixes are resolved at startup:

DATABASE_URL=aws-secret:myapp/prod#database_url
API_KEY=aws-secret:/aws/reference/secretsmanager/myapp/token

Secret Reference Formats

Secrets Manager (string values):

aws-secret:secret-name

Secrets Manager (JSON key extraction):

aws-secret:secret-name#key

Parameter Store (via Secrets Manager reference):

aws-secret:/aws/reference/secretsmanager/secret-name

Authentication

Uses standard AWS credential chain including:

• IAM Roles for Service Accounts (IRSA) in Kubernetes
• Instance profiles on EC2
• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• AWS credential files

Signal Handling

When running as PID 1, aws-init properly forwards signals to child processes and handles graceful shutdown with a 10-second timeout before force-killing.

Examples

Basic usage:

export DATABASE_URL="aws-secret:myapp/prod#db_url"
aws-init python app.py

Dockerfile integration:

FROM python:3.11-slim
COPY aws-init /usr/local/bin/
ENV DATABASE_URL=aws-secret:myapp/prod#database_url
ENV API_KEY=aws-secret:myapp/prod#api_key
ENTRYPOINT ["/usr/local/bin/aws-init", "python", "app.py"]

Kubernetes deployment:

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      serviceAccountName: my-app-sa  # with IRSA
      containers:
      - name: app
        image: myapp:latest
        command: ["/usr/local/bin/aws-init", "python", "app.py"]
        env:
        - name: DATABASE_URL
          value: "aws-secret:myapp/prod#database_url"

Health check:

aws-init -h

Version information:

aws-init -v

Security

Secrets are resolved once at startup and passed to the child process via environment variables. No secrets are logged or persisted to disk. Use minimal IAM permissions for production deployments.

Package main provides AWS secret resolution functionality.

This file contains functions for resolving AWS Secrets Manager and Systems Manager Parameter Store references in environment variables.

Secret Reference Format

Secrets Manager (string values):

aws-secret:secret-name

Secrets Manager (JSON key extraction):

aws-secret:secret-name#key

Parameter Store (via Secrets Manager reference):

aws-secret:/aws/reference/secretsmanager/secret-name

Error Handling

Functions implement retry logic with exponential backoff for transient AWS API errors. Context cancellation is respected for timeout handling.