The Complete Production SOP: How to Deploy and Run cert-manager Automated Let's Encrypt TLS Provisioning in Autonomous AI Agents
Production SOP to install cert-manager Automated Let's Encrypt TLS Provisioning in Codex, Claude Code, and Cursor. Automate ACME HTTP-01/DNS-01 setups.
Technical Overview & Architectural Context
Autonomous coding agents like Codex, Claude Code, Cursor, and Windsurf frequently introduce critical misconfigurations when provisioning Kubernetes TLS infrastructure. Typical hallucination patterns include writing deprecated `certmanager.k8s.io/v1alpha1` API manifests, omitting required ACME solver ingress classes, misconfiguring Cloudflare or Route53 API token Secret references, or attempting direct ACME staging versus production endpoint cutovers without testing orders. In high-stakes production clusters, these errors trigger Let's Encrypt rate limits (5 failures per domain per hour), leading to prolonged certificate issuance blackouts and broken ingress routing. The `kubernetes-cert-manager-letsencrypt` skill eliminates these failure modes by enforcing deterministic procedural Standard Operating Procedures (SOPs). It constrains agent behavior to the official `cert-manager.io/v1` specification, mandates staged validation using Let's Encrypt staging endpoints (`https://acme-staging-v02.api.letsencrypt.org/directory`) before production promotion, and provides explicit diagnostic commands across `Certificate`, `CertificateRequest`, `Order`, and `Challenge` CRDs. By integrating this SKILL.md into your workspace, coding agents operate within secure declarative boundaries with zero unvetted shell execution traps.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into agent configuration paths.
Autonomous agent runtimes scan `.agents/skills/` or `.cursor/rules/` for domain-specific SKILL.md files. When initializing cert-manager setups, mounting the SKILL.md directly into the workspace informs the agent's contextual awareness of Let's Encrypt schema specifications, solver requirements, and debugging procedures before manifest generation begins.
mkdir -p .agents/skills/kubernetes-cert-manager-letsencrypt && curl -fsSL https://askills.dev/api/skills/kubernetes-cert-manager-letsencrypt/raw -o .agents/skills/kubernetes-cert-manager-letsencrypt/SKILL.md---
name: "kubernetes-cert-manager-letsencrypt"
description: "Automate issuance and auto-renewal of TLS certificates using cert-manager and Let's Encrypt."
metadata:
author: "cert-manager"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "setup cert-manager clusterissuer"
- "dns-01 challenge cert-manager cloudflare"
- "auto tls ingress cert-manager"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Place the SKILL.md inside workspace root `.agents/skills/` to allow seamless multi-runtime hot-reloading across Claude Code, Cursor, and Windsurf without restarting your IDE.
The skill enforces `shell_exec: false` to prevent agent runtimes from executing destructive raw `kubectl apply` commands directly without human review.
Secret Scaffolding & CRD Preflight Verification
Deploy cert-manager CRDs via Helm and mount DNS-01 provider tokens securely.
Cert-manager requires CustomResourceDefinitions installed prior to manifest reconciliation. Furthermore, DNS-01 ACME challenges require referencing Kubernetes Secret objects that contain provider tokens (e.g., Cloudflare API tokens or AWS secret keys) within the `cert-manager` namespace rather than the application namespace.
helm repo add jetstack https://charts.jetstack.io --force-update && helm upgrade --install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set crds.enabled=trueapiVersion: v1
kind: Secret
type: Opaque
metadata:
name: cloudflare-api-token-secret
namespace: cert-manager
stringData:
api-token: "${CLOUDFLARE_API_TOKEN}"Always store DNS solver credentials in the `cert-manager` namespace when using `ClusterIssuer`, as `ClusterIssuer` cannot reference secrets across arbitrary application namespaces without explicit ref grants.
Never commit plaintext Cloudflare or Route53 tokens into version control. Use environment substitution or sealed secrets before running git commits.
Intent Matching & Declarative ClusterIssuer Invocation
Prompt the agent with specific triggers to generate dual-environment Let's Encrypt ClusterIssuers.
Instruct the AI agent using exact frontmatter trigger phrases. The skill directs the agent to generate dual ClusterIssuers: a staging issuer to test verification loops without consuming production ACME rate limits, and a production issuer for final ingress annotations.
echo 'Prompting agent with trigger: setup cert-manager clusterissuer'apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
spec:
acme:
server: https://acme-staging-v02.api.letsencrypt.org/directory
email: [email protected]
privateKeySecretRef:
name: letsencrypt-staging-account-key
solvers:
- http01:
ingress:
class: nginx
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: [email protected]
privateKeySecretRef:
name: letsencrypt-prod-account-key
solvers:
- http01:
ingress:
class: nginxTarget `letsencrypt-staging` first on all new Ingress annotations. Once the secret is successfully populated, switch `cert-manager.io/cluster-issuer` to `letsencrypt-prod`.
Ensure ingress controller ingressClassName exactly matches the solver spec (e.g. `nginx`, `traefik`). Mismatched classes cause HTTP-01 challenge pods to hang.
Ingress Annotation & Challenge Lifecycle Verification
Annotate application Ingress resources and monitor the four-stage cert-manager lifecycle.
The skill guides the agent to append the required metadata annotations on the application Ingress. The agent then runs declarative status inspections across the complete cert-manager CRD hierarchy: Certificate -> CertificateRequest -> Order -> Challenge.
kubectl get certificate,certificaterequest,order,challenge -AapiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web-ingress
namespace: production
annotations:
cert-manager.io/cluster-issuer: "letsencrypt-prod"
acme.cert-manager.io/http01-edit-in-place: "false"
spec:
ingressClassName: nginx
tls:
- hosts:
- api.example.com
secretName: api-example-tls
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web-service
port:
number: 80Use `kubectl describe challenge <challenge-name>` immediately if a certificate fails to enter `Ready: True` within 120 seconds.
If using external DNS or AWS ALBs, ensure public DNS propagated before issuing certs, otherwise ACME HTTP-01 verification will fail with connection refused.
Real-World Scenario: Automating Wildcard TLS Issuance with Cloudflare DNS-01 on Kubernetes Ingress
“setup cert-manager clusterissuer using dns-01 challenge cert-manager cloudflare for *.infra.internal.net and configure the ingress to automatically provision TLS.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent attempted to use deprecated pre-v1 cert-manager syntax where solvers were defined directly under `acme.http01` instead of inside the `acme.solvers[]` list.
# Update the ClusterIssuer manifest to nest solvers under the solvers array:
spec:
acme:
solvers:
- http01:
ingress:
class: nginxRoot Cause: The API token secret referenced by `apiTokenSecretRef` in the DNS-01 solver was either placed in the incorrect namespace or contained trailing newlines.
kubectl create secret generic cloudflare-api-token-secret --namespace cert-manager --from-literal=api-token="$CLOUDFLARE_API_TOKEN" --dry-run=client -o yaml | kubectl apply -f -Frequently Asked Questions (cert-manager Automated Let's Encrypt TLS Provisioning SOP)
Q:Can I use cert-manager Automated Let's Encrypt TLS Provisioning across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres strictly to open SKILL.md metadata specifications. Placing the manifest within `.agents/skills/kubernetes-cert-manager-letsencrypt/` allows Codex Desktop, Claude Code CLI, Cursor, and Windsurf to simultaneously load rules and validation triggers.
Q:How does cert-manager Automated Let's Encrypt TLS Provisioning prevent context window overflow during long agent sessions?
Rather than feeding entire cert-manager docs or large CRD OpenAPI schemas into context, the skill supplies concise, high-density declarative patterns and exact trigger terms. This keeps context usage below 400 tokens while preventing hallucinated schema keys.
Q:Does this skill require escalated root or container permissions?
No. The skill enforces `fs_write: workspace`, `shell_exec: false`, and `net_access: false`, holding an audited security score of 98/100. It produces strictly declarative Kubernetes manifests for manual or pipeline review.
Ready to equip your autonomous agent with cert-manager Automated Let's Encrypt TLS Provisioning?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.