mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:51:30 +00:00
shankar0123
d809874fa1
Per operator decision the framework-mapping docs are gone. They
were aspirational (no audit, no certification, no validated
mapping); keeping them around was misleading.
Files deleted (1,883 lines):
- docs/compliance/index.md
- docs/compliance/soc2.md
- docs/compliance/pci-dss.md
- docs/compliance/nist-sp-800-57.md
Hyperlinks removed:
- README.md: 'Auditor / compliance' row in the doc table; the
'(compliance mapping included)' parenthetical in the
positioning paragraph
- docs/README.md: the '## Compliance' section table; the
'Auditor / compliance team' reading-order-by-role row
Prose name-drops swept across 24 files:
- README.md: 'FedRAMP boundary CAs / financial-services policy
CAs' → '4-level boundary CAs / 3-level policy CAs';
'Compliance-grade for PCI-DSS Level 1, FedRAMP Moderate / High,
SOC 2 Type II, HIPAA' → cut entirely
- getting-started/{quickstart,concepts,examples,why-certctl,
advanced-demo}.md: 'compliance' → 'audit' / 'policy';
'PCI-DSS / SOC 2 / NIST SP 800-57' framework lists cut;
''pci': 'true'' tag example → ''environment': 'production''
- migration/cert-manager-coexistence.md: 'compliance rules' →
'policy rules'
- operator/approval-workflow.md: 'Compliance customers (PCI-DSS
Level 1, FedRAMP Moderate / High, SOC 2 Type II, HIPAA)' →
'Operators'; entire 'Compliance control mapping' table
(PCI-DSS §6.4.5 / NIST SP 800-53 SA-15 / SOC 2 Type II CC6.1
/ HIPAA §164.308(a)(4)) deleted; 'compliance contract' →
'two-person-integrity contract'; 'compliance auditors' →
'reviewers'
- operator/legacy-clients-tls-1.2.md: 'PCI-DSS v4.0 Req 4 §2.2.5'
audit-reference → CWE-326 (kept); 'PCI-DSS Req 4 §2.2.5
attestation' section retitled to 'TLS posture summary' and
rewritten without framework framing; 'PCI-DSS, NIST, and
major browsers will eventually deprecate TLS 1.2' →
'Major browsers and OS vendors will eventually deprecate
TLS 1.2'
- operator/database-tls.md: PCI-DSS Req 4 §2.2.5 audit-ref →
CWE-319 only; 'PCI-DSS scope' → 'sensitive data'; PCI-DSS
Req 4 v4.0 prose footing → cut
- operator/runbooks/disaster-recovery.md: 'SOC 2 / PCI
procurement-team deliverable' → 'on-call deliverable';
'compliance auditors' → 'reviewers'
- reference/connectors/{acme,aws-acm,azure-kv,globalsign,
local-ca,openssl,ssh,index}.md: 'compliance reporting
(PCI-DSS §3.6, HIPAA §164.312)' → 'audit reporting';
'Compliance environments (PCI-DSS Level 1, FedRAMP High,
HIPAA)' → 'Regulated environments'; 'compliance audits' →
'audit'; 'FedRAMP boundary CA' pattern names →
'4-level boundary CA' (technically descriptive)
- reference/protocols/est.md: 'compliance-hook seam' →
'device-state hook seam'; 'compliance gating' → 'device-state
gating'; 'est_compliance_failed' → 'est_device_state_failed'
- reference/protocols/scep-intune.md: 'Optional compliance
check' → 'Optional device-state check'; failure-counter
'compliance_failed' → 'device_state_failed'; 'Conditional
Access compliance gating' → 'Conditional Access
device-state gating'
- reference/intermediate-ca-hierarchy.md: 'FedRAMP boundary-CA
deployments where the regulator requires...' →
'Boundary-CA deployments where you want separation of policy
and issuing authorities'; pattern A retitled '4-level FedRAMP
boundary CA' → '4-level boundary CA'
- reference/architecture.md: broken Related-docs link to
compliance.md removed; the rest of that block had stale
pre-Phase-2 paths (quickstart.md, demo-advanced.md,
connectors.md, openapi.md, testing-guide.md, test-env.md) —
retargeted to current locations
- reference/deployment-model.md: 'SOC 2 evidence-report
generator' → 'Audit-evidence report generator'
- reference/vendor-matrix.md: 'SOC 2 / PCI auditors paste this
into evidence packs' → 'reviewers paste this into
vendor-evaluation packs'
- contributor/qa-test-suite.md: 'compliance exist' coverage
description cut; 'Compliance (PCI / SOC2 / HIPAA-relevant)'
risk-class label → 'Audit-relevant'
What was kept:
- CWE references (legitimate technical pointers)
- Microsoft API/feature names that happen to use 'compliance'
literally ('Microsoft Graph compliance API',
'device-compliance validators' — these are MS product names,
not framework name-drops)
- 'NIST PQC' on the landing page (Post-Quantum Cryptography is
the actual NIST standard family, not a compliance framework)
Verified: zero hyperlinks into docs/compliance/ remain. All 24
ci-guards/*.sh pass locally. qa-doc-seed-count.sh clean.
Net diff: 26 files / -1,883 deletions in compliance/ + -32 net
across the prose sweep.
Companion edits in cowork/ (CLAUDE.md doc-tree summary +
WORKSPACE-CHANGELOG.md retirement note) land separately.
148 lines
7.0 KiB
Markdown
148 lines
7.0 KiB
Markdown
# certctl for cert-manager Users
|
|
|
|
> Last reviewed: 2026-05-05
|
|
|
|
You run cert-manager inside Kubernetes and it works well for in-cluster certificates. But you also have VMs, bare-metal servers, network appliances, and legacy systems outside the cluster. cert-manager can't reach those. This guide shows how certctl complements cert-manager to give you unified certificate visibility and automation across your entire infrastructure.
|
|
|
|
## Not a Replacement
|
|
|
|
cert-manager is the right tool for in-cluster certs. It's tightly integrated with Kubernetes:
|
|
- Native CRDs (Certificate, ClusterIssuer, Issuer)
|
|
- Automatic cert injection into Ingress and Service objects
|
|
- Controller-driven renewal within the cluster
|
|
|
|
**certctl does not replace this.** Instead, it extends your certificate management to everything outside Kubernetes: VMs, bare metal, network appliances, Windows servers, and legacy systems.
|
|
|
|
## The Problem
|
|
|
|
Your setup:
|
|
- **cert-manager**: handles all certs in Kubernetes (TLS for Ingress, service-to-service, internal services)
|
|
- **Everything else**: NGINX/Apache on VMs, HAProxy load balancers on bare metal, network appliances, Windows servers with IIS — these are managed inconsistently. Maybe Certbot cron jobs, maybe manual renewal, maybe deprecated cert files sitting around.
|
|
|
|
Result:
|
|
- No unified visibility — you don't know when non-Kubernetes certs expire
|
|
- Renewal failures go unnoticed until the cert is already expired
|
|
- Audit trail fragmented across multiple tools
|
|
- Scaling to hundreds of machines becomes impossible
|
|
|
|
## The Solution
|
|
|
|
Deploy certctl control plane once (Docker Compose, Kubernetes Helm chart, or self-hosted). Deploy agents on your VMs, bare metal, and network appliances. One dashboard shows:
|
|
- **All cert-manager certs** via discovery scanning (agents find cert-manager-issued certs copied to target machines, or scan the cluster directly)
|
|
- **All certctl-managed certs** issued by shared issuers (ACME, step-ca, Vault PKI (planned), private CA)
|
|
- **Unified renewal and deployment** across both worlds
|
|
- **Single pane of glass** with expiration timeline, renewal status, deployment verification, audit trail
|
|
|
|
## How to Set Up
|
|
|
|
### 1. Install certctl Control Plane
|
|
|
|
**Option A: Docker Compose** (quickest for evaluation)
|
|
```bash
|
|
cd /opt/certctl
|
|
docker compose up -d
|
|
# Dashboard & API: https://localhost:8443 (self-signed cert — pin with --cacert ./deploy/test/certs/ca.crt)
|
|
```
|
|
|
|
**Option B: Kubernetes** (recommended for prod)
|
|
```bash
|
|
helm install certctl deploy/helm/certctl/ \
|
|
--set auth.apiKey=YOUR_SECURE_KEY
|
|
```
|
|
|
|
### 2. Deploy Agents to Non-Kubernetes Infrastructure
|
|
|
|
On each VM, bare-metal server, or appliance (via proxy agent):
|
|
```bash
|
|
# Linux amd64
|
|
curl -sSL https://github.com/certctl-io/certctl/releases/download/v2.1.0/certctl-agent-linux-amd64 \
|
|
-o /usr/local/bin/certctl-agent
|
|
chmod +x /usr/local/bin/certctl-agent
|
|
|
|
# Config
|
|
sudo tee /etc/certctl/agent.env > /dev/null <<EOF
|
|
CERTCTL_SERVER_URL=https://certctl-control-plane:8443
|
|
CERTCTL_SERVER_CA_BUNDLE_PATH=/etc/certctl/tls/ca.crt
|
|
CERTCTL_API_KEY=your-api-key
|
|
CERTCTL_DISCOVERY_DIRS=/etc/nginx/certs,/etc/ssl,/etc/letsencrypt/live
|
|
CERTCTL_KEY_DIR=/var/lib/certctl/keys
|
|
EOF
|
|
sudo chmod 600 /etc/certctl/agent.env
|
|
|
|
# Start
|
|
sudo systemctl start certctl-agent
|
|
```
|
|
|
|
### 3. Enable Discovery Scanning
|
|
|
|
Agents scan configured directories and report back all existing certs. In the dashboard:
|
|
- **Discovery** page: all found certs grouped by agent
|
|
- Claim cert-manager certs to link them with Kubernetes metadata
|
|
- Dismiss obsolete certs
|
|
|
|
### 4. Configure Shared Issuers
|
|
|
|
Set up the same issuer certctl uses for non-Kubernetes certs:
|
|
- **ACME** (Let's Encrypt, for public certs)
|
|
- **step-ca** (Smallstep, for internal certs)
|
|
- **Vault PKI** (HashiCorp Vault, for enterprise PKI)
|
|
- **Private CA** (your own internal root CA)
|
|
|
|
No new CA infrastructure needed. If cert-manager already uses your CA, certctl points to the same one.
|
|
|
|
### 5. Create Policies for Non-Kubernetes Certs
|
|
|
|
Go to **Policies** → **+ New Policy** to create enforcement rules:
|
|
- **Name:** e.g., "VM Certificate Policy"
|
|
- **Type:** `expiration_window` or `key_algorithm` (enforce renewal thresholds or crypto requirements)
|
|
- **Severity:** `high`
|
|
- **Config:** set your enforcement parameters
|
|
|
|
Certificates are linked to issuers and profiles when created or claimed from discovery. Policies add guardrails — enforcing key algorithm requirements, expiration windows, and other policy rules across your fleet.
|
|
|
|
### 6. View Unified Inventory
|
|
|
|
**Dashboard** shows:
|
|
- Certificate status heatmap (all 1000 certs: cert-manager + certctl)
|
|
- Renewal job trends (both types)
|
|
- Expiration timeline (30/60/90 days)
|
|
- Agent fleet status (all infrastructure)
|
|
|
|
**Certificates** page filters by issuer (show me all ACME certs, or all step-ca certs):
|
|
- cert-manager certs discovered from Kubernetes nodes
|
|
- certctl-managed certs on VMs
|
|
- Network appliance certs auto-discovered
|
|
|
|
## Shared Infrastructure
|
|
|
|
If cert-manager and certctl both use the same CA:
|
|
- **ACME**: cert-manager uses ClusterIssuer + certctl uses ACME connector → same Let's Encrypt account, transparent coexistence
|
|
- **step-ca**: cert-manager uses external issuer CRD + certctl uses step-ca connector → same provisioner, shared certificate inventory
|
|
- **Vault PKI**: cert-manager uses external issuer CRD + certctl uses Vault connector → same mount, same audit trail
|
|
|
|
No conflict. They just issue certs through the same CA. certctl's discovery scanning finds cert-manager-issued certs and shows them alongside certctl-managed ones.
|
|
|
|
## Key Differences from cert-manager
|
|
|
|
| Feature | cert-manager | certctl |
|
|
|---------|--------------|---------|
|
|
| Target | In-cluster (Kubernetes) | Out-of-cluster (VMs, bare metal, appliances) |
|
|
| Configuration | CRDs (Certificate, ClusterIssuer, Issuer) | API + Dashboard (JSON REST) |
|
|
| Deployment | Injected into Secret objects, mounted by pods | Agent pulls work, deploys via target-specific API (file, service restart, proxy agent) |
|
|
| Renewal | Controller watches Certificate CRDs, triggers renewal when needed | Scheduler checks thresholds, agents poll for work |
|
|
| Audit | Kubernetes event log | Immutable append-only audit trail |
|
|
| Visibility | Per-namespace, per-resource | Fleet-wide, unified inventory |
|
|
|
|
## Future Integration
|
|
|
|
On the roadmap (V4): **cert-manager external issuer** — certctl acts as a ClusterIssuer backend for Kubernetes. This would allow cert-manager to request certificates from certctl, which could issue them via any of its connectors (step-ca, Vault, private CA, etc.). Pure integration play; no breaking changes.
|
|
|
|
For now: cert-manager handles Kubernetes, certctl handles everything else. They coexist seamlessly.
|
|
|
|
## Next Steps
|
|
|
|
1. Run through the [Quick Start](../getting-started/quickstart.md) for a 5-minute demo
|
|
2. Try the [Multi-Issuer example](../examples/multi-issuer/multi-issuer.md) — manages public and internal certs from one dashboard
|
|
3. Explore [Architecture](../reference/architecture.md#agents) for deployment patterns
|
|
4. Check the [Helm Chart](../deploy/helm/certctl/) for production Kubernetes deployment
|