certctl/examples/step-ca-haproxy/step-ca-haproxy.md

step-ca + HAProxy Example

This example demonstrates certctl managing certificates issued by Smallstep step-ca and deploying them to HAProxy.

Operational notes shared by every example (postgres password rotation trap, TLS provisioning, teardown semantics) live in ../README.md. Read it first if you plan to change DB_PASSWORD after the initial docker compose up — the postgres volume binds the password on first boot only.

Scenario

You're a Smallstep user running step-ca as your internal PKI. You have HAProxy load balancers that need certificates. This setup:

1. step-ca issues certificates (via JWK provisioner, no challenge solving)
2. certctl manages the certificate lifecycle (renewal policies, deployment, audit)
3. HAProxy serves HTTPS with certificates managed by certctl

This is the natural choice if you're already invested in step-ca and want to consolidate certificate lifecycle management without learning Let's Encrypt, DNS-01 challenges, or external integrations.

What's Included

Service	Image	Purpose
step-ca	smallstep/step-ca:latest	Private internal CA
certctl-server	ghcr.io/certctl-io/certctl-server:latest	Certificate management control plane
certctl-agent	ghcr.io/certctl-io/certctl-agent:latest	Agent running on HAProxy server
haproxy	haproxy:2.9-alpine	Reverse proxy / load balancer
postgres	postgres:16-alpine	certctl audit trail + config storage

Quick Start

Prerequisites

• Docker and Docker Compose
• Curl (to interact with APIs)

1. Start Everything

docker compose up -d

This will:

• Initialize step-ca with a self-signed root CA
• Create a JWK provisioner named certctl (pre-configured credentials)
• Start certctl-server (connected to step-ca)
• Start the certctl-agent (ready to deploy certs to HAProxy)
• Start HAProxy with a placeholder config

Monitor logs:

docker compose logs -f certctl-server

TLS Security

certctl is HTTPS-only as of v2.2. The demo compose stack provisions a self-signed certificate. When accessing https://localhost:8443, you can either:

• Use curl --cacert ./deploy/test/certs/ca.crt ... to pin the CA certificate
• Use curl -k ... for quick smoke tests (never in production)
• Import the CA at ./deploy/test/certs/ca.crt into your OS trust store for browser visits

Wait for all services to reach healthy state:

docker compose ps

Expected output:

NAME                              STATUS
certctl-postgres-...              healthy
certctl-server-...                healthy
step-ca-...                       healthy
certctl-agent-...                 running
certctl-haproxy-...               healthy

2. Access certctl Dashboard

Open your browser to:

https://localhost:8443

You should see an empty dashboard. This is expected — no certificates issued yet.

3. Create a Certificate Profile

This defines what certificates certctl can issue (key algorithm, max TTL, allowed names).

curl -X POST https://localhost:8443/api/v1/profiles \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "internal-web",
    "key_type": "rsa-2048",
    "max_ttl_days": 90,
    "description": "Internal web services"
  }'

4. Create an HAProxy Deployment Target

This tells certctl where to deploy certificates on the HAProxy server.

curl -X POST https://localhost:8443/api/v1/targets \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "haproxy-01",
    "type": "haproxy",
    "enabled": true,
    "config": {
      "pem_path": "/etc/haproxy/ssl/cert.pem",
      "reload_command": "systemctl reload haproxy",
      "validate_command": "haproxy -c -f /etc/haproxy/haproxy.cfg"
    }
  }'

Note: In the Docker Compose environment, reload command can be kill -HUP $(pidof haproxy) instead of systemctl reload haproxy.

5. Create a Renewal Policy

This ties a certificate profile to a deployment target and sets renewal thresholds.

curl -X POST https://localhost:8443/api/v1/renewal-policies \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "haproxy-internal-web",
    "profile_id": "<profile_id_from_step_3>",
    "issuer_id": "iss-stepca",
    "enabled": true,
    "renewal_days_before_expiry": 30,
    "alert_thresholds_days": [30, 14, 7, 0]
  }'

Get the issuer ID:

curl https://localhost:8443/api/v1/issuers | jq '.'

You should see iss-stepca in the list.

6. Issue a Certificate

Request a certificate via the API. The server will sign it via step-ca.

curl -X POST https://localhost:8443/api/v1/certificates \
  -H 'Content-Type: application/json' \
  -d '{
    "common_name": "api.internal.example.com",
    "sans": ["api.internal.example.com", "api.staging.example.com"],
    "issuer_id": "iss-stepca",
    "profile_id": "<profile_id_from_step_3>"
  }'

7. Deploy to HAProxy

Get the certificate ID and trigger deployment:

curl -X POST https://localhost:8443/api/v1/certificates/<cert_id>/deploy \
  -H 'Content-Type: application/json' \
  -d '{
    "target_id": "<target_id_from_step_4>"
  }'

The agent will:

1. Fetch the deployment job
2. Generate a combined PEM (cert + chain + key) locally
3. Write it to /etc/haproxy/ssl/cert.pem on HAProxy
4. Reload HAProxy
5. Report status back to certctl

8. Verify in Dashboard

Refresh https://localhost:8443 and you should see:

• 1 certificate (status: Active, expiry in 90 days)
• 1 deployment job (status: Completed)
• 1 agent (heartbeat: recent)

Configuration Details

step-ca Integration

step-ca is configured with:

• Root CA Name: certctl-demo-ca
• Provisioner: certctl (JWK type)
• Default Password: certctl-provisioner-demo (override with STEP_CA_PROVISIONER_PASSWORD)

To inspect step-ca:

docker compose exec step-ca step ca provisioner list
docker compose exec step-ca step ca health --insecure

HAProxy Combined PEM Format

HAProxy requires a single file with certificate, chain, and key concatenated:

-----BEGIN CERTIFICATE-----
[leaf certificate]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[intermediate CA]
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
[private key]
-----END RSA PRIVATE KEY-----

The agent automatically constructs this file from the issued certificate and step-ca-provided chain.

Security: The combined PEM is written with 0600 permissions (owner-readable only) because it contains the private key.

Environment Variables

Customize behavior with:

Variable	Default	Purpose
DB_PASSWORD	certctl-dev-password	PostgreSQL password
STEP_CA_PASSWORD	stepca-demo-password	step-ca root key password
STEP_CA_PROVISIONER_PASSWORD	certctl-provisioner-demo	certctl JWK provisioner password
AGENT_API_KEY	agent-demo-key	Agent authentication token
SERVER_PORT	8443	certctl server external port

Example:

STEP_CA_PASSWORD=myca-password AGENT_API_KEY=secret-key docker compose up -d

Integrating with an Existing step-ca Instance

If you already run step-ca elsewhere (not in this Compose file):

1. Extract the root certificate from your step-ca:

   step ca root /tmp/step-ca-root.crt --ca-url https://ca.internal:9000 --insecure
   

2. Create or retrieve the certctl JWK provisioner key:

   step ca provisioner list --ca-url https://ca.internal:9000 --insecure
   step ca provisioner describe certctl --ca-url https://ca.internal:9000 --insecure
   

3. Update docker-compose.yml:

   certctl-server:
     environment:
       CERTCTL_STEPCA_URL: https://ca.internal:9000
       CERTCTL_STEPCA_ROOT_CERT_PATH: /etc/certctl/step-ca-root.crt
       CERTCTL_STEPCA_PROVISIONER_NAME: certctl
       CERTCTL_STEPCA_PROVISIONER_KEY_PATH: /etc/certctl/step-ca-provisioner.json
       CERTCTL_STEPCA_PROVISIONER_PASSWORD: <your-password>
   

4. Mount the cert and key:

   volumes:
     - /path/to/step-ca-root.crt:/etc/certctl/step-ca-root.crt:ro
     - /path/to/provisioner.json:/etc/certctl/step-ca-provisioner.json:ro
   

Cleanup

docker compose down -v

This removes all containers and volumes (step-ca config, certificates, database).

Next Steps

Production Deployment

• Replace image tags (latest → specific version)
• Use real TLS certificates for step-ca (self-signed is fine internally, but use proper roots for verification)
• Configure persistent storage for step-ca keys (HSM or encrypted filesystem)
• Set CERTCTL_AUTH_TYPE: api-key and rotate API keys regularly
• Enable audit trail export for compliance
• Configure renewal alerts (Slack, email, PagerDuty)
• Run agents on separate machines (not in Compose)

Advanced Features

• Multiple HAProxy instances: Create additional targets and agents
• Policy-based renewal: Set different renewal windows per environment (staging vs. production)
• Approval workflows: Require manual approval before deploying to production
• Discovery: Scan existing HAProxy certs and bring them under management
• Network scanning: Discover TLS endpoints in your network and inventory them

Troubleshooting

step-ca fails to initialize

Check logs:

docker compose logs step-ca

Common issues:

• Permissions on /home/step/step-ca volume
• Port 9000 already in use

Agent can't reach server

Verify network:

docker compose exec certctl-agent curl http://certctl-server:8443/health

HAProxy config validation fails

Check HAProxy config syntax:

docker compose exec haproxy haproxy -c -f /etc/haproxy/haproxy.cfg

Deployment job stays in "Running" state

Check agent logs:

docker compose logs certctl-agent

Likely causes:

• Agent can't write to /etc/haproxy/ssl/cert.pem (permissions)
• Reload command is misconfigured
• HAProxy container is not accessible

Documentation

• certctl Architecture
• step-ca Connector Docs
• HAProxy Target Docs
• API Reference

Support

For issues or questions:

1. Check the troubleshooting guide
2. Review service logs: docker compose logs <service>
3. Open an issue on GitHub