mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 18:41:30 +00:00
shankar0123
52248be717
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).
98 lines
2.5 KiB
Markdown
98 lines
2.5 KiB
Markdown
# Quick Installation Guide
|
|
|
|
## One-Liner Installation
|
|
|
|
### Development (no auth)
|
|
```bash
|
|
helm install certctl certctl/ \
|
|
--set server.auth.type=none \
|
|
--set postgresql.auth.password=dev
|
|
```
|
|
|
|
### Production (with API key)
|
|
```bash
|
|
API_KEY=$(openssl rand -base64 32)
|
|
DB_PASSWORD=$(openssl rand -base64 32)
|
|
|
|
helm install certctl certctl/ \
|
|
--values examples/values-prod-ha.yaml \
|
|
--set server.auth.apiKey="$API_KEY" \
|
|
--set postgresql.auth.password="$DB_PASSWORD"
|
|
```
|
|
|
|
## Verify Installation
|
|
|
|
```bash
|
|
# Wait for pods to be ready
|
|
kubectl rollout status deployment/certctl-server
|
|
kubectl rollout status statefulset/certctl-postgres
|
|
|
|
# Check all components
|
|
kubectl get pods -l app.kubernetes.io/instance=certctl
|
|
|
|
# View server logs
|
|
kubectl logs -l app.kubernetes.io/component=server -f
|
|
|
|
# Access the API (HTTPS-only as of v2.2; use --cacert or -k depending on your cert provisioning)
|
|
kubectl port-forward svc/certctl-server 8443:8443 &
|
|
# If the chart provisioned a self-signed cert, fetch the CA bundle from the secret first:
|
|
# kubectl get secret certctl-server-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > /tmp/certctl-ca.crt
|
|
curl --cacert /tmp/certctl-ca.crt https://localhost:8443/health
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. **Read Documentation**
|
|
- `README.md` - Complete reference
|
|
- `DEPLOYMENT_GUIDE.md` - Step-by-step guide
|
|
- `CHART_SUMMARY.md` - Architecture overview
|
|
|
|
2. **Configure for Your Environment**
|
|
- Review `examples/` for your deployment scenario
|
|
- Customize `values.yaml` as needed
|
|
- Use `helm upgrade` to apply changes
|
|
|
|
3. **Set Up Monitoring**
|
|
- Install Prometheus (optional)
|
|
- Enable Ingress with HTTPS
|
|
- Configure email notifications
|
|
|
|
4. **Deploy Agents**
|
|
- Agents deploy automatically as DaemonSet
|
|
- Verify with: `kubectl get pods -l app.kubernetes.io/component=agent`
|
|
|
|
5. **Create Certificates**
|
|
- Configure issuer connectors (Local CA, ACME, etc.)
|
|
- Access web dashboard at ingress or port-forward
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# List installations
|
|
helm list
|
|
|
|
# View chart values
|
|
helm values certctl
|
|
|
|
# Upgrade chart
|
|
helm upgrade certctl certctl/ -f new-values.yaml
|
|
|
|
# Rollback to previous version
|
|
helm rollback certctl 1
|
|
|
|
# Uninstall chart
|
|
helm uninstall certctl
|
|
|
|
# View deployment history
|
|
helm history certctl
|
|
|
|
# Dry-run installation to see generated YAML
|
|
helm install certctl certctl/ --dry-run --debug
|
|
```
|
|
|
|
## Support
|
|
|
|
- Full documentation in `README.md`
|
|
- Troubleshooting in `DEPLOYMENT_GUIDE.md`
|
|
- Issues: https://github.com/shankar0123/certctl
|