mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 12:41:30 +00:00
shankar0123
0729ee46e0
Post-transfer cosmetic + release-critical URL refresh after moving the
repo from github.com/shankar0123/certctl to github.com/certctl-io/certctl
(2026-05-03). GitHub HTTP redirects continue to forward old URLs forever,
so existing operators are not broken — but aligns the canonical
references with the new owner so:
- procurement engineers / contributors browsing the docs see the right
URL on first read
- operators copying the agent install one-liner hit the new path
directly without going through a redirect
- the Helm chart's default image repository points at the canonical org
registry path
- the OnboardingWizard rendered to first-run UI users shows the new
URL in the install snippets and doc anchor links
- the GitHub Actions release workflow pushes container images to
ghcr.io/certctl-io/certctl-{server,agent} (was: shankar0123)
- the release-notes Markdown body in release.yml — which gets stamped
into every future release page — references the post-transfer
cert-identity (cosign keyless signing now uses the certctl-io
workflow URL) and the post-transfer SLSA provenance source-uri.
Without this, every cosign verify / slsa-verifier command on a
v2.1.0+ release would fail because the cert-identity-regexp would
not match the signing identity GitHub Actions OIDC issues post-
transfer. Old releases (v2.0.67 and earlier) keep their immutable
release-notes pointing at the shankar0123 path and remain
verifiable via their own published instructions.
Customer impact:
- Operators on ghcr.io/shankar0123/certctl-{server,agent}:latest
silently freeze on whatever tag was current at transfer time. They
get no errors; they just stop receiving updates. The next release
notes need a one-line callout (Phase 3.1 of cowork/transfer-
certctl-to-org.md) telling them to update their image path to
ghcr.io/certctl-io/certctl-{server,agent}.
- All other URLs (git clone, install one-liner, raw.githubusercontent
URLs, browser links, GitHub API) continue to resolve via permanent
HTTP redirects. The sweep is cosmetic for those.
Files swept (30 total):
.github/workflows/release.yml — IMAGE_NAMESPACE, source-uri,
cosign cert-identity-regexp, IMAGE= snippet (5 refs total).
CHANGELOG.md, README.md — anchor links, badges, install one-liner,
cosign verify snippets in operator-facing sections.
api/openapi.yaml — info / externalDocs URLs.
install-agent.sh — GITHUB_REPO const + systemd unit Documentation=
field.
deploy/ENVIRONMENTS.md, deploy/helm/{CHART_SUMMARY,INDEX,
INSTALLATION,README}.md, deploy/helm/certctl/{Chart.yaml,
README.md,values.yaml}, deploy/helm/examples/values-*.yaml —
chart docs + image repository defaults across dev / prod-ha
overrides.
docs/{certctl-for-cert-manager-users,connector-iis,connectors,
migrate-from-acmesh,migrate-from-certbot,quickstart,test-env,
why-certctl}.md — operator-facing doc URLs.
examples/{acme-nginx,acme-wildcard-dns01,multi-issuer,
private-ca-traefik,step-ca-haproxy}/docker-compose.yml +
examples/step-ca-haproxy/step-ca-haproxy.md — example image:
paths and accompanying narrative.
web/src/pages/OnboardingWizard.tsx — first-run-UI URL refs (curl
install one-liners, agent docker image path, doc anchor links).
Files intentionally NOT swept (Choice A from cowork/transfer-certctl-
to-org.md):
go.mod, go.sum — module declaration stays github.com/shankar0123/
certctl. Existing imports compile because Go uses the path
declared in go.mod, not the URL it was fetched from. Internal-
only project; no external Go consumers; rename will land as a
mechanical sed when one materializes.
~250 *.go files — every import remains github.com/shankar0123/
certctl/internal/...
deploy/test/f5-mock-icontrol/go.mod — separate test sub-module;
same Choice A logic; module path stays.
Files intentionally NOT swept (other reasons):
README.md lines 244-245 — Scarf-pixel docker-pull commands.
shankar0123.docker.scarf.sh/... is a Scarf-account hostname
(per-user, not per-repo) and the pixel keeps tracking pulls
against the operator's personal Scarf account. Migrating to a
certctl-io Scarf account is a separate decision (create org
Scarf account → re-create package → update README).
deploy/test/f5-mock-icontrol/f5-mock-icontrol — checked-in
compiled binary with shankar0123/certctl baked into Go build
info via the sub-module path. Out of scope for a URL sweep;
will refresh on the next `make test-integration` rebuild.
Verification:
gofmt: clean (no .go files touched).
go vet ./...: clean (verified at this SHA in 1.3 of the transfer
checklist; no .go changes since).
go build ./...: clean (same).
go test -short on representative packages: green (same).
Diff shape: 30 files, 74 insertions / 74 deletions, net-zero size,
pure URL substitution.
146 lines
6.9 KiB
Markdown
146 lines
6.9 KiB
Markdown
# certctl for cert-manager Users
|
|
|
|
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 compliance 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](./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](./architecture.md#agents) for deployment patterns
|
|
4. Check the [Helm Chart](../deploy/helm/certctl/) for production Kubernetes deployment
|