Guardrails for Agent-Generated Docker Compose on GCP

An AI-generated Compose file should be easy to review before it reaches Google Cloud. 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
• Authenticated with defang login (this handles both Defang auth and can trigger GCP OAuth)
• GCP project identified (set GCP_PROJECT_ID, or the CLI will prompt during stack creation)
• A Defang stack targeting GCP: run defang stack new and select GCP when prompted for provider

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 Google Cloud:

services:
  db:
    image: postgres:17
    x-defang-postgres: true  # Maps to Cloud SQL

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

  ai:
    build: .
    x-defang-llm: true       # Grants access to Vertex AI
    environment:
      - PROMPT_TEMPLATE

The x-defang-llm annotation configures Vertex AI access for the annotated service (roles and environment variables). 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 Vertex AI access without provisioning additional infrastructure.

GCP-supported annotations: x-defang-postgres (Cloud SQL), x-defang-redis (Memorystore), x-defang-mongodb (Firestore), x-defang-llm (Vertex AI).

This is easier to review than generated IAM, VPC connectors, Cloud SQL instances, Firestore databases, and Vertex AI configuration.

What to avoid

Do not put API keys in the Compose file. Do not expose databases publicly. Do not generate custom GCP 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 Google Cloud infrastructure (Cloud Run, Cloud SQL, Memorystore, Firestore) while keeping the source-of-truth readable in the repository.