pgblame

Running the agent on AWS ECS (Fargate)

One Fargate task running the agent as a long-lived service, with secrets in Secrets Manager and (optionally) an EFS volume for the buffer.

1. Store the secrets

aws secretsmanager create-secret --name pgblame/db-url \
  --secret-string 'postgresql://...'

aws secretsmanager create-secret --name pgblame/token \
  --secret-string 'pgb_...'

2. Register the task definition

Replace <account-id>, <region>, and the EFS fileSystemId. Drop the volumes / mountPoints and the PGBLAME_DATA_DIR env to run without EFS (see notes).

{
  "family": "pgblame-agent",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::<account-id>:role/ecsTaskExecutionRole",
  "volumes": [
    {
      "name": "pgblame-data",
      "efsVolumeConfiguration": {
        "fileSystemId": "fs-xxxxxxxx",
        "transitEncryption": "ENABLED"
      }
    }
  ],
  "containerDefinitions": [
    {
      "name": "agent",
      "image": "ghcr.io/liberzon/pgblame-agent:latest",
      "essential": true,
      "user": "65532",
      "environment": [
        { "name": "PGBLAME_DATA_DIR", "value": "/var/lib/pgblame" }
      ],
      "secrets": [
        { "name": "PGBLAME_DATABASE_URL", "valueFrom": "arn:aws:secretsmanager:<region>:<account-id>:secret:pgblame/db-url" },
        { "name": "PGBLAME_TOKEN", "valueFrom": "arn:aws:secretsmanager:<region>:<account-id>:secret:pgblame/token" }
      ],
      "mountPoints": [
        { "sourceVolume": "pgblame-data", "containerPath": "/var/lib/pgblame" }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/pgblame-agent",
          "awslogs-region": "<region>",
          "awslogs-stream-prefix": "agent"
        }
      }
    }
  ]
}
aws ecs register-task-definition --cli-input-json file://pgblame-agent.json

3. Create the service

aws ecs create-service \
  --cluster <your-cluster> \
  --service-name pgblame-agent \
  --task-definition pgblame-agent \
  --desired-count 1 \
  --launch-type FARGATE \
  --deployment-configuration 'maximumPercent=100,minimumHealthyPercent=0' \
  --network-configuration 'awsvpcConfiguration={subnets=[subnet-xxxx],securityGroups=[sg-xxxx],assignPublicIp=ENABLED}'

Notes

  • One task only. --desired-count 1 plus maximumPercent=100, minimumHealthyPercent=0 makes ECS stop the old task before starting the new one on a deploy — never two agents racing the same database.
  • EFS is optional. It keeps the delta baseline + retry queue across task replacements (recommended). Use an EFS access point with posixUser uid/gid 65532 so the nonroot container can write it. To skip EFS, drop the volume blocks and PGBLAME_DATA_DIR and run on Fargate ephemeral storage — you lose one delta window per task restart.
  • Networking. The agent is outbound-only: it needs egress to your database and HTTPS to pgblame.com, and no inbound rules. assignPublicIp=ENABLED (or a NAT gateway) is required for egress on public/private subnets respectively.

Tell pgblame about deploys

Run the agent on AWS ECS — pgblame