Document ID: GOS-80-CHAIN-AWS-ECS-ENV-BLOCKS Version: 0.1.0 Status: DRAFT Owner Role: CHAIN_OFFICER Last Review Date: 2026-03-04 Next Review Date: 2026-04-04

Purpose

Provide copy/paste-ready ECS containerDefinitions[].environment blocks for Kafka orchestration workloads on AWS.

Usage

• Paste the relevant block into your ECS task definition container.
• Keep secrets in ECS secrets (SSM/Secrets Manager), not in environment.
• Replace <region> and broker DNS values with real MSK endpoints.

Dev environment Block

[
  { "name": "NODE_ENV", "value": "development" },
  { "name": "KAFKA_BROKERS", "value": "b-1.kvary-dev-msk.<region>.amazonaws.com:9098,b-2.kvary-dev-msk.<region>.amazonaws.com:9098" },
  { "name": "KAFKA_DEMO_CLIENT_ID", "value": "kvary-kafka-demo-dev" },
  { "name": "KAFKA_DEMO_GROUP_ID", "value": "kvary-demo-dev" },
  { "name": "KAFKA_DEMO_TOPIC", "value": "mint.requested" },
  { "name": "KAFKA_DEMO_TIMEOUT_MS", "value": "30000" },
  { "name": "KAFKA_DEMO_WARMUP_MS", "value": "1500" }
]

Stage environment Block

[
  { "name": "NODE_ENV", "value": "staging" },
  { "name": "KAFKA_BROKERS", "value": "b-1.kvary-stage-msk.<region>.amazonaws.com:9098,b-2.kvary-stage-msk.<region>.amazonaws.com:9098" },
  { "name": "KAFKA_DEMO_CLIENT_ID", "value": "kvary-kafka-demo-stage" },
  { "name": "KAFKA_DEMO_GROUP_ID", "value": "kvary-demo-stage" },
  { "name": "KAFKA_DEMO_TOPIC", "value": "mint.requested" },
  { "name": "KAFKA_DEMO_TIMEOUT_MS", "value": "30000" },
  { "name": "KAFKA_DEMO_WARMUP_MS", "value": "1500" }
]

Prod environment Block

[
  { "name": "NODE_ENV", "value": "production" },
  { "name": "KAFKA_BROKERS", "value": "b-1.kvary-prod-msk.<region>.amazonaws.com:9098,b-2.kvary-prod-msk.<region>.amazonaws.com:9098,b-3.kvary-prod-msk.<region>.amazonaws.com:9098" },
  { "name": "KAFKA_DEMO_CLIENT_ID", "value": "kvary-kafka-demo-prod" },
  { "name": "KAFKA_DEMO_GROUP_ID", "value": "kvary-demo-prod" },
  { "name": "KAFKA_DEMO_TOPIC", "value": "mint.requested" },
  { "name": "KAFKA_DEMO_TIMEOUT_MS", "value": "45000" },
  { "name": "KAFKA_DEMO_WARMUP_MS", "value": "2000" }
]

Recommended secrets Block (Template)

[
  { "name": "KAFKA_SASL_USERNAME", "valueFrom": "arn:aws:ssm:<region>:<account-id>:parameter/kvary/<env>/kafka/sasl/username" },
  { "name": "KAFKA_SASL_PASSWORD", "valueFrom": "arn:aws:ssm:<region>:<account-id>:parameter/kvary/<env>/kafka/sasl/password" }
]

Notes

• Keep the same topic contract and key policy (intentId) across all environments.
• For local smoke checks, continue using npm run kafka:smoke with Docker profile.
• For AWS runtime checks, use npm run kafka:demo or service-level health checks.

Ready-to-Use Task Definition Templates

• docs/80_chain/templates/ecs-task-kafka-orchestrator.dev.json
• docs/80_chain/templates/ecs-task-kafka-orchestrator.stage.json
• docs/80_chain/templates/ecs-task-kafka-orchestrator.prod.json

Register examples:

aws ecs register-task-definition --cli-input-json file://docs/80_chain/templates/ecs-task-kafka-orchestrator.dev.json
aws ecs register-task-definition --cli-input-json file://docs/80_chain/templates/ecs-task-kafka-orchestrator.stage.json
aws ecs register-task-definition --cli-input-json file://docs/80_chain/templates/ecs-task-kafka-orchestrator.prod.json

ECS Service Deploy Commands (Create / Update)

Set shared placeholders first:

AWS_REGION=<region>
ECS_CLUSTER=<ecs-cluster-name>
SUBNETS=subnet-aaa,subnet-bbb
SECURITY_GROUPS=sg-aaa

Dev:

aws ecs create-service \
  --region $AWS_REGION \
  --cluster $ECS_CLUSTER \
  --service-name kvary-kafka-orchestrator-dev \
  --task-definition kvary-kafka-orchestrator-dev \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[$SUBNETS],securityGroups=[$SECURITY_GROUPS],assignPublicIp=DISABLED}"

aws ecs update-service \
  --region $AWS_REGION \
  --cluster $ECS_CLUSTER \
  --service kvary-kafka-orchestrator-dev \
  --task-definition kvary-kafka-orchestrator-dev \
  --force-new-deployment

Stage:

aws ecs create-service \
  --region $AWS_REGION \
  --cluster $ECS_CLUSTER \
  --service-name kvary-kafka-orchestrator-stage \
  --task-definition kvary-kafka-orchestrator-stage \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[$SUBNETS],securityGroups=[$SECURITY_GROUPS],assignPublicIp=DISABLED}"

aws ecs update-service \
  --region $AWS_REGION \
  --cluster $ECS_CLUSTER \
  --service kvary-kafka-orchestrator-stage \
  --task-definition kvary-kafka-orchestrator-stage \
  --force-new-deployment

Prod:

aws ecs create-service \
  --region $AWS_REGION \
  --cluster $ECS_CLUSTER \
  --service-name kvary-kafka-orchestrator-prod \
  --task-definition kvary-kafka-orchestrator-prod \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[$SUBNETS],securityGroups=[$SECURITY_GROUPS],assignPublicIp=DISABLED}"

aws ecs update-service \
  --region $AWS_REGION \
  --cluster $ECS_CLUSTER \
  --service kvary-kafka-orchestrator-prod \
  --task-definition kvary-kafka-orchestrator-prod \
  --force-new-deployment

Notes:

• Run create-service once per environment; afterward use update-service for new task revisions.
• If your service needs target groups, add --load-balancers and the corresponding health check settings.

Terraform Variant (Dev / Stage / Prod)

Terraform templates:

• docs/80_chain/templates/terraform/ecs-kafka-orchestrator/main.tf
• docs/80_chain/templates/terraform/ecs-kafka-orchestrator/variables.tf
• docs/80_chain/templates/terraform/ecs-kafka-orchestrator/dev.tfvars
• docs/80_chain/templates/terraform/ecs-kafka-orchestrator/stage.tfvars
• docs/80_chain/templates/terraform/ecs-kafka-orchestrator/prod.tfvars

Quick start:

cd docs/80_chain/templates/terraform/ecs-kafka-orchestrator
terraform init
terraform plan -var-file=dev.tfvars
terraform apply -var-file=dev.tfvars