Guardrails for Agent-Generated Docker Compose on AWS

An AI-generated Compose file should be easy to review before it reaches AWS. The goal is not to hide infrastructure intent; the goal is to express the intent cleanly and let Defang handle the cloud translation after review.

Prerequisites

• Defang CLI installed
• User authenticated with defang login
• AWS credentials configured
• A Defang stack targeting AWS: run defang stack new and select AWS when prompted

Required guardrails

Use these checks before running defang compose up:

• Every public service has exactly the intended public port.
• Web and API services have health checks.
• Secret values are not committed in compose.yaml. Use defang config set SECRET_NAME to store them.
• Required environment variables are named explicitly.
• Stateful dependencies use managed-service annotations when possible.
• Resource reservations are reasonable for the app size.
• The file works for local development too. Always include the image field (e.g., image: postgres:17) — Defang uses the tag to determine the managed service version, and docker compose up uses the same image locally. The x-defang- annotations are only interpreted during cloud deployment.

Use Defang Agent Skills

Install Defang Agent Skills when you want your coding agent to apply Defang’s deployment, estimate, and debug workflows while checking these guardrails.

Managed service annotations

Use Defang annotations to keep production dependencies managed by AWS:

services:
  db:
    image: postgres:17
    x-defang-postgres: true  # Maps to Amazon RDS

  cache:
    image: redis:7
    x-defang-redis: true     # Maps to Amazon ElastiCache

  ai:
    build: .
    x-defang-llm: true       # Grants IAM access to Amazon Bedrock
    environment:
      - PROMPT_TEMPLATE

The x-defang-llm annotation configures IAM permissions so the annotated service can call Amazon Bedrock. For supported model runner images, Defang also provisions an OpenAI-compatible LLM proxy (LiteLLM). For custom app services (like the build: . example above), it grants Bedrock access without provisioning additional infrastructure.

This is easier to review than a generated set of RDS, ElastiCache, IAM, networking, and Bedrock resources.

What to avoid

Do not put API keys in the Compose file. Do not expose databases publicly. Do not generate custom AWS infrastructure files unless you need low-level control. Do not assume that a local-only Compose file is production-ready without health checks and secret handling.

Deploy

After review:

defang compose up

Defang turns the guarded Compose file into AWS infrastructure (ECS Fargate, ALB, RDS, ElastiCache) while keeping the source-of-truth readable in the repository.