gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 12:21:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

v2.0.47: HTTPS Everywhere — TLS-only control plane, agents/CLI/MCP

Browse Source 
Breaking change release. Plaintext HTTP listener removed. The certctl
control plane now terminates TLS 1.3 on :8443 via
http.Server.ListenAndServeTLS. No CERTCTL_TLS_ENABLED=false escape
hatch. No dual-listener mode. One-step cutover per docs/upgrade-to-tls.md.

Server
- cmd/server/tls.go: certHolder with SIGHUP hot-reload + atomic cert
  swap, buildServerTLSConfig (TLS 1.3 min, GetCertificate callback),
  preflightServerTLS validation
- cmd/server/main.go: ListenAndServeTLS in place of ListenAndServe,
  watchSIGHUP wiring, cert/key path config threading
- tls_test.go: 418-line regression coverage of reload, preflight,
  callback behavior, SAN validation

Config
- CERTCTL_TLS_CERT_PATH / CERTCTL_TLS_KEY_PATH (required)
- Plaintext rejection: agents/CLI/MCP pre-flight-fail on http://
  URLs with a pointer to docs/upgrade-to-tls.md

Agents, CLI, MCP
- All three pre-flight-reject http:// URLs with fail-loud diagnostic
- CERTCTL_SERVER_CA_BUNDLE_PATH for private-CA trust
- CERTCTL_SERVER_TLS_INSECURE_SKIP_VERIFY for dev-only bypass
  (loud warning on startup)
- install-agent.sh emits both vars as commented template lines

docker-compose
- certctl-tls-init sidecar generates SAN-valid self-signed cert into
  deploy/test/certs/ on first boot
- All demo-stack curls pin against ca.crt with --cacert

Helm chart
- Three TLS provisioning modes, exactly one required:
  - server.tls.existingSecret (operator-supplied)
  - server.tls.certManager.enabled (cert-manager integration)
  - server.tls.selfSigned.enabled (eval only — not for production)
- server-certificate.yaml template for cert-manager mode
- helm install without a TLS source fails at template render with
  a pointer to docs/tls.md

CI
- .github/workflows/ci.yml Helm Chart Validation step renders the
  chart in both existingSecret and cert-manager modes, plus an
  inverse guard-regression test that asserts helm template MUST
  refuse to render when no TLS source is configured. Previously
  the single `helm template` invocation hit the certctl.tls.required
  fail-loud guard and exit-1'd CI. Four invocations now: lint
  (existingSecret), template (existingSecret), template
  (cert-manager), template (no args — must fail).

Integration tests
- deploy/test/integration_test.go stands up the Compose stack over
  HTTPS, extracts the CA bundle, and exercises every certctl API
  over https://localhost:8443
- All 34 integration subtests green (per Phase 8 local CI-parity)

Documentation
- New: docs/tls.md (provisioning patterns, rotation, SIGHUP reload)
- New: docs/upgrade-to-tls.md (one-step cutover, no-downgrade
  warnings, fleet-roll sequencing)
- CHANGELOG.md: v2.2.0 "HTTPS Everywhere — The Irony" entry
  (file heading unchanged; release tag is v2.0.47)
- All curls in docs/, examples/, deploy/helm/ guides use
  https://localhost:8443 --cacert

Verification
- grep -rn "ListenAndServe[^T]" cmd/ internal/ → 0 hits
- grep -rn "\"http://" cmd/ internal/ → 2 benign hits (Caddy admin
  API default, SSRF doc comment) — zero certctl endpoints
- Tasks #197–#206 (Phases 0–8) all closed in the tracker

Files: 65 changed, 3489 insertions, 372 deletions (pre-CI-fix).
This commit is contained in:
shankar0123
2026-04-20 03:31:05 +00:00
parent 04c7eca615
commit 52248be717
66 changed files with 3518 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/acme-nginx/acme-nginx.md
+8 -1
View File
@@ -36,6 +36,13 @@ flowchart TD
If you don't have a real domain or can't open port 80, see [Customization Tips](#customization-tips) below.
## 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
## Quick Start
### 1. Clone or copy this example
@@ -122,7 +129,7 @@ docker compose logs -f certctl-server certctl-agent
### 5. Access the dashboard
Navigate to `http://localhost:8443` (or your `SERVER_PORT`)
Navigate to `https://localhost:8443` (or your `SERVER_PORT`)
You should see:
- An empty certificate inventory (no certs issued yet)
examples/acme-nginx/docker-compose.yml
+1 -1
View File
@@ -61,7 +61,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
test: ['CMD-SHELL', 'curl -sfk https://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/acme-wildcard-dns01/acme-wildcard-dns01.md
+8 -1
View File
@@ -9,6 +9,13 @@ This example is ideal for:
- Internal PKI with public DNS names
- Scenarios where you have programmatic access to your DNS provider's API
## 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
## Prerequisites
Before running this example, you need:
@@ -74,7 +81,7 @@ This starts:
### Step 5: Access the Dashboard
Open your browser to `http://localhost:8443`
Open your browser to `https://localhost:8443`
### Step 6: Create a Wildcard Certificate
examples/acme-wildcard-dns01/docker-compose.yml
+1 -1
View File
@@ -113,7 +113,7 @@ services:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
test: ['CMD-SHELL', 'curl -sfk https://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/multi-issuer/docker-compose.yml
+1 -1
View File
@@ -64,7 +64,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
test: ['CMD-SHELL', 'curl -sfk https://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/multi-issuer/multi-issuer.md
+8 -1
View File
@@ -45,6 +45,13 @@ flowchart TD
- **Domain for ACME** (optional) — if using real Let's Encrypt, not needed for demo
- **Internet connectivity** — to reach Let's Encrypt's API (demo can use staging directory)
## 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
## Quick Start
### 1. Clone or navigate to this directory
@@ -83,7 +90,7 @@ This spins up:
### 4. Access the dashboard
Open your browser to **http://localhost:8443** (or your configured SERVER_PORT)
Open your browser to **https://localhost:8443** (or your configured SERVER_PORT)
You should see:
- Empty cert inventory (fresh start)
examples/private-ca-traefik/docker-compose.yml
+1 -1
View File
@@ -77,7 +77,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
test: ['CMD-SHELL', 'curl -sfk https://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/private-ca-traefik/private-ca-traefik.md
+18 -11
View File
@@ -29,6 +29,13 @@ flowchart TD
C -->|TLS handshakes| D
```
## 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
## Quick Start (Self-Signed CA)
The simplest way to get running in 2 minutes:
@@ -58,7 +65,7 @@ EOF
docker compose up -d
# 4. Access the dashboards
# - certctl: http://localhost:8443 (API only, use the CLI or direct HTTP calls)
# - certctl: https://localhost:8443 (API only, use the CLI or direct HTTP calls)
# - Traefik dashboard: http://localhost:8080
```
@@ -112,7 +119,7 @@ Once the stack is running:
```bash
# 1. Create a certificate profile in certctl (defines allowed key types, TTL, etc.)
curl -X POST http://localhost:8443/api/v1/profiles \
curl -X POST https://localhost:8443/api/v1/profiles \
-H "Content-Type: application/json" \
-d '{
"id": "prof-internal",
@@ -123,7 +130,7 @@ curl -X POST http://localhost:8443/api/v1/profiles \
}'
# 2. Create a renewal policy (defines issuer, renewal thresholds, etc.)
curl -X POST http://localhost:8443/api/v1/policies \
curl -X POST https://localhost:8443/api/v1/policies \
-H "Content-Type: application/json" \
-d '{
"id": "pol-internal",
@@ -135,7 +142,7 @@ curl -X POST http://localhost:8443/api/v1/policies \
}'
# 3. Create a certificate (triggers issuance immediately)
curl -X POST http://localhost:8443/api/v1/certificates \
curl -X POST https://localhost:8443/api/v1/certificates \
-H "Content-Type: application/json" \
-d '{
"common_name": "api.internal.local",
@@ -144,7 +151,7 @@ curl -X POST http://localhost:8443/api/v1/certificates \
}'
# 4. Create a Traefik target (agent will deploy to this)
curl -X POST http://localhost:8443/api/v1/targets \
curl -X POST https://localhost:8443/api/v1/targets \
-H "Content-Type: application/json" \
-d '{
"id": "target-traefik-01",
@@ -156,7 +163,7 @@ curl -X POST http://localhost:8443/api/v1/targets \
}'
# 5. Create a deployment job (agent picks this up and deploys)
curl -X POST http://localhost:8443/api/v1/certificates/{cert-id}/deploy \
curl -X POST https://localhost:8443/api/v1/certificates/{cert-id}/deploy \
-H "Content-Type: application/json" \
-d '{
"target_ids": ["target-traefik-01"]
@@ -209,16 +216,16 @@ The server provides a REST API on port 8443. Example queries:
```bash
# List all certificates
curl http://localhost:8443/api/v1/certificates
curl https://localhost:8443/api/v1/certificates
# Check certificate status
curl http://localhost:8443/api/v1/certificates/{cert-id}
curl https://localhost:8443/api/v1/certificates/{cert-id}
# View audit trail
curl http://localhost:8443/api/v1/audit
curl https://localhost:8443/api/v1/audit
# Check renewal policy compliance
curl http://localhost:8443/api/v1/policies/{policy-id}
curl https://localhost:8443/api/v1/policies/{policy-id}
```
### Traefik Dashboard
@@ -290,7 +297,7 @@ Changes are picked up automatically (file watcher enabled).
docker compose logs certctl-agent | grep heartbeat
# Check deployment job status
curl http://localhost:8443/api/v1/jobs | jq '.[] | select(.type == "Deployment")'
curl https://localhost:8443/api/v1/jobs | jq '.[] | select(.type == "Deployment")'
# Check Traefik is watching the directory
docker compose exec traefik ls -la /etc/traefik/certs/
examples/step-ca-haproxy/docker-compose.yml
+1 -1
View File
@@ -119,7 +119,7 @@ services:
networks:
- certctl-network
healthcheck:
test: ['CMD-SHELL', 'curl -sf http://localhost:8443/health || exit 1']
test: ['CMD-SHELL', 'curl -sfk https://localhost:8443/health || exit 1']
interval: 10s
timeout: 5s
retries: 3
examples/step-ca-haproxy/step-ca-haproxy.md
+15 -8
View File
@@ -48,6 +48,13 @@ 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:
```bash
@@ -69,7 +76,7 @@ certctl-haproxy-... healthy
Open your browser to:
```
http://localhost:8443
https://localhost:8443
```
You should see an empty dashboard. This is expected — no certificates issued yet.
@@ -79,7 +86,7 @@ You should see an empty dashboard. This is expected — no certificates issued y
This defines what certificates certctl can issue (key algorithm, max TTL, allowed names).
```bash
curl -X POST http://localhost:8443/api/v1/profiles \
curl -X POST https://localhost:8443/api/v1/profiles \
-H 'Content-Type: application/json' \
-d '{
"name": "internal-web",
@@ -94,7 +101,7 @@ curl -X POST http://localhost:8443/api/v1/profiles \
This tells certctl where to deploy certificates on the HAProxy server.
```bash
curl -X POST http://localhost:8443/api/v1/targets \
curl -X POST https://localhost:8443/api/v1/targets \
-H 'Content-Type: application/json' \
-d '{
"name": "haproxy-01",
@@ -115,7 +122,7 @@ Note: In the Docker Compose environment, reload command can be `kill -HUP $(pido
This ties a certificate profile to a deployment target and sets renewal thresholds.
```bash
curl -X POST http://localhost:8443/api/v1/renewal-policies \
curl -X POST https://localhost:8443/api/v1/renewal-policies \
-H 'Content-Type: application/json' \
-d '{
"name": "haproxy-internal-web",
@@ -130,7 +137,7 @@ curl -X POST http://localhost:8443/api/v1/renewal-policies \
Get the issuer ID:
```bash
curl http://localhost:8443/api/v1/issuers | jq '.'
curl https://localhost:8443/api/v1/issuers | jq '.'
```
You should see `iss-stepca` in the list.
@@ -140,7 +147,7 @@ You should see `iss-stepca` in the list.
Request a certificate via the API. The server will sign it via step-ca.
```bash
curl -X POST http://localhost:8443/api/v1/certificates \
curl -X POST https://localhost:8443/api/v1/certificates \
-H 'Content-Type: application/json' \
-d '{
"common_name": "api.internal.example.com",
@@ -155,7 +162,7 @@ curl -X POST http://localhost:8443/api/v1/certificates \
Get the certificate ID and trigger deployment:
```bash
curl -X POST http://localhost:8443/api/v1/certificates/<cert_id>/deploy \
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>"
@@ -171,7 +178,7 @@ The agent will:
### 8. Verify in Dashboard
Refresh http://localhost:8443 and you should see:
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)