Document the ingress-nginx default certificate override

[rberrelleza]

Problem

Setting wildcardCertificate.create: false alone is not enough to switch Okteto from its built-in self-signed wildcard certificate to a cert-manager / Let's Encrypt one.

The ingress-nginx controller reads its default certificate from ingress-nginx.controller.extraArgs.default-ssl-certificate, which is not derived from wildcardCertificate.name. If you only set create: false, the controller keeps serving its previous default certificate. It fails silently: cert-manager reports the certificate as Ready, but browsers still show a warning.

What the docs said

The three community guides linked from the cert-manager page already include both settings, and so does the bring your own certificate page. Two gaps remained:

• The cert-manager page has no Helm configuration of its own. It links out to the community guides and shows a video, so nothing on the page itself tells you about the override.
• The Helm configuration reference documents create ("If set to false, Okteto will not create a self-signed wildcard certificate") and name, with no mention of the ingress-nginx argument. Anyone configuring from the reference alone hits the silent failure.

Changes

• Add a "Configure Okteto to use your certificate" section to the cert-manager page with the wildcardCertificate + ingress-nginx.controller.extraArgs pair, mirroring the bring-your-own-certificate page, plus a warning that both settings are required.
• Add a note under wildcardCertificate in the Helm configuration reference.

Applied to both the next version and 1.47.

Open questions for reviewers

• The community guides were last updated between 2023-01 and 2024-10. They may be worth a refresh, or worth folding into the docs so the cert-manager page is self-contained.
• The guides' Issuer lists an http01 solver before dns01, while this page says you must use DNS01 for a wildcard. Minor, but confusing.
• A chart-side validation that fails the install when create: false and default-ssl-certificate still points at the self-signed secret would close this properly.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for okteto-docs ready!

Name	Link
🔨 Latest commit	735c89f
🔍 Latest deploy log	https://app.netlify.com/projects/okteto-docs/deploys/6a7e75fdefa31b0008959ac2
😎 Deploy Preview	https://deploy-preview-1328--okteto-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rberrelleza]

Added a Create the Issuer section. The page said a DNS01 solver was required but never showed one, so the Issuer was left entirely to the community guides — and those list an http01 solver before dns01, which can't satisfy a wildcard.

Three provider tabs (Google Cloud DNS, Route53, Azure DNS) using the Tabs/TabItem convention already used in volume-snapshots and github.mdx.

Reviewer note: the Google Cloud DNS variant is verified end to end against Let's Encrypt production (issued a wildcard, served it, ssl_verify=0). The Route53 and Azure blocks follow cert-manager's documented schema but I have not run them — worth a second pair of eyes on the credential fields.

[rberrelleza]

Reverted the Issuer section — it's going into the community guides instead, so this PR is back to just the default-ssl-certificate override (+50/-0, as originally opened). Disregard my previous comment about the provider tabs.

[ifbyol]

In all the 3 guides above we already indicate the helm setting to be used to configure your certificate in Okteto. If we are guide them to those guides, and even the new section refers to them, why do we want to add it here too? Shouldn't we keep that information only in 1 place (community guides or public documentation)

[rberrelleza]

This has been a source of constant confusion for customers. I think it's better to be explicit and repetitive rather than require customers to dig through multiple documents, especially because this is a non-trivial configuration.

[ifbyol]

But then we should consider to move all the documents. This is not solving the problem of making customers dig through multiple documents. They still need to go to those documents to know what they have to do based on the provider.

Duplicating the configuration will make that at some point, both sources could diverge, mainly because the source of them are different (they are not 2 pages within the same repository). That divergence would be more confusing that always sending them to the community post where steps and configuration are documented

[rberrelleza]

I think this helps in several ways:

1. For customers that know how to use cert-manager, they still need the okteto-specific configuration. This provides it. I think this is specific enough to live in our docs.

2. When using agents to configure, this is more effective as it reduces the hops.

3. The community guides are not maintained nor monitored by definition (it's a community resource, not a canonical source of info). in the scenario you describe I think we are more likely to update our docs vs an external resource.

I'll let you and Cody decide to merge or close.

[ifbyol]

if we think this is better, I'm ok with it, but I wouldn't assume that someone has read the okteto-community guides, like using the name okteto-letsencrypt.

I would just say that if you already have created the certificate in the cluster in a secret, you have to use the following configuration, and use a placeholder.

pinging @codyjlandstrom explicitly for review

[codyjlandstrom]

@ekline-ai Could you please give this a review?

[ekline]

EkLine Docs Agent is working on this update. You can view the progress at EkLine Editor.

[ekline]

EkLine Docs Agent review — this is in good shape. The change correctly documents that wildcardCertificate.create: false and ingress-nginx.controller.extraArgs.default-ssl-certificate must be set together, which is the actual behavior and closes a real silent-failure gap.

What holds up well

• The new cert-manager section mirrors the bring-your-own-certificate page's config block exactly, so the two certificate pages now stay parallel.
• The okteto-letsencrypt secret name and the $(POD_NAMESPACE)/okteto-letsencrypt argument match what self-hosted/manage/troubleshooting.mdx already documents, so the example is consistent across the docs.
• The warning admonition accurately describes the SNI fallback (matching hosts still served, non-matching hosts get the fake cert) rather than overstating it as a total outage.
• Internal links and anchors resolve: #ingress-nginx, install/certificates/index.mdx, and manage/upgrade.mdx all exist. Changes are applied identically to both the next version and 1.47.

One thing worth tightening (non-blocking)

• In helm-configuration.mdx, the note says "point that argument at the same secret, as shown in configure your wildcard certificate." That target is the overview/hub page — it lists the three approaches but doesn't actually show the default-ssl-certificate override. Readers following the link to see the pair won't find it there. Consider pointing to a page that shows the config (e.g. the new Configure Okteto to use your certificate section on the cert-manager page, or bring-your-own-certificate.mdx), or rewording so the link isn't promising an example the hub page doesn't contain.

Minor / optional

• The heading Configure Okteto to use your certificate is imperative; the repo's page-structure rule leans toward noun-phrase headings. It's consistent with the sibling pages' imperative headings, so this is a judgment call, not a fix.

Overall grade: A-. Accurate, consistent with existing patterns, links resolve. Only the hub-page link target above is worth a quick adjustment. Happy to push that one-line link fix if you'd like.

[ekline]

I reviewed the PR and posted my feedback as a reply comment (no file changes, since the request was a review, not a change request).

Summary

PR #1328 documents that switching Okteto to a cert-manager/Let's Encrypt certificate requires two settings together — wildcardCertificate.create: false and ingress-nginx.controller.extraArgs.default-ssl-certificate — otherwise the ingress controller silently falls back to its built-in fake certificate.

My verdict: A-. The change is accurate and well-built:

• It mirrors the existing bring-your-own-certificate.mdx config pattern exactly.
• The okteto-letsencrypt secret name matches what troubleshooting.mdx already documents.
• All internal links and anchors resolve (#ingress-nginx, index.mdx, upgrade.mdx), and the change is applied identically to both the next version and 1.47.
• The warning accurately describes the SNI fallback rather than overstating it.

One actionable nit I flagged: in helm-configuration.mdx, the note links "as shown in configure your wildcard certificate" to index.mdx — but that hub page lists the three approaches and doesn't actually show the default-ssl-certificate override. Better to link to a page that shows the config (the new cert-manager section, or bring-your-own-certificate.mdx). I offered to push that one-line fix if they want it.

Review comment: #1328 (comment)