k8s-agent-skills 1.2.0

package/README.md

@@ -0,0 +1,102 @@
+# k8s-agent-skills
+
+Agent skills for Kubernetes cluster operations tooling. Each skill is a self-contained `SKILL.md` designed for agentic AI tools (Claude Code, OpenCode, Codex) that load skills for task-specific expertise.
+
+**Mirror:** [github.com/Aidas-dev/k8s-agent-skills](https://github.com/Aidas-dev/k8s-agent-skills)
+
+## Skills
+
+| Skill | What it covers | CRDs |
+|-------|---------------|------|
+| [atlas](skills/atlas/SKILL.md) | Atlas Operator — DB schema migrations, lint, policies | AtlasSchema, AtlasMigration |
+| [cert-manager](skills/cert-manager/SKILL.md) | TLS cert provisioning, ACME, Issuers, Gateway integration | Certificate, Issuer, ClusterIssuer |
+| [cilium-gateway](skills/cilium-gateway/SKILL.md) | Gateway API, TLS, traffic splitting, oauth2-proxy, hostNetwork | GatewayClass, Gateway, HTTPRoute, etc. |
+| [cilium-network](skills/cilium-network/SKILL.md) | Cilium CNI, network policies, LB IPAM, encryption, Hubble | CiliumNetworkPolicy, CiliumCIDRGroup, etc. |
+| [cnpg](skills/cnpg/SKILL.md) | CloudNativePG — PostgreSQL clusters, backups, poolers | Cluster, Backup, ScheduledBackup, Pooler |
+| [dragonfly](skills/dragonfly/SKILL.md) | DragonflyDB — Redis-compatible operator, replication, TLS | Dragonfly |
+| [external-dns](skills/external-dns/SKILL.md) | DNS sync — Cloudflare, Route53, Gateway API, sources, registry | None |
+| [flagger](skills/flagger/SKILL.md) | Progressive delivery, canary, A/B, blue/green | Canary, MetricTemplate, AlertProvider |
+| [flux](skills/flux/SKILL.md) | Flux CD router — debugging, CRDs, repo audit | Router → sub-skills |
+| [gitea](skills/gitea/SKILL.md) | Gitea router — API, runner, registry, webhooks, tea CLI | Router → sub-skills |
+| [gitea-api](skills/gitea-api/SKILL.md) | Gitea REST API — auth, repos, issues, PRs, packages | None |
+| [gitea-registry](skills/gitea-registry/SKILL.md) | Gitea container registry — OCI, multi-arch, push/pull | None |
+| [gitea-runner](skills/gitea-runner/SKILL.md) | Gitea Actions runners — registration, host-mode, ephemeral | None |
+| [gitea-tea](skills/gitea-tea/SKILL.md) | tea CLI — commands, auth, actions, webhooks, admin | None |
+| [gitea-webhooks](skills/gitea-webhooks/SKILL.md) | Gitea webhooks — events, HMAC, org vs repo hooks | None |
+| [harbor](skills/harbor/SKILL.md) | Harbor router — API, Helm, Terraform | Router → sub-skills |
+| [harbor-api](skills/harbor-api/SKILL.md) | Harbor REST API v2 — projects, artifacts, robots, replication, GC, OIDC | None |
+| [harbor-helm](skills/harbor-helm/SKILL.md) | Harbor Helm chart — production deploy, external DB/Redis/S3, Trivy | None |
+| [harbor-terraform](skills/harbor-terraform/SKILL.md) | Harbor Terraform provider — 20 resources, 8 data sources | None |
+| [higress](skills/higress/SKILL.md) | Higress router — CRDs, Wasm plugins, AI Gateway, Helm | Router → sub-skills |
+| [higress-helm](skills/higress-helm/SKILL.md) | Higress Helm chart — core/console/redis/plugin-server/o11y | None |
+| [higress-operator](skills/higress-operator/SKILL.md) | Higress CRDs — WasmPlugin, Http2Rpc, McpBridge, 41 Wasm plugins, 16 AI providers | WasmPlugin, Http2Rpc, McpBridge |
+| [kserve](skills/kserve/SKILL.md) | KServe router — CRDs, Helm, deployment modes | Router → sub-skills |
+| [kserve-helm](skills/kserve-helm/SKILL.md) | KServe Helm — 10 charts, Serverless/Raw/ModelMesh modes | None |
+| [kserve-operator](skills/kserve-operator/SKILL.md) | KServe CRDs — InferenceService, ServingRuntime, InferenceGraph, LLMInferenceService, LocalModel | 22 CRDs under serving.kserve.io |
+| [kubeflow](skills/kubeflow/SKILL.md) | Kubeflow router — Trainer v2, Pipelines v2, Training Operator v1 | Router → sub-skills |
+| [kubeflow-pipelines](skills/kubeflow-pipelines/SKILL.md) | KFP v2 SDK — DSL, IR YAML, control flow, Kubernetes Native API | PipelineRun (v2beta1) |
+| [kubeflow-trainer](skills/kubeflow-trainer/SKILL.md) | Kubeflow Trainer v2.2 — TrainJob, TrainingRuntime, 5 ML policies | TrainJob, TrainingRuntime, ClusterTrainingRuntime |
+| [kubeflow-training-operator](skills/kubeflow-training-operator/SKILL.md) | Legacy v1 — PyTorchJob, TFJob, MPIJob, XGBoostJob | PyTorchJob, TFJob, MPIJob, XGBoostJob |
+| [mariadb](skills/mariadb/SKILL.md) | MariaDB router — operator CRDs, Helm | Router → sub-skills |
+| [mariadb-helm](skills/mariadb-helm/SKILL.md) | MariaDB operator Helm — 3 charts, production HA values | None |
+| [mariadb-operator](skills/mariadb-operator/SKILL.md) | MariaDB operator — 12 CRDs, Galera HA, MaxScale, backups, PITR | 12 CRDs under k8s.mariadb.com |
+| [nvidia-device-plugin](skills/nvidia-device-plugin/SKILL.md) | GPU discovery, GFD, NFD, CDI, MIG, time-slicing | None (ConfigMap) |
+| [rook-ceph-operator](skills/rook-ceph-operator/SKILL.md) | Ceph cluster, block pools, object store, NFS, CSI | CephCluster, CephBlockPool, CephObjectStore, etc. |
+| [rook-ceph-toolbox](skills/rook-ceph-toolbox/SKILL.md) | Ceph CLI — health, OSD mgmt, RBD, RGW, CRUSH | None (toolbox ops) |
+| [sealed-secrets](skills/sealed-secrets/SKILL.md) | Encrypted Secrets for GitOps, kubeseal, key rotation | SealedSecret |
+| [stakater-reloader](skills/stakater-reloader/SKILL.md) | ConfigMap/Secret reload, annotations, Helm values | None (annotation-based) |
+| [talos](skills/talos/SKILL.md) | Talos Linux — cluster deploy, machine config, upgrades, talosctl | None |
+| [tekton](skills/tekton/SKILL.md) | Tekton pipelines — resolver refs, matrix, CEL, TTL | Task, Pipeline, etc. |
+| [vector](skills/vector/SKILL.md) | Vector router — Helm, operator CRDs | Router → sub-skills |
+| [vector-helm](skills/vector-helm/SKILL.md) | Vector Helm chart — 3 roles (Agent/Aggregator/Stateless), customConfig | None |
+| [vector-operator](skills/vector-operator/SKILL.md) | Vector operator — 5 CRDs, auto-routing by source type | Vector, VectorPipeline, ClusterVectorPipeline, VectorAggregator, ClusterVectorAggregator |
+| [victoria-metrics](skills/victoria-metrics/SKILL.md) | VM skill router — operator, queries, cardinality, logs, traces | Router |
+| [victoriametrics-operator](skills/victoriametrics-operator/SKILL.md) | VM Operator CRDs — VMAgent, VMAlert, VMServiceScrape, VLogs | 19 CRDs |
+| [zitadel](skills/zitadel/SKILL.md) | ZITADEL router — API, Helm, Terraform | Router → sub-skills |
+| [zitadel-api](skills/zitadel-api/SKILL.md) | ZITADEL API — OIDC/SAML/API apps, users, orgs, roles | None |
+| [zitadel-helm](skills/zitadel-helm/SKILL.md) | ZITADEL Helm — CNPG, Gateway API, caches, masterkey | None |
+| [zitadel-terraform](skills/zitadel-terraform/SKILL.md) | ZITADEL Terraform provider — 80+ resources, 40+ data sources | None |
+
+## Usage
+
+### Via npm (recommended)
+
+```bash
+npm install --save-dev k8s-agent-skills
+# or
+bun add -d k8s-agent-skills
+
+# Symlink skills to agent config dir
+npx skills-npm
+# → symlinks skills/ into ~/.agents/skills/
+```
+
+### Via git clone
+
+```bash
+git clone https://github.com/Aidas-dev/k8s-agent-skills.git
+ln -sf $(pwd)/k8s-agent-skills/skills/* ~/.agents/skills/
+```
+
+### Manual copy
+
+```bash
+# OpenCode / Codex
+cp -r skills/vector ~/.agents/skills/
+
+# Claude Code Desktop
+cp -r skills/external-dns ~/.claude/skills/
+```
+
+## npm Publishing
+
+The package auto-publishes to npm on push to `main` via GitHub Actions.
+
+**Setup required** (one-time):
+1. Create an npm automation token at [npmjs.com/settings/tokens](https://www.npmjs.com/settings/tokens)
+2. Add it as `NPM_TOKEN` secret in the GitHub repo settings
+3. Workflow at `.github/workflows/publish.yml` handles version bump and publish
+
+## License
+
+MIT — free to use, modify, and distribute.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "k8s-agent-skills",
+  "version": "1.2.0",
+  "private": false,
+  "description": "Agent skills for Kubernetes cluster operations — Cilium, Talos, Flux, Rook-Ceph, CNPG, Gitea, Tekton, Cert-Manager, VictoriaMetrics, ZITADEL, Harbor, Higress, KServe, Kubeflow, MariaDB, Vector, ExternalDNS, Dragonfly, Flagger, Sealed Secrets, Stakater Reloader, NVIDIA GPU, Atlas",
+  "files": [
+    "skills"
+  ],
+  "keywords": [
+    "ai-agent-skill",
+    "kubernetes",
+    "gitops",
+    "cilium",
+    "talos",
+    "flux",
+    "rook-ceph",
+    "postgresql",
+    "cnpg",
+    "gitea",
+    "tekton",
+    "cert-manager",
+    "victoriametrics",
+    "zitadel",
+    "harbor",
+    "higress",
+    "kserve",
+    "kubeflow",
+    "mariadb",
+    "vector",
+    "dragonfly",
+    "flagger",
+    "external-dns",
+    "sealed-secrets",
+    "stakater-reloader",
+    "nvidia-gpu",
+    "atlas",
+    "open-code",
+    "opencode",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Aidas",
+    "url": "https://github.com/Aidas-dev"
+  },
+  "homepage": "https://github.com/Aidas-dev/k8s-agent-skills",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aidas-dev/k8s-agent-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Aidas-dev/k8s-agent-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": true,
+    "tag": "latest"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/atlas/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: atlas
+description: Use when working with Atlas Operator on Kubernetes — creating or troubleshooting AtlasSchema or AtlasMigration resources; configuring DevDB, migration policies, credential patterns, or schema diff/lint rules.
+---
+
+# Atlas Operator
+
+## Overview
+
+Database schema management on Kubernetes via `db.atlasgo.io/v1alpha1`. Two approaches: **AtlasSchema** (declarative — define desired schema, operator diffs and applies) and **AtlasMigration** (versioned — ordered SQL scripts). Deployed via OCI Helm chart: `ghcr.io/ariga/charts/atlas-operator` (latest: 0.7.32).
+
+## CRD Reference
+
+| CRD | Approach | Use When |
+|-----|----------|----------|
+| `AtlasSchema` | Declarative | Schema should match a desired state (operator auto-diffs) |
+| `AtlasMigration` | Versioned | Need sequential migration files, rollback support, audit trail |
+
+## AtlasSchema (Declarative)
+
+```yaml
+apiVersion: db.atlasgo.io/v1alpha1
+kind: AtlasSchema
+metadata:
+  name: app-schema
+spec:
+  urlFrom:
+    secretKeyRef:
+      name: db-creds
+      key: url              # postgres://user:pass@host:5432/db?sslmode=require
+
+  schema:
+    sql: |
+      CREATE TABLE users (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        email TEXT UNIQUE NOT NULL,
+        created_at TIMESTAMPTZ DEFAULT now()
+      );
+      CREATE TABLE posts (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        user_id UUID REFERENCES users(id),
+        title TEXT NOT NULL
+      );
+
+  policy:
+    lint:
+      destructive:
+        error: true          # Block DROP COLUMN / DROP TABLE
+    diff:
+      skip:
+        - drop_column        # Skip dropping columns (compatible changes only)
+    exclude:
+      - "audit_*"           # Glob patterns to ignore
+
+  prewarmDevDB: true          # Default — ephemeral dev container for diff
+  allowCustomConfig: false    # Don't allow DB config changes via atlas
+```
+
+## AtlasMigration (Versioned)
+
+```yaml
+apiVersion: db.atlasgo.io/v1alpha1
+kind: AtlasMigration
+metadata:
+  name: app-migrations
+spec:
+  urlFrom:
+    secretKeyRef:
+      name: db-creds
+      key: url
+
+  dir:
+    configMapRef:
+      name: migration-files   # ConfigMap with SQL migration scripts
+
+  execOrder: linear           # linear | linear-skip | non-linear
+  baseline: "000000"          # Start from this version (skip earlier)
+
+  policy:
+    lint:
+      destructive:
+        error: true
+
+  prewarmDevDB: true
+  allowCustomConfig: false
+```
+
+Migration files in ConfigMap must be lexicographically ordered:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: migration-files
+data:
+  000001_init.sql: |
+    CREATE TABLE users (...);
+  000002_add_posts.sql: |
+    CREATE TABLE posts (...);
+  000003_add_indexes.sql: |
+    CREATE INDEX idx_users_email ON users(email);
+```
+
+## Credential Patterns
+
+| Pattern | Example |
+|---------|---------|
+| Connection URL in Secret | `urlFrom.secretKeyRef.key: url` |
+| Credentials struct | `credentials.host`, `.user`, `.passwordFrom`, `.database`, `.port` |
+| Extra connection parameters | `credentials.parameters: { sslmode: require }` |
+
+Use `credentials` struct when the URL is constructed from multiple Secret keys:
+
+```yaml
+spec:
+  credentials:
+    host: myhost.example.com
+    user: app
+    passwordFrom:
+      secretKeyRef:
+        name: db-creds
+        key: password
+    database: mydb
+    port: 5432
+```
+
+## Policy Configuration
+
+| Policy | Field | Effect |
+|--------|-------|--------|
+| `lint.destructive.error` | `true`/`false` | Block (true) or warn (false) on destructive changes |
+| `diff.skip` | `[drop_column, drop_index, ...]` | Operations to skip in diff (safe for roll-forward) |
+| `exclude` | `["pattern_*"]` | Glob patterns to exclude from management |
+
+## Migration Directory Sources
+
+| Source | Location | Use Case |
+|--------|----------|----------|
+| `dir.configMapRef` | ConfigMap in same namespace | Simple, no external deps |
+| `dir.local.path` | Mounted volume path | Sidecar / init container pattern |
+| `dir.remote` | Atlas Cloud URL | Team-managed schema registry |
+| Inline (`spec.schema.sql`) | Embedded in CR | Quick prototyping |
+
+## DevDB
+
+Ephemeral database used to compute diff between desired and current schema. If `devURL` not set, operator spins a temporary container. Set explicitly to reuse or for air-gapped:
+
+```yaml
+spec:
+  devURL: postgres://user:pass@dev-db-host:5432/template?sslmode=disable
+```
+
+Or via Secret: `devURLFrom.secretKeyRef`.
+
+## Common Mistakes
+
+- **`allowCustomConfig: true` without need** — allows arbitrary DB config changes; keep `false` unless you need `ALTER SYSTEM SET`
+- **No lint policy** — destructive changes silently applied; always set `lint.destructive.error: true` for production
+- **Wrong execOrder** — `non-linear` skips version ordering; use `linear` for strict migration order
+- **Missing `baseline`** — operator tries to run all migrations including already-applied ones; set `baseline` to skip
+- **ConfigMap not updated** — AtlasMigration reads migration dir once at reconcile; if ConfigMap changes, operator picks it up on next loop
+- **DevDB connection issues** — operator needs network access to a temporary or explicit devDB; ensure `prewarmDevDB: true` works in your cluster
+
+## Supported Databases
+
+MySQL, MariaDB, PostgreSQL, SQLite, SQL Server, ClickHouse, CockroachDB, TiDB, YugabyteDB.

package/skills/cert-manager/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: cert-manager
+description: Use when creating or managing cert-manager CRDs — Certificate, Issuer, ClusterIssuer, CertificateRequest. Covers ACME DNS-01/HTTP-01, self-signed, CA issuers, Gateway API integration, and common patterns.
+---
+
+# Cert-Manager CRDs
+
+Chart from `https://charts.jetstack.io` or `oci://quay.io/jetstack/charts/cert-manager`  
+Latest chart: **v1.20.2** (Apr 2026) | API: `cert-manager.io/v1`, `acme.cert-manager.io/v1`  
+CRDs: Certificate, Issuer, ClusterIssuer, CertificateRequest | ACME: Order, Challenge | Alpha: ListenerSet
+
+Install CRDs: `--set crds.enabled=true` or `installCRDs: true`
+
+## CRD Reference
+
+| CRD | API | Scope | Purpose | Key Fields |
+|-----|-----|-------|---------|------------|
+| **Issuer** | `cert-manager.io/v1` | Namespaced | Certificate authority within a namespace. ACME, self-signed, CA, Vault, Venafi. | `spec.acme`, `spec.ca`, `spec.selfSigned`, `spec.vault`, `spec.venafi` |
+| **ClusterIssuer** | `cert-manager.io/v1` | Cluster | Cluster-wide issuer — can issue certs in any namespace. Same spec as Issuer. | Same as Issuer |
+| **Certificate** | `cert-manager.io/v1` | Namespaced | Request a TLS certificate from an issuer. Creates Secret with cert+key. | `spec.secretName`, `spec.issuerRef`, `spec.dnsNames[]`, `spec.commonName`, `spec.duration`, `spec.renewBefore`, `spec.privateKey` (algorithm, size, rotationPolicy), `spec.usages[]`, `spec.subject` |
+| **CertificateRequest** | `cert-manager.io/v1` | Namespaced | Low-level CSR resource. Usually created automatically by Certificate. | `spec.issuerRef`, `spec.request` (base64 CSR), `spec.duration`, `spec.isCA` |
+
+### ACME Resources
+
+| CRD | API | Purpose |
+|-----|-----|---------|
+| **Order** | `acme.cert-manager.io/v1` | ACME order lifecycle. Created automatically by Certificate with ACME issuer. |
+| **Challenge** | `acme.cert-manager.io/v1` | ACME challenge (DNS-01, HTTP-01). Created automatically per domain in Order. |
+
+## Issuer Types
+
+| Type | Configuration | Use Case |
+|------|--------------|----------|
+| **ACME** | `spec.acme.server` + `spec.acme.solvers[]` | Let's Encrypt, ZeroSSL, Buypass |
+| **SelfSigned** | `spec.selfSigned: {}` | Internal CA bootstrap, testing |
+| **CA** | `spec.ca.secretName` | Sign with existing CA key+cert in Secret |
+| **Vault** | `spec.vault` | HashiCorp Vault PKI |
+| **Venafi** | `spec.venafi` | Venafi TPP/Cloud |
+
+## Deployed Pattern — Let's Encrypt + Cloudflare DNS-01
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-production
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: admin@example.com
+    privateKeySecretRef:
+      name: letsencrypt-production-account-key
+    solvers:
+      - dns01:
+          cloudflare:
+            apiTokenSecretRef:
+              name: cloudflare-api-token-secret
+              key: api-token
+```
+
+## Deployed Pattern — Gateway Wildcard Certificate
+
+```yaml
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: kubexa-tech-gateway
+  namespace: cilium-gateway
+spec:
+  secretName: kubexa-tech-tls
+  issuerRef:
+    name: letsencrypt-production
+    kind: ClusterIssuer
+  dnsNames:
+    - "*.kubexa.tech"
+    - "kubexa.tech"
+  duration: 168h         # 7 days
+  renewBefore: 144h      # Renew 6 days before expiry
+  privateKey:
+    algorithm: ECDSA
+    size: 256
+    rotationPolicy: Always
+  usages:
+    - server auth
+```
+
+## Deployed Pattern — Self-Signed CA + Issuer
+
+```yaml
+# 1. Self-signed root CA
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: selfsigned
+spec:
+  selfSigned: {}
+---
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: ca-root
+  namespace: cert-manager
+spec:
+  secretName: ca-root-secret
+  isCA: true
+  commonName: "cluster-ca"
+  privateKey:
+    algorithm: ECDSA
+    size: 256
+  issuerRef:
+    name: selfsigned
+    kind: ClusterIssuer
+---
+# 2. CA issuer from root
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: ca-issuer
+spec:
+  ca:
+    secretName: ca-root-secret
+```
+
+## Key Config Details
+
+```yaml
+# ACME DNS-01 solver options
+spec:
+  acme:
+    solvers:
+      - dns01:
+          cloudflare:
+            apiTokenSecretRef:    # API token (not API key)
+              name: cloudflare-token
+              key: api-token
+          # Or route53:
+          route53:
+            region: us-east-1
+            accessKeyIDSecretRef:
+              name: aws-creds
+              key: access-key-id
+            secretAccessKeySecretRef:
+              name: aws-creds
+              key: secret-access-key
+            hostedZoneID: Z123456
+          # Or Azure:
+          azureDNS:
+            subscriptionID: <id>
+            resourceGroupName: <rg>
+            hostedZoneName: example.com
+            tenantID: <tenant>
+            clientID: <client>
+            clientSecretSecretRef:
+              name: azure-creds
+              key: client-secret
+      - http01:
+          ingress:
+            class: nginx        # Ingress class for HTTP-01 solver
+```
+
+## Gateway API Integration
+
+cert-manager v1.20+ supports Gateway API for ACME HTTP-01 challenges. No `parentRefs` required (v1.20):
+
+```yaml
+spec:
+  acme:
+    solvers:
+      - http01:
+          gatewayHTTPRoute:
+            parentRefs:
+              - name: my-gateway
+                namespace: istio-system
+```
+
+## Important Fields — Certificate
+
+```yaml
+spec:
+  duration: 2160h                   # 90 days default
+  renewBefore: 720h                  # 30 days before expiry
+  privateKey:
+    algorithm: ECDSA                # ECDSA > RSA for performance
+    size: 256                       # P-256 curve
+    rotationPolicy: Never           # or "Always" to rekey on renewal
+  usages:                           # Extended Key Usage
+    - server auth
+    - client auth
+  subject:
+    organizations:
+      - MyOrg
+  emailAddresses:
+    - admin@example.com
+  keystores:                        # Create JKS/PKCS12 keystores
+    pkcs12:
+      create: true
+      passwordSecretRef:
+        name: keystore-pass
+        key: password
+```
+
+## Common Mistakes
+
+- **DNS-01 `apiTokenSecretRef` vs `apiKeySecretRef`** — Cloudflare uses API **tokens** (scoped), not API keys. Use `apiTokenSecretRef`.
+- **Certificate renewBefore > duration** — cert-manager will constantly renew. Keep `renewBefore < duration`.
+- **ClusterIssuer in wrong namespace** — ClusterIssuer is not namespaced. Certificate references it via `issuerRef.kind: ClusterIssuer`.
+- **EC key with older clients** — Some clients don't support ECDSA. Use RSA if compatibility needed: `algorithm: RSA`, `size: 2048`.
+- **DNS-01 recursive nameservers** — cert-manager needs authoritative DNS. Set `--dns01-recursive-nameservers=8.8.8.8:53,1.1.1.1:53` and `--dns01-recursive-nameservers-only` to avoid public resolver issues.
+- **ACME rate limits** — Let's Encrypt has 50 certs/week/domain for production, 5/week for staging. Use staging for testing.
+- **Secret overwrite** — cert-manager overwrites the Secret on renewal. Don't manually edit the TLS secret.
+- **dnsNames vs commonName** — SANs (`dnsNames`) are required. `commonName` is deprecated in CA/B guidelines.
+- **HTTP-01 on port 80** — cert-manager needs port 80 reachable. Behind Cilium Gateway, ensure HTTP listener exists.