docs: comprehensive V2 documentation update across all guides

Add missing V2 concepts (Certificate Profiles, Revocation with CRL/OCSP,
Short-Lived Certificates, CLI, MCP Server, Observability) to concepts guide.
Update quickstart with revocation examples, sorting/filtering, cursor pagination,
sparse fields, stats/metrics, and approval workflows. Align 5-minute demo guide
and advanced demo to full V2 feature set including revocation workflows, bulk ops,
fleet overview, and dashboard charts. Update architecture with MCP server section,
5th scheduler loop, API audit log, and 860+ test count. Add revocation-across-issuers
section to connectors guide.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Shankar
2026-03-23 19:10:57 -04:00
parent 0d58ce22bf
commit 9656c6c585
6 changed files with 355 additions and 26 deletions
+41 -9
View File
@@ -1,6 +1,6 @@
# certctl Demo Guide
A 5-7 minute guided walkthrough of certctl's dashboard and API. Perfect for stakeholder presentations and team demos.
A 5-10 minute guided walkthrough of certctl's dashboard and API. Perfect for stakeholder presentations and team demos.
New to certificates? Read the [Concepts Guide](concepts.md) first. Want a hands-on demo where you issue certificates yourself? See the [Advanced Demo](demo-advanced.md).
@@ -28,7 +28,7 @@ The main dashboard shows at a glance:
- **Active** — healthy certificates with time remaining
- **Renewal success rate** — percentage of automated renewals that succeeded
Below the stats, you'll see an **expiry timeline** showing how many certs expire in each time bucket (7/14/30/60/90 days), and a **recent activity feed** with the latest audit events.
Below the stats, interactive charts provide deeper visibility: an **expiration heatmap** (90-day weekly buckets), **renewal success rate trends** (30-day line chart), **certificate status distribution** (donut chart), and **issuance rate** (30-day bar chart).
### Certificates View
Click "Certificates" in the sidebar to see the full inventory:
@@ -57,6 +57,18 @@ Click "Agents" in the sidebar. Four agents are online, one (`iis-prod-agent`) we
**6. "What policies are enforced?"**
Click "Policies" to see the active rules: required owner metadata, allowed environments, max certificate lifetime, minimum renewal window. Check the violations list to see which certs are non-compliant.
**7. "Can I revoke a compromised cert?"**
Click any active certificate, then click the "Revoke" button. A modal appears with RFC 5280 reason codes (Key Compromise, Superseded, Cessation of Operation, etc.). After revocation, the cert shows a revocation banner with the reason and timestamp.
**8. "Show me short-lived credentials"**
Click "Short-Lived" in the sidebar. This view shows certificates with TTL under 1 hour — live countdown timers, auto-refresh every 10 seconds, and profile-based filtering. These are for service-to-service auth where rapid expiry replaces revocation.
**9. "What about bulk operations?"**
On the Certificates page, select multiple certificates using the checkboxes. A bulk action bar appears with options to trigger renewal, revoke (with reason codes), or reassign ownership — all with progress tracking.
**10. "How do I see the deployment history?"**
Click any certificate, then scroll to the deployment timeline. A visual 4-step timeline shows the lifecycle: Requested → Issued → Deploying → Active. Previous versions show a rollback button.
## API Walkthrough
The dashboard is backed by a real REST API. Try these while the demo is running:
@@ -82,6 +94,23 @@ curl -s http://localhost:8443/api/v1/policies/pr-require-owner/violations | jq .
# Check system health
curl -s http://localhost:8443/health | jq .
# Dashboard stats
curl -s http://localhost:8443/api/v1/stats/summary | jq .
# System metrics (cert totals, agent counts, job stats)
curl -s http://localhost:8443/api/v1/metrics | jq .
# Certificate profiles
curl -s http://localhost:8443/api/v1/profiles | jq .
# Agent groups
curl -s http://localhost:8443/api/v1/agent-groups | jq .
# Revoke a certificate
curl -s -X POST http://localhost:8443/api/v1/certificates/mc-api-prod/revoke \
-H "Content-Type: application/json" \
-d '{"reason": "superseded"}' | jq .
```
## Demo Without Docker
@@ -109,15 +138,18 @@ The `-v` flag removes the PostgreSQL data volume so you get a clean slate next t
If you're demoing to a team or customer, here's a suggested flow:
1. **Start with the dashboard** — "This is your certificate inventory at a glance"
1. **Start with the dashboard** — "This is your certificate inventory at a glance, with real-time charts showing expiration trends and renewal health"
2. **Show the expiring certs** — "These three would have caused outages without this platform"
3. **Click into auth-production** — "Here's the full lifecycle: who owns it, where it's deployed, when it was last renewed"
4. **Show the failed VPN cert** — "The system tried 3 times, then alerted the team via webhook"
5. **Show agents** — "Agents run on your infrastructure, handle key generation locally, and report back"
6. **Show policies** — "Guardrails prevent teams from going outside approved scope"
7. **Show the API** — "Everything you see here is API-first, so you can automate on top of it"
3. **Click into auth-production** — "Here's the full lifecycle: who owns it, where it's deployed, deployment timeline, when it was last renewed"
4. **Show revocation** — "If a key is compromised, one click revokes the cert with an RFC 5280 reason code. CRL and OCSP are served automatically"
5. **Show the failed VPN cert** — "The system tried 3 times, then alerted the team via Slack, Teams, PagerDuty, or OpsGenie"
6. **Show agents and fleet overview** — "Agents run on your infrastructure, handle key generation locally. Fleet view shows OS, architecture, and version distribution"
7. **Show profiles** — "Certificate profiles enforce crypto constraints — key types, max TTL, compliance requirements"
8. **Show policies** — "Guardrails prevent teams from going outside approved scope"
9. **Show bulk operations** — "Select multiple certs, trigger renewal or revoke in bulk with progress tracking"
10. **Show the API** — "Everything you see here is API-first. We also have a CLI tool and an MCP server for AI assistant integration"
The whole walkthrough takes 5-7 minutes.
The whole walkthrough takes 5-10 minutes.
## Next Steps