I spent two days chasing a cert-manager error that looked like it was coming from the future. The message was clean: Error: failed to solve challenge: failed to update DNS record: 403 Forbidden. I had followed the docs, created the API token, set up the ClusterIssuer, and even double-checked the zone. But the error wouldn’t go away. Turns out, the token didn’t have the right scope, and I had no idea. That’s the kind of thing that happens when you skip the part of the documentation that says "make sure your token has these exact permissions."

If you’re running Kubernetes on bare metal, in a homelab, or in a production environment, you need TLS. You need it for ingress, for internal services, for anything exposed to the internet. cert-manager is the go-to tool for this, and Cloudflare is the go-to DNS provider for a lot of us. But the setup isn’t as straightforward as the docs make it look. I’m going to walk through what I tried first, what actually worked, and why it matters.

I’m not here to sell you on cert-manager or Cloudflare. I’m here to tell you what I did when I tried to make TLS work for everything in my cluster , and what I had to fix when it didn’t.

What I Tried First

I started with the standard cert-manager installation, using the Helm chart. I followed the example for Cloudflare DNS-01, set up the API token, and created the ClusterIssuer. I used a Kubernetes Secret to store the token, and referenced it in the cloudflare provider block of the issuer configuration.

That’s where it went wrong.

The first error was 403 Forbidden, and I had no idea why. I checked the token’s scope again. I double-checked the zone name. I even created a new token with all the permissions I could think of. Nothing worked. The cert-manager logs just said the same thing again and again.

I tried looking for similar issues on GitHub, Stack Overflow, and the cert-manager forums. The most common answers were things like:

• "Make sure your token has the DNS:Edit scope"
• "Check that the zone name is correct"
• "Ensure that the API token is not expired"

I had done all of those. And still, it didn’t work.

Then I thought: maybe the token was created for the wrong zone. I went to the Cloudflare dashboard, created a new token for the exact zone name I was using. I gave it Zone:Read and DNS:Edit permissions, and then I re-deployed the ClusterIssuer.

Still nothing.

It was at this point that I realized the issue wasn’t the token or the zone , it was the email field in the provider configuration. I had used the same email that I used to register the domain. But cert-manager requires a Cloudflare account email, not the email used to register the domain. That’s not something you see in the documentation, and that’s exactly the kind of thing that breaks your day.

The Actual Solution

Let’s get specific. Here’s what I ended up with:

Step 1: Create a Cloudflare API Token

Go to the Cloudflare API Tokens dashboard, and create a new token. Give it the following permissions:

• Zone:Read (for reading the zone information)
• DNS:Edit (for updating DNS records during the DNS-01 challenge)

Make sure the token is scoped to the exact zone you're using, not the entire account.

Step 2: Store the API Token in a Kubernetes Secret

Create a Kubernetes Secret to store your Cloudflare API token:

kubectl create secret generic cloudflare-api-token \
  --from-literal=api-token="your-cloudflare-api-token-here" \
  --namespace=cert-manager

Step 3: Configure cert-manager with the Cloudflare DNS-01 Provider

Here’s the complete configuration for the ClusterIssuer:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: cloudflare
spec:
  acme:
    email: "your-cloudflare-account-email@example.com"
    server: https://acme-v02.api.sandbox.cloudfla.re
    privateKeySecretRef:
      name: cloudflare-acme-account-key
    solvers:
      - selector:
          dnsZones:
            - "example.com"
        dns01:
          cloudflare:
            apiTokenSecretRef:
              name: cloudflare-api-token
              key: api-token

Make sure to replace your-cloudflare-account-email@example.com with the actual email address associated with your Cloudflare account, not the one you used to register the domain.

Step 4: Deploy a Sample Ingress to Test

Create a simple Ingress to test if cert-manager can issue a certificate:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
    cert-manager.io/cluster-issuer: "cloudflare"
spec:
  tls:
    - hosts:
        - "example.com"
      secretName: example-com-tls
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: nginx
                port:
                  number: 80

Once this is deployed, cert-manager should automatically request and issue a certificate for example.com.

Step 5: Use SealedSecrets for Secure Credential Management (Optional)

If you want to store your Cloudflare API token securely, you can use SealedSecrets. This is especially useful if you're using GitOps or want to ensure that secrets aren't stored in plain text in your version control system.

First, install SealedSecrets:

kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/latest/download/controller.yaml

Then, seal your secret:

kubeseal --cert ./sealed-secrets/public-key.pem < cloudflare-api-token.yaml > cloudflare-api-token-sealed.yaml

Apply the sealed secret:

kubectl apply -f cloudflare-api-token-sealed.yaml

And update your ClusterIssuer to reference the sealed secret:

apiTokenSecretRef:
  name: cloudflare-api-token-sealed
  key: api-token

Why It Works

cert-manager uses the ACME protocol to issue certificates. When you use the DNS-01 challenge, cert-manager needs to modify a DNS record to prove that it has control over the domain. This is where Cloudflare comes in , it allows cert-manager to temporarily update a DNS record on your behalf.

The key part here is the cloudflare provider configuration in the ClusterIssuer. It tells cert-manager how to authenticate with Cloudflare using the API token. The email field must be the email associated with the Cloudflare account, not the domain's registration email.

Cloudflare's API is rate-limited, and if you're not careful, you can hit these limits and cause certificate issuance to fail. That’s why it's important to ensure your API token has the correct scopes and that you're using the right email.

Also, cert-manager requires that the zone in the selector.dnsZones field matches the domain exactly. If you're using a wildcard, like *.example.com, make sure to include that in your configuration.

Lessons Learned

• Use the right email. The Cloudflare email is not the same as the domain's registration email. This is the first thing I missed, and it took me hours to figure out.
• Token scopes matter. If your token doesn’t have the right permissions, cert-manager can't update the DNS records. Always double-check that your token has Zone:Read and DNS:Edit permissions.
• Secure your secrets. Using SealedSecrets is a great way to keep your Cloudflare API token safe. It adds an extra layer of security and ensures that your secrets aren't exposed in your version control.
• Test everything. Don’t assume that just because the configuration looks right, it will work. Create a test Ingress and watch the cert-manager logs to see what’s happening under the hood.
• Watch for API limits. Cloudflare's API has rate limits, and if you’re issuing a lot of certificates, you could hit those limits. It’s a good idea to monitor your usage and set up alerts if needed.

I also found that cert-manager v1.13+ has stricter validation for DNS01 providers. Older versions might not show errors clearly, which can make debugging a lot harder. I ended up using v1.14.0, which had better error messages and worked more reliably with Cloudflare.

If you're using a dynamic IP setup, like with a home network or a cloud provider that assigns dynamic IPs, you’ll need to set up a DDNS update mechanism. I used a CronJob with GitOps to ensure that my Cloudflare A record was always up to date. That way, even if my IP changes, the certificate can still be issued and renewed.

I also had to deal with a bug in my Helm chart that was using an old version of cert-manager. The Helm chart I was using had a misconfigured targetRevision, which was causing the issuer to fail silently. I had to manually update the targetRevision to match the version I was using.

Final Thoughts

Automating TLS with cert-manager and Cloudflare DNS-01 is a powerful combination. It saves you from manually issuing certificates and keeps your cluster secure without the overhead of managing them by hand. But it’s not without its gotchas , and I’ve had my fair share of them.

If you're new to cert-manager or Cloudflare, I recommend starting small. Create a test Ingress, watch the logs, and make sure everything works before rolling it out to production. And if you hit a roadblock, don’t be afraid to check the cert-manager logs , they often give you the exact error you need to fix the problem.

You can also find more information on how to set up cert-manager with Cloudflare in the official documentation, or in some of the other posts on guatulabs.dev about Kubernetes and infrastructure. If you're interested in more advanced topics, like setting up a GitOps pipeline with ArgoCD or using SealedSecrets for secure credential management, those are also worth reading.

In the end, the goal is to make TLS work for everything , and that’s what cert-manager is all about.