certforge-issuer Reference

certforge-issuer is the cert-manager external issuer controller that bridges Kubernetes CertificateRequest objects to the CertForge API. It runs as a Deployment in your cluster and watches for CertificateRequest resources directed at CertForgeIssuer or CertForgeClusterIssuer objects. For installation and quick-start usage, see the cert-manager Integration guide.

cert-manager + certforge-issuer architecture — Helm install, CRDs, namespace scoping, and certificate flow

Version compatibility

certforge-issuer	cert-manager	Kubernetes	CertForge API	Notes
v0.3.x	v1.14+	1.27+	v1	mTLS client certificate auth (`mtlsSecretRef`)
v0.2.x	v1.14+	1.27+	v1	Workload Identity, denial propagation fix
v0.1.x	v1.14+	1.24+	v1	Initial release

Always use the latest patch release. Run helm search repo certforge-issuer --versions to list available releases.

Helm chart values

Install or upgrade with helm upgrade --install:

helm upgrade --install certforge-issuer oci://ghcr.io/certforge-llc/charts/certforge-issuer \
  --namespace certforge-system \
  --create-namespace \
  --values values.yaml

Full values reference

certforge:
  # URL of your CertForge instance (required)
  url: https://app.certgov.app

  # API token — stored as a Kubernetes Secret.
  # Required when using Secret-based auth (the default).
  # Not needed when workloadIdentity.enabled=true.
  token: ""

  # Optional: default issuance profile ID applied to all requests from this issuer
  issuanceProfileID: ""

  # Optional: override the namespace where the credentials Secret is looked up
  # (CertForgeClusterIssuer only — defaults to certforge-system)
  secretNamespace: ""

tokenSecret:
  # Set true to create the Secret from certforge.token above
  create: true
  name: certforge-credentials

replicaCount: 1

image:
  repository: ghcr.io/certforge-llc/certforge-issuer
  tag: ""        # defaults to chart appVersion
  pullPolicy: IfNotPresent

resources:
  requests:
    cpu: 10m
    memory: 32Mi
  limits:
    cpu: 100m
    memory: 64Mi

# Leader election — recommended when running multiple replicas
leaderElect: true

# Workload Identity — authenticate using projected ServiceAccount tokens
# instead of a long-lived API key stored in a Secret. See the
# "Workload Identity" section below for full setup instructions.
workloadIdentity:
  enabled: false
  audience: "https://app.certgov.app"  # must match the CertForge WI Provider
  expirationSeconds: 3600   # kubelet rotates token before this deadline
  tokenFile: "/var/run/secrets/certforge/token"

# NetworkPolicy — restrict pod traffic to only what the controller needs.
# Requires a CNI with NetworkPolicy support (Calico, Cilium, etc.).
networkPolicy:
  enabled: false
  kubeApiServerPort: 6443   # set to 443 for managed clusters (EKS, GKE, AKS)

# ServiceMonitor — Prometheus Operator integration.
# Requires prometheus-operator or kube-prometheus-stack.
serviceMonitor:
  enabled: false
  interval: 30s
  scrapeTimeout: 10s
  # Labels required by your Prometheus Operator's selector, e.g.:
  # additionalLabels: {release: prometheus}
  additionalLabels: {}

CRD reference

CertForgeIssuer

Namespaced resource. Issues certificates only for CertificateRequest objects in the same namespace. Exactly one of authSecretRef, workloadIdentity, or mtlsSecretRef must be set.

apiVersion: certforge.io/v1alpha1
kind: CertForgeIssuer
metadata:
  name: certforge
  namespace: default
spec:
  # URL of the CertForge instance (required)
  url: https://app.certgov.app

  # Option A: Secret-based auth (long-lived token)
  # Secret must be in the same namespace as this issuer.
  authSecretRef:
    name: certforge-credentials

  # Option B: Workload Identity (short-lived projected ServiceAccount token)
  # workloadIdentity:
  #   audience: https://app.certgov.app
  #   tokenFile: /var/run/secrets/certforge/token   # optional, this is the default

  # Option C: mTLS client certificate (recommended for direct, low-latency connections)
  # Secret holds client.crt, client.key, server.crt — created by certforge-issuer-enroll.
  # Connects directly to the CertForge agent endpoint, bypassing Cloudflare.
  # The agent host/port are set as Helm values (certforge.mtlsHost / certforge.mtlsPort),
  # not as fields on the issuer CR.
  # mtlsSecretRef:
  #   name: certforge-mtls

  # Optional: default issuance profile ID for requests handled by this issuer
  issuanceProfileID: ""

Status conditions:

Condition	Status	Meaning
`Ready`	`True`	Issuer connected to CertForge and ready to sign
`Ready`	`False`	Cannot reach CertForge — check URL, token, and network

kubectl get certforgeissuer certforge -n default -o yaml

CertForgeClusterIssuer

Cluster-scoped resource. Issues certificates for CertificateRequest objects in any namespace. When using Secret-based auth, the Secret must be in the certforge-system namespace (or secretNamespace if overridden).

apiVersion: certforge.io/v1alpha1
kind: CertForgeClusterIssuer
metadata:
  name: certforge
spec:
  url: https://app.certgov.app

  # Option A: Secret-based auth
  # Secret must be in certforge-system (or secretNamespace)
  authSecretRef:
    name: certforge-credentials

  # Option B: Workload Identity (no Secret needed)
  # workloadIdentity:
  #   audience: https://app.certgov.app

  # Option C: mTLS client certificate
  # Secret must be in certforge-system (or secretNamespace)
  # Agent host/port (certforge.mtlsHost / certforge.mtlsPort) are Helm values, not CR fields.
  # mtlsSecretRef:
  #   name: certforge-mtls

  # Optional
  issuanceProfileID: ""
  secretNamespace: ""      # CertForgeClusterIssuer only

kubectl get certforgeclusterissuer certforge -o yaml

Authentication

Secret-based (default)

The controller reads a long-lived API token from a Kubernetes Secret. Create the token under Settings → API Keys in the CertForge dashboard (needs read and enroll scopes).

# Create
kubectl create secret generic certforge-credentials \
  --namespace certforge-system \
  --from-literal=token=<your-api-token>

# Rotate (controller re-reads on next reconcile — no restart needed)
kubectl create secret generic certforge-credentials \
  --namespace certforge-system \
  --from-literal=token=<new-api-token> \
  --dry-run=client -o yaml | kubectl apply -f -

For CertForgeIssuer (namespaced), create the Secret in the issuer’s namespace:

kubectl create secret generic certforge-credentials \
  --namespace default \
  --from-literal=token=<your-api-token>

Workload Identity (recommended for production)

Workload Identity lets the controller authenticate using a short-lived projected ServiceAccount token instead of a long-lived API key. The kubelet writes and rotates the token automatically — no Kubernetes Secret is required. How it works:

The Helm chart adds a projected serviceAccountToken volume to the controller pod.
The kubelet writes a signed OIDC JWT to /var/run/secrets/certforge/token, bound to the configured audience.
The controller re-reads this file on every API call — token rotation is fully transparent.
CertForge validates the JWT against the cluster’s OIDC JWKS endpoint and grants the permissions configured in the matching Workload Identity Provider.

Step 1 — Find your cluster’s OIDC issuer URL:

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

Cluster type	Typical issuer URL
EKS	`https://oidc.eks.<region>.amazonaws.com/id/<cluster-id>`
GKE	`https://container.googleapis.com/v1/projects/<p>/locations/<l>/clusters/<c>`
AKS	`https://<uuid>.hcp.<region>.azmk8s.io`
kubeadm / kind	`https://kubernetes.default.svc`

Step 2 — Configure a Workload Identity Provider in CertForge: Go to Settings → Workload Identity → Add Provider:

Field	Value
Name	`certforge-issuer (production)`
OIDC Issuer URL	Paste the URL from Step 1
Audience	`https://app.certgov.app` (or your EU URL)
Allowed Subjects	`system:serviceaccount:certforge-system:certforge-issuer`
Scopes	`read`, `enroll`

Use an exact subject for production. The system:serviceaccount:certforge-system:certforge-issuer format identifies the precise ServiceAccount — no other workload can impersonate it. Trailing * wildcards are supported (e.g. system:serviceaccount:certforge-system:*) but should only be used in dev/staging environments.

Step 3 — Install or upgrade with workload identity enabled:

helm upgrade --install certforge-issuer oci://ghcr.io/certforge-llc/charts/certforge-issuer \
  --namespace certforge-system \
  --create-namespace \
  --set certforge.url=https://app.certgov.app \
  --set tokenSecret.create=false \
  --set workloadIdentity.enabled=true \
  --set workloadIdentity.audience=https://app.certgov.app

Step 4 — Update your issuer spec (omit authSecretRef):

apiVersion: certforge.io/v1alpha1
kind: CertForgeClusterIssuer
metadata:
  name: certforge
spec:
  url: https://app.certgov.app
  workloadIdentity:
    audience: https://app.certgov.app

Step 5 — Verify:

# Issuer should reach Ready=True without a Secret
kubectl get certforgeclusterissuer certforge -o jsonpath='{.status.conditions[?(@.type=="Ready")].message}'
# Expected: "Credentials verified, connected to https://app.certgov.app"

# Confirm no Secret is referenced
kubectl get certforgeclusterissuer certforge -o jsonpath='{.spec.authSecretRef}' # should be empty

Migrating from Secret-based auth:

Add the Workload Identity Provider in CertForge (Step 2 above).
Upgrade the Helm chart with workloadIdentity.enabled=true and tokenSecret.create=false.
Update the issuer spec to use workloadIdentity instead of authSecretRef.
Once Ready=True is confirmed, delete the old Secret.

kubectl delete secret certforge-credentials --namespace certforge-system

mTLS client certificate (v0.3.x+)

Authenticate the issuer controller using a mutual-TLS client certificate issued by CertForge. This connects directly to the CertForge agent endpoint on port 8443, bypassing Cloudflare — the same mechanism used by the connector and discovery agents. Step 1 — Install the enroll helper on a host that can reach your cluster:

# Linux
curl -LO https://github.com/CertForge-LLC/certforge-issuer/releases/latest/download/certforge-issuer-enroll-linux-amd64
chmod +x certforge-issuer-enroll-linux-amd64
sudo mv certforge-issuer-enroll-linux-amd64 /usr/local/bin/certforge-issuer-enroll

Step 2 — Generate an enrollment token in CertForge:

Go to Integrations → Connector Agents
Click + Enroll Agent and choose type Issuer
Give it a label (e.g. prod-cluster)
Copy the one-time token

Step 3 — Enroll and write credentials directly to a Kubernetes Secret:

certforge-issuer-enroll \
  --token      <one-time-token>          \
  --url        https://app.certgov.app   \
  --label      prod-cluster              \
  --secret     certforge-mtls            \
  --namespace  certforge-system

This creates (or replaces) a Kubernetes Secret named certforge-mtls in certforge-system containing:

Key	Contents
`client.crt`	Client certificate — identifies this cluster’s issuer to CertForge
`client.key`	Client private key
`server.crt`	Pinned CertForge agent CA certificate

Step 4 — Install or upgrade the Helm chart pointing at the Secret:

helm upgrade --install certforge-issuer oci://ghcr.io/certforge-llc/charts/certforge-issuer \
  --namespace certforge-system \
  --create-namespace \
  --set certforge.url=https://app.certgov.app \
  --set tokenSecret.create=false \
  --set certforge.mtlsSecretRef=certforge-mtls \
  --set certforge.mtlsHost=usagent.certgov.app \
  --set certforge.mtlsPort=8443

Step 5 — Update your issuer spec:

apiVersion: certforge.io/v1alpha1
kind: CertForgeClusterIssuer
metadata:
  name: certforge
spec:
  url: https://app.certgov.app
  mtlsSecretRef:
    name: certforge-mtls

The agent host and port (certforge.mtlsHost, certforge.mtlsPort) are Helm chart values configured at the controller level — not fields on the issuer CR. Pass them during helm install or helm upgrade with --set certforge.mtlsHost=usagent.certgov.app --set certforge.mtlsPort=8443.

Step 6 — Verify:

kubectl get certforgeclusterissuer certforge -o jsonpath='{.status.conditions[?(@.type=="Ready")].message}'
# Expected: "mTLS credentials verified, connected to ..."

mTLS certificate rotation: The client certificate has a fixed validity period. Re-run certforge-issuer-enroll with the same --secret and --label to issue a fresh credential set — the controller re-reads the Secret on the next reconcile without a restart. To revoke a certificate immediately: go to Integrations → Connector Agents, find the agent, and click Revoke Cert.

RBAC

The controller’s service account is granted the following permissions by the Helm chart:

Resource	Verbs
`certificaterequests`	get, list, watch, update, patch
`certificaterequests/status`	update, patch
`certificates`	get, patch
`signers` (certforge.io/*)	approve
`certforgeissuers`, `certforgeclusterissuers`	get, list, watch
`certforgeissuers/status`, `certforgeclusterissuers/status`	update, patch
`secrets`	get (in issuer namespaces only)
`leases`	get, list, watch, create, update, patch, delete (certforge-system only)

No cluster-wide Secret read access is granted.

Security hardening

NetworkPolicy

Restrict the controller pod to only the traffic it actually needs. Enable with networkPolicy.enabled=true in your values. Requires a CNI with NetworkPolicy support (Calico, Cilium, etc.). When enabled, the policy allows:

Direction	Ports	Purpose
Egress	UDP/TCP 53	DNS resolution
Egress	TCP 443	Kubernetes API server (managed clusters) + CertForge API (Secret-based / WI auth)
Egress	TCP 8443	CertForge agent endpoint (mTLS auth — `usagent.certgov.app`)
Egress	TCP `kubeApiServerPort` (default 6443)	Kubernetes API server (kubeadm clusters)
Ingress	TCP 8080	Prometheus metrics scrape
Ingress	TCP 8081	Kubelet health probes

networkPolicy:
  enabled: true
  kubeApiServerPort: 443   # for EKS/GKE/AKS; keep 6443 for kubeadm

Prometheus metrics

Enable a ServiceMonitor for Prometheus Operator integration:

serviceMonitor:
  enabled: true
  interval: 30s
  scrapeTimeout: 10s
  additionalLabels:
    release: prometheus   # match your Prometheus Operator's selector

The controller exposes standard controller-runtime metrics on :8080/metrics.

Controller logs

The controller writes structured JSON logs:

kubectl logs -n certforge-system deployment/certforge-issuer -f

Common log entries:

Message	Meaning
`issuer ready`	Controller connected to CertForge; issuer marked Ready
`submitted to CertForge`	CSR sent; waiting for approval
`certificate issued`	CertForge issued the cert; written to CertificateRequest
`request pending approval`	In the human-approval queue — check the CertForge dashboard
`certificate request denied by CertForge approver`	Approver rejected; CR marked Denied (terminal)
`CertForge ping failed`	Auth or connectivity failure; issuer set to Ready=False and retried in 30s
`propagating denial from sibling CertificateRequest`	cert-manager retry blocked — previous request was denied

Upgrading

helm upgrade certforge-issuer oci://ghcr.io/certforge-llc/charts/certforge-issuer \
  --namespace certforge-system \
  --reuse-values

The controller performs a rolling update. In-flight certificate requests are not lost — the controller picks up any pending request IDs from CertificateRequest annotations on restart.

v0.2.x → v0.3.x

Adds mtlsSecretRef field to both issuer kinds and mtlsHost / mtlsPort Helm chart values for the controller. Existing authSecretRef- and workloadIdentity-based issuers continue to work without changes.

v0.1.x → v0.2.x

authSecretRef is now an optional pointer field (previously required). Existing authSecretRef-based issuers continue to work without changes. The new workloadIdentity field is the alternative.

High availability

replicaCount: 2
leaderElect: true

Only one replica processes requests at a time; the others stand by. All replicas must reach the CertForge API. The leader election lease lives in certforge-system.

Uninstall

helm uninstall certforge-issuer --namespace certforge-system
kubectl delete namespace certforge-system
# Remove CRDs only if you no longer need them
kubectl delete crd certforgeissuers.certforge.io certforgeclusterissuers.certforge.io

Uninstalling does not delete CertificateRequest objects or Kubernetes Secrets containing issued certificates — those remain intact.

​Version compatibility

​Helm chart values

​Full values reference

​CRD reference

​CertForgeIssuer

​CertForgeClusterIssuer

​Authentication

​Secret-based (default)

​Workload Identity (recommended for production)

​mTLS client certificate (v0.3.x+)

​RBAC

​Security hardening

​NetworkPolicy

​Prometheus metrics

​Controller logs

​Upgrading

​v0.2.x → v0.3.x

​v0.1.x → v0.2.x

​High availability

​Uninstall

Version compatibility

Helm chart values

Full values reference

CRD reference

CertForgeIssuer

CertForgeClusterIssuer

Authentication

Secret-based (default)

Workload Identity (recommended for production)

mTLS client certificate (v0.3.x+)

RBAC

Security hardening

NetworkPolicy

Prometheus metrics

Controller logs

Upgrading

v0.2.x → v0.3.x

v0.1.x → v0.2.x

High availability

Uninstall