Skip to content

deployment.md

Latest commit

 

History

History
115 lines (85 loc) · 3.84 KB

deployment.md

File metadata and controls

115 lines (85 loc) · 3.84 KB
Raw

Deployment

AgentFlow has three useful local-to-production-shaped views. This page explains what each view is for and where the external evidence boundary starts.

Local demo with No Docker

Use this for the fastest local API, SDK, and documentation loop:

python scripts/demo_local.py

The runner selects a persistent DuckDB serving store, explicitly provisions and seeds it, processes 500 events through the local pipeline, skips optional Iceberg writes, and starts FastAPI on http://localhost:8000. It also disables external Kafka, Flink, Iceberg, and Redis health/cache connections so this path does not require local infrastructure after package installation.

Use python scripts/demo_local.py --prepare-only to stop after provisioning and pipeline processing. make demo-local is a convenience alias.

Docker demo

Use this when testing the ClickHouse-backed serving profile:

make demo

What it starts (see the demo target in the Makefile):

  • Redis and ClickHouse through Docker Compose (ClickHouse is the default serving store — ADR 0006)
  • an explicit provisioning step, python -m src.serving.provision --schema --seed — the API itself never creates or seeds a store on boot (audit P0-2)
  • synthetic event seeding through the local pipeline (500 events); the embedded DuckDB file keeps carrying the control-plane state
  • FastAPI on http://localhost:8000

This path exercises more service boundaries than the local-only runner and requires Docker Compose.

Development compose

docker compose up -d

The default compose file includes Kafka, Flink, MinIO, Redis, Prometheus, and Grafana. It is useful for pipeline and observability development, but it is not a cloud production deployment.

Production-shaped compose

docker compose -f docker-compose.prod.yml up -d

The production-shaped compose stack models a more realistic topology:

  • three Kafka brokers
  • schema registry and Kafka UI
  • Redis
  • Jaeger
  • optional ClickHouse profile
  • FastAPI service container
  • Prometheus and Grafana

Use it for local debugging of service boundaries and observability wiring. Do not treat a compose stack as proof that a managed production environment has been provisioned.

Helm and Kubernetes

The repository includes Helm and Kubernetes assets for staging-shaped workflow rehearsal. They are intended to help operators render manifests, test chart defaults, and prepare cluster rollout work.

Before using them for a real environment, operators still need to provide:

  • image registry and tag policy
  • secrets and key ownership
  • ingress/TLS strategy
  • resource requests and limits
  • monitoring ownership
  • rollback process
  • network isolation: set networkPolicy.enabled=true before any multi-replica production rollout (the chart default is false so kind/dev clusters without a NetworkPolicy controller keep working) and confirm the target cluster actually enforces NetworkPolicy

Terraform overview

Terraform modules are present as reference infrastructure code. Local validation can check syntax and module consistency, but applying to AWS requires external setup that this docs build does not close:

  • GitHub OIDC role bootstrap
  • environment tfvars owned by the operator
  • cloud account credentials and approval
  • first real apply evidence

See the existing AWS OIDC setup handoff for the current status before making any stronger infrastructure claim.

External gates

Gate Current docs stance
AWS OIDC-backed Terraform apply Not closed by this walkthrough
Third-party penetration test evidence Not present in this walkthrough
Object-lock-backed immutable audit retention Not evidenced by this walkthrough
Formal compliance certification Not claimed
Production CDC source onboarding Requires approved sources, secrets, network path, monitoring owner, and rollback owner