mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 16:41:36 +00:00
shankar0123
bcf2c3ae92
Pre-2.1.0 adoption polish delivering all four milestones: A) Demo Data Overhaul — seed_demo.sql rewritten with 35 certs across 5 issuers, 8 agents, 8 targets, 50+ jobs spanning 90 days, 55+ audit events, discovery scans, network scan targets, S/MIME cert. B) Examples Directory — 5 turnkey docker-compose configs: acme-nginx, acme-wildcard-dns01, private-ca-traefik, step-ca-haproxy, multi-issuer. C) Migration Guides — migrate-from-certbot.md, migrate-from-acmesh.md, certctl-for-cert-manager-users.md. D) Agent Install Script — install-agent.sh with cross-platform support (Linux systemd + macOS launchd), release.yml updated for 6-target cross-compilation. Triple-audited against codebase: 22 factual corrections applied across docs, examples, and config (env var names, CLI flags, ports, DNS hook interface, scheduler loop counts, license conversion date). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
162 lines
6.3 KiB
Markdown
162 lines
6.3 KiB
Markdown
# Migrating from Certbot to certctl
|
|
|
|
You have 50 Let's Encrypt certificates across 10 servers, managed by a mix of Certbot cron jobs and manual renewals. Certbot handles issuance, but you lack inventory visibility, centralized alerting, and audit trails. This guide walks you through moving to certctl while keeping your existing certificates and ACME account.
|
|
|
|
## Why Migrate
|
|
|
|
Certbot renews certs in isolation. If a renewal fails on one server, you don't know until the cert expires. certctl gives you a single pane of glass: see all certs across all servers, get alerts 30/14/7 days before expiry, track who renewed what when, and verify each deployment succeeded via TLS fingerprint validation.
|
|
|
|
## What You Keep
|
|
|
|
- Your existing Certbot ACME account key and Let's Encrypt account
|
|
- All issued certificates in `/etc/letsencrypt/live/`
|
|
- Certbot's renewal history and hooks
|
|
|
|
You will not re-issue any certificates. certctl discovers them and takes over renewal scheduling.
|
|
|
|
## Step-by-Step Migration
|
|
|
|
### 1. Deploy certctl Control Plane
|
|
|
|
Option A: Docker Compose (quickest for evaluation)
|
|
```bash
|
|
cd /opt/certctl
|
|
docker compose up -d
|
|
# Dashboard & API: https://localhost:8443
|
|
# Default API key in logs (grep CERTCTL_API_KEY docker logs certctl-server)
|
|
```
|
|
|
|
Option B: Kubernetes (Helm)
|
|
```bash
|
|
helm install certctl deploy/helm/certctl/ \
|
|
--set auth.apiKey=YOUR_SECURE_KEY
|
|
```
|
|
|
|
### 2. Deploy Agents to Each Server
|
|
|
|
On each of your 10 servers running Certbot:
|
|
|
|
```bash
|
|
# Linux amd64 (adjust for your architecture)
|
|
curl -sSL https://github.com/shankar0123/certctl/releases/download/v2.1.0/certctl-agent-linux-amd64 \
|
|
-o /usr/local/bin/certctl-agent
|
|
chmod +x /usr/local/bin/certctl-agent
|
|
|
|
# Create config
|
|
sudo mkdir -p /etc/certctl /var/lib/certctl/keys
|
|
sudo tee /etc/certctl/agent.env > /dev/null <<EOF
|
|
CERTCTL_SERVER_URL=https://certctl-control-plane.example.com:8080
|
|
CERTCTL_API_KEY=your-api-key-here
|
|
CERTCTL_DISCOVERY_DIRS=/etc/letsencrypt/live
|
|
CERTCTL_KEY_DIR=/var/lib/certctl/keys
|
|
EOF
|
|
sudo chmod 600 /etc/certctl/agent.env
|
|
|
|
# Start agent
|
|
sudo systemctl start certctl-agent # if installed via script
|
|
# OR manually:
|
|
sudo certctl-agent --server https://... --api-key ... --discovery-dirs /etc/letsencrypt/live
|
|
```
|
|
|
|
The agent will scan `/etc/letsencrypt/live/` and report all discovered certificates to the control plane.
|
|
|
|
### 3. Triage Discovered Certificates
|
|
|
|
In the certctl dashboard, go to **Discovery**:
|
|
- See all discovered certs grouped by agent
|
|
- Status shows "Unmanaged" for certificates not yet claimed
|
|
- For each Certbot cert, click **Claim** and link it to managed inventory
|
|
|
|
The control plane now knows about all 50 certs and where they live.
|
|
|
|
### 4. Configure ACME Issuer
|
|
|
|
Go to **Issuers** → **Add Issuer**:
|
|
- Type: ACME
|
|
- Directory URL: `https://acme-v02.api.letsencrypt.org/directory` (production)
|
|
- Email: your Let's Encrypt account email
|
|
- Challenge Type: `http-01` (if you have HTTP access) or `dns-01` (for wildcard/internal certs)
|
|
- For DNS-01, provide your DNS provider's script hook (Cloudflare, Route53, Azure DNS, etc.)
|
|
|
|
Test the connection. certctl uses the same Let's Encrypt account; no new credentials needed.
|
|
|
|
### 5. Create Renewal Policies
|
|
|
|
Go to **Policies** → **New Policy**:
|
|
- Profile: ACME (or create a new one with `serverAuth` EKU)
|
|
- Issuer: the ACME issuer you just created
|
|
- Renewal Threshold: 30 days before expiry (default, adjust as needed)
|
|
- Scope: select agent groups or individual agents managing your servers
|
|
|
|
Assign this policy to your discovered certs.
|
|
|
|
### 6. Disable Certbot Cron, One Server at a Time
|
|
|
|
On the first server (start with a low-traffic one):
|
|
|
|
```bash
|
|
# Stop Certbot renewal
|
|
sudo systemctl disable certbot.timer
|
|
sudo systemctl stop certbot.timer
|
|
|
|
# Or remove the cron job
|
|
sudo rm /etc/cron.d/certbot # if managed by cron
|
|
```
|
|
|
|
Monitor that server in the certctl dashboard. Certctl will renew the cert ~30 days before expiry.
|
|
|
|
### 7. Verify First Renewal Succeeds
|
|
|
|
Wait for the renewal to trigger (or manually trigger it in **Certificates** → select cert → **Renew**). Check the dashboard:
|
|
- **Certificates** page: status transitions from `Active` to `Renewing` to `Active`
|
|
- **Jobs** page: renewal job shows `Completed` status
|
|
- **Verification** tab: TLS check confirms the new cert is deployed and live
|
|
|
|
After verifying, disable Certbot on the remaining 9 servers.
|
|
|
|
### 8. Enable Alerting
|
|
|
|
Configure notifiers via environment variables before starting the server:
|
|
```bash
|
|
# Example: Slack alerting
|
|
export CERTCTL_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
|
|
docker compose up -d
|
|
|
|
# Or email alerting
|
|
export CERTCTL_SMTP_HOST=smtp.gmail.com
|
|
export CERTCTL_SMTP_PORT=587
|
|
export CERTCTL_SMTP_USERNAME=your-email@gmail.com
|
|
export CERTCTL_SMTP_PASSWORD=your-app-password
|
|
export CERTCTL_SMTP_FROM_ADDRESS=certctl@example.com
|
|
docker compose up -d
|
|
|
|
# Other options: CERTCTL_TEAMS_WEBHOOK_URL, CERTCTL_PAGERDUTY_ROUTING_KEY, CERTCTL_OPSGENIE_API_KEY
|
|
```
|
|
|
|
Now you get 30/14/7-day warnings before any cert expires, across all 50 servers, in one place.
|
|
|
|
## What Changes
|
|
|
|
- **Renewal**: Agent polls certctl for work instead of Certbot cron triggering locally. Faster failure detection (agent heartbeat every 5 minutes vs. cron running once a day).
|
|
- **Deployment**: certctl verifies post-deployment by probing the live TLS endpoint and comparing SHA-256 fingerprints. Catches reload failures silently.
|
|
- **Audit Trail**: Every renewal, deployment, and alert is logged immutably. Answer "who renewed cert X when and why" within seconds.
|
|
- **Alerting**: Threshold-based alerts to Slack/email/webhook 30/14/7 days before expiry, not when cert expires.
|
|
|
|
## Coexistence and Rollback
|
|
|
|
During migration, certctl and Certbot can run simultaneously. The agent will discover Certbot certs even while Certbot continues renewing them. Run both for a week to build confidence.
|
|
|
|
**If you need to rollback**: Re-enable Certbot cron on any server:
|
|
```bash
|
|
sudo systemctl enable certbot.timer
|
|
sudo systemctl start certbot.timer
|
|
```
|
|
|
|
certctl will stop renewing that cert when the policy is disabled. Certbot resumes as before. Your certificates and ACME account remain untouched.
|
|
|
|
## Next Steps
|
|
|
|
- Review the [Concepts Guide](./concepts.md) for terminology (profiles, policies, agents, jobs)
|
|
- Explore [Network Discovery](./quickstart.md#network-discovery) to find certificates you didn't know about
|
|
- Set up [Kubernetes cert-manager integration](./cert-manager.md) if you manage in-cluster certs too
|