Building SwiftDeploy: From Declarative Deployments to Policy-Gated Releases

Building SwiftDeploy: From Declarative Deployments to Policy-Gated Releases

Introduction

SwiftDeploy is a DevOps deployment tool I built as part of the HNG DevOps Track. The project started as a deployment automation task and later became a policy-gated and observable deployment system.

In Stage 4A, I built the deployment engine. The tool could read a manifest.yaml file, generate infrastructure files, deploy the stack, and switch between stable and canary modes.

In Stage 4B, I extended the project with observability, policy enforcement, chaos testing, status checks, and audit reporting.

The goal was to build a tool that does not just deploy containers, but also checks whether the environment is safe before deployment and promotion.

The Design: A Tool That Writes Its Own Infrastructure

The main idea behind SwiftDeploy is that manifest.yaml remains the single source of truth.

Instead of manually writing docker-compose.yml and nginx.conf, the CLI reads the manifest and generates those files from templates.

The flow looks like this:

text
manifest.yaml
      |
      v
swiftdeploy init
      |
      v
nginx.conf + docker-compose.yml
      |
      v
Docker Compose deployment
This means if the generated files are deleted, the CLI can recreate them again from the manifest.

The manifest defines the service image, port, mode, version, Nginx settings, network settings, and policy thresholds.

Example:

services:
  image: 10johnny-swiftdeploy-stage4b:latest
  port: 3000
  mode: stable
  version: "1.0.0"
  restart_policy: unless-stopped

nginx:
  image: nginx:latest
  port: 8080
  proxy_timeout: 30

network:
  name: swiftdeploy-net
  driver_type: bridge

policy:
  opa_url: http://localhost:8181
  thresholds:
    min_disk_free_gb: 10
    max_cpu_load: 2.0
    max_error_rate_percent: 1
    max_p99_latency_ms: 500
Architecture

The application runs behind Nginx.

User / Browser / curl
        |
        v
Nginx container on port 8080
        |
        v
Python API service on internal port 3000

Only Nginx is exposed to the host. The Python API service is not exposed directly. This ensures all traffic goes through the reverse proxy.

The generated Docker Compose file creates the service container, Nginx container, network, named volume, and OPA policy sidecar.

Stage 4A: Deployment Lifecycle

SwiftDeploy supports the main deployment lifecycle commands:

python swiftdeploy init
python swiftdeploy validate
python swiftdeploy deploy
python swiftdeploy promote canary
python swiftdeploy promote stable
python swiftdeploy teardown
python swiftdeploy teardown --clean
Init

The init command reads manifest.yaml and generates:

nginx.conf
docker-compose.yml
Validate

The validate command performs pre-flight checks before deployment.

It checks that:

manifest.yaml exists and is valid YAML
required fields are present
Docker image exists locally
Nginx port is free
nginx.conf syntax is valid
Deploy

The deploy command runs init, starts the stack, and waits until the health check passes.

Promote

The promote canary command switches the application to canary mode.

The promote stable command switches it back to stable mode.

The mode is updated in manifest.yaml, the Docker Compose file is regenerated, and only the service container is restarted.

Observability: Adding /metrics

For Stage 4B, I added a /metrics endpoint in Prometheus text format.

The API service tracks:

http_requests_total
http_request_duration_seconds
app_uptime_seconds
app_mode
chaos_active

These metrics help track:

throughput
errors
latency
uptime
current mode
active chaos state

The metrics endpoint can be tested with:

curl http://localhost:8080/metrics

This gives SwiftDeploy visibility into the running service.

The Guardrails: OPA Policy Enforcement

Stage 4B also introduced Open Policy Agent, also known as OPA.

OPA acts as the policy decision engine. The CLI does not make the allow or deny decision itself. Instead, SwiftDeploy collects data and sends it to OPA. OPA evaluates the policy and returns a decision with reasons.

The policies are stored in the policies/ directory:

policies/
├── infrastructure.rego
└── canary.rego
Infrastructure Policy

The infrastructure policy answers this question:

Is the host safe enough for deployment?

It blocks deployment if:

Disk free space is below 10GB
CPU load is above 2.0

This protects the deployment from running on an unhealthy host.

Canary Safety Policy

The canary policy answers this question:

Is the canary safe enough to promote?

It blocks promotion if:

Error rate is above 1%
P99 latency is above 500ms

Before promotion, SwiftDeploy scrapes /metrics, calculates error rate and P99 latency, and sends the result to OPA.

Why Policy Isolation Matters

Each policy domain owns one responsibility.

The infrastructure policy only checks host safety.

The canary policy only checks canary safety.

This separation is important because a change in one policy should not require changing another policy. It also makes the system easier to debug because each policy gives its own decision and reason.

Example:

Infrastructure policy: PASS
Canary policy: FAIL

This makes it clear which part of the deployment process is unsafe.

Gated Deploy and Promote

The deploy flow now works like this:

swiftdeploy deploy
      |
      v
start OPA
      |
      v
collect disk, CPU, and memory data
      |
      v
ask OPA infrastructure policy
      |
      v
deploy only if allowed

The promote flow works like this:

swiftdeploy promote canary
      |
      v
start OPA
      |
      v
scrape /metrics
      |
      v
calculate error rate and P99 latency
      |
      v
ask OPA canary policy
      |
      v
promote only if allowed

OPA decisions include reasons, not just true or false. This is useful because the operator can understand why an operation passed or failed.

The Chaos: Testing Slow and Error States

The application has a /chaos endpoint that works in canary mode.

It supports slow mode:

{ "mode": "slow", "duration": 3 }

It also supports error mode:

{ "mode": "error", "rate": 0.5 }

Slow mode delays responses. Error mode causes some requests to return 500 errors.

This allows the canary safety policy to be tested under unhealthy conditions.

Example request:

curl -X POST http://localhost:8080/chaos \
  -H "Content-Type: application/json" \
  -d "{\"mode\":\"error\",\"rate\":0.5}"

After injecting chaos, the /metrics endpoint records the request behaviour. The swiftdeploy status command then displays the current metrics and policy compliance.

Example status view:

python swiftdeploy status

Requests: 20
Error Rate: 5.0%
P99 Latency: 700ms

Policy Compliance:
- Infrastructure: PASS
- Canary: FAIL

This shows how SwiftDeploy can detect an unhealthy canary instead of promoting it blindly.

Status Command

I added:

python swiftdeploy status

The status command scrapes /metrics, calculates request statistics, checks policy compliance, and appends every scrape to:

history.jsonl

This creates a simple audit trail of what happened over time.

Audit Command

I also added:

python swiftdeploy audit

This command reads history.jsonl and generates:

audit_report.md

The audit report contains:

deployment timeline
mode changes
policy checks
policy violations

This gives SwiftDeploy memory. Instead of only showing the current state, it records what happened during deployment, promotion, chaos testing, and policy checks.

Repository Structure

The project structure is:

manifest.yaml
swiftdeploy
Dockerfile
README.md
app/
templates/
policies/

Generated files are created in the root folder:

nginx.conf
docker-compose.yml

Audit files include:

history.jsonl
audit_report.md
How to Run the Project

Build the Docker image:

docker build -t 10johnny-swiftdeploy-stage4b:latest .

Generate configuration files:

python swiftdeploy init

Deploy the stack:

python swiftdeploy deploy

Check health:

curl http://localhost:8080/healthz

Check metrics:

curl http://localhost:8080/metrics

Promote to canary:

python swiftdeploy promote canary

Run status:

python swiftdeploy status

Generate audit report:

Python SwiftDeploy Audit

Tear down:

python swiftdeploy teardown --clean
Lessons Learned

This project helped me understand how deployment tools work beyond simply starting containers.

I learned how to:

generate infrastructure files from templates
Use Docker Compose to manage multiple containers
Use Nginx as a reverse proxy
Expose Prometheus-style metrics
Use OPA for policy decisions
separate policy logic from CLI logic
Test canary behavior with chaos injection
Generate an audit report from deployment history

The biggest lesson is that deployment automation should not only focus on speed. A good deployment tool should also provide safety, visibility, clear decision-making, and traceability.

SwiftDeploy started as a deployment automation tool, but Stage 4B made it more reliable by adding observability, policy guardrails, chaos testing, and auditing.

GitHub Repository

GitHub Repo:

https://github.com/10Johnny/swiftdeploy-stage4a