How to Configure cert-manager ClusterIssuer with Cloudflare API Token on Kubernetes

Introduction

Managing SSL certificates manually in Kubernetes can be time-consuming and error-prone. Using cert-manager with Cloudflare DNS-01 Challenge, you can automatically issue and renew Let’s Encrypt certificates for your applications.

This guide covers:

• Installing cert-manager
• Creating a Cloudflare API Token
• Configuring Kubernetes Secret
• Creating a ClusterIssuer
• Issuing SSL certificates automatically
• Using specific Cloudflare Zones

Prerequisites

Before starting, ensure you have:

• Kubernetes Cluster
• kubectl configured
• NGINX Ingress Controller installed
• Domain managed by Cloudflare
• cert-manager installed

Verify cert-manager:

kubectl get pods -n cert-manager

All pods should be in Running state.

Step 1: Create a Cloudflare API Token

Cloudflare recommends using API Tokens instead of the Global API Key because they provide granular permissions and improved security.

Navigate to:

Cloudflare Dashboard
→ My Profile
→ API Tokens
→ Create Token

Select:

Edit Zone DNS

Assign the following permissions:

Zone - DNS - Edit
Zone - Zone - Read

Limit access to your specific domain (recommended) or all zones.

Example:

Zone Resources:
Include → Specific Zone → example.com

Click:

Create Token

Copy and save the token securely.

Step 2: Create Kubernetes Secret

Store the Cloudflare API token inside Kubernetes.

kubectl create secret generic cloudflare-api-token-secret \
  --from-literal=api-token=YOUR_CLOUDFLARE_API_TOKEN \
  -n cert-manager

Verify:

kubectl get secret -n cert-manager

Expected:

cloudflare-api-token-secret

Step 3: Create ClusterIssuer

Create a file:

nano clusterissuer.yaml

Add:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-cloudflare
spec:
  acme:
    email: admin@example.com
    server: https://acme-v02.api.letsencrypt.org/directory

    privateKeySecretRef:
      name: letsencrypt-cloudflare

    solvers:
    - dns01:
        cloudflare:
          apiTokenSecretRef:
            name: cloudflare-api-token-secret
            key: api-token

Apply:

kubectl apply -f clusterissuer.yaml

Verify:

kubectl get clusterissuer

Expected:

letsencrypt-cloudflare   True

cert-manager supports authentication using apiTokenSecretRef, which is the recommended method for Cloudflare integrations.

Step 4: Restrict to a Specific Cloudflare Zone

If you manage multiple domains, specify which zone should use Cloudflare DNS validation.

Example:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-cloudflare
spec:
  acme:
    email: admin@example.com
    server: https://acme-v02.api.letsencrypt.org/directory

    privateKeySecretRef:
      name: letsencrypt-cloudflare

    solvers:
    - dns01:
        cloudflare:
          apiTokenSecretRef:
            name: cloudflare-api-token-secret
            key: api-token

      selector:
        dnsZones:
        - example.com

This configuration tells cert-manager to use this solver only for:

example.com
*.example.com
api.example.com
app.example.com

and other subdomains.

Step 5: Create Certificate Resource

Create:

nano certificate.yaml

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-tls
  namespace: default
spec:
  secretName: example-com-tls

  issuerRef:
    name: letsencrypt-cloudflare
    kind: ClusterIssuer

  dnsNames:
  - example.com
  - "*.example.com"

Apply:

kubectl apply -f certificate.yaml

Check status:

kubectl get certificate

Step 6: Use Certificate in Ingress

Example Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-cloudflare
spec:
  ingressClassName: nginx

  tls:
  - hosts:
    - app.example.com
    secretName: example-com-tls

  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

Apply:

kubectl apply -f ingress.yaml

Verify Certificate

Check certificate:

kubectl describe certificate example-com-tls

Check challenges:

kubectl get challenges -A

Check orders:

kubectl get orders -A

Common Errors

Error: Permission Denied

requires permission to list zones

Fix:

Ensure the Cloudflare API Token contains:

Zone - DNS - Edit
Zone - Zone - Read

These permissions are required for cert-manager to discover and update DNS records.

Error: Secret Not Found

secret cloudflare-api-token-secret not found

Verify:

kubectl get secret -n cert-manager

Error: Challenge Failed

Check logs:

kubectl logs -n cert-manager deploy/cert-manager

Conclusion

By integrating cert-manager with Cloudflare DNS-01 validation, Kubernetes can automatically issue and renew Let’s Encrypt SSL certificates without manual intervention. This approach is secure, scalable, and ideal for production environments using Cloudflare-managed DNS.

Frequently Asked Questions (FAQs)

1. Why should I use a Cloudflare API Token instead of the Global API Key?

Cloudflare API Tokens are more secure because they allow you to grant only the permissions required for DNS validation. If the token is compromised, its impact is limited to the assigned zones and permissions.

2. What permissions are required for cert-manager?

Your Cloudflare API Token should include:

Zone - DNS - Edit
Zone - Zone - Read

These permissions allow cert-manager to create and remove temporary TXT records used during the DNS-01 challenge.

3. Can I use a Global API Key instead of an API Token?

Yes, cert-manager supports both methods. However, API Tokens are strongly recommended because they follow the principle of least privilege and provide better security.

Related Articles

1. Cloudflare and Its Uses

Talk to our experts

Looking for the right technology solution for your business? Our team of experts can help you with development, cloud, DevOps, design, and a wide range of other technology needs. Get in touch with our team here.