Skip to content

Document the ingress-nginx default certificate override #1328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rberrelleza wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Document the ingress-nginx default certificate override #1328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4fe965f
Document the ingress-nginx default certificate override
rberrelleza Aug 13, 2026
546c7e6
Correct the described failure mode
rberrelleza Aug 13, 2026
b7d880a
Add the DNS-01 ClusterIssuer to the cert-manager page
rberrelleza Aug 14, 2026
735c89f
Revert "Add the DNS-01 ClusterIssuer to the cert-manager page"
rberrelleza Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions src/content/self-hosted/helm-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1358,6 +1358,10 @@ wildcardCertificate:
key: "ca.crt"
```

:::note
Setting `create: false` is not enough on its own to serve your own certificate. The [ingress-nginx](self-hosted/helm-configuration.mdx#ingress-nginx) ingress controller reads its default certificate from `ingress-nginx.controller.extraArgs.default-ssl-certificate`, which is not derived from `wildcardCertificate.name`. Whenever you set `create: false`, point that argument at the same secret, as shown in [configure your wildcard certificate](self-hosted/install/certificates/index.mdx). Otherwise that secret no longer exists, the ingress controller falls back to its own built-in fake certificate, and browsers show a certificate warning.
:::

## Dependencies

Okteto will automatically install two instances of [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) as part of the default installation, using its official [Helm chart](https://kubernetes.github.io/ingress-nginx).
Expand Down
21 changes: 21 additions & 0 deletions src/content/self-hosted/install/certificates/cert-manager.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,27 @@ The Okteto community maintains guides on using cert-manager with different cloud
- [Google Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-google-cloud-dns/274/2)
- [Azure Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-azure-cloud-dns/275/2)

## Configure Okteto to use your certificate

@ifbyol ifbyol Aug 14, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 rberrelleza Aug 15, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ifbyol Aug 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 rberrelleza Aug 15, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ifbyol Aug 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Each guide creates a cert-manager `Certificate` that stores the issued certificate in a secret named `okteto-letsencrypt`. Once cert-manager has issued it, add the following to your Helm configuration file to tell Okteto and NGINX to use your certificate:

```yaml title="config.yaml"
wildcardCertificate:
create: false
name: okteto-letsencrypt

ingress-nginx:
controller:
extraArgs:
default-ssl-certificate: $(POD_NAMESPACE)/okteto-letsencrypt
```

:::warning
Both settings are required. `wildcardCertificate.create: false` stops Okteto from generating its self-signed certificate, which also removes the secret that `default-ssl-certificate` points at. If you don't update that argument as well, the ingress controller falls back to its own built-in fake certificate. This fails quietly: cert-manager reports your certificate as `Ready`, and the hosts Okteto creates ingresses for still serve it over SNI, but any request that doesn't match one of those hosts shows a certificate warning.
:::

Finally, [upgrade](self-hosted/manage/upgrade.mdx) your Okteto installation for the new configuration to be applied.

This video tutorial walks through configuring certificates for Okteto using cert-manager and Let's Encrypt:

<figure class="video_container">
Expand Down
4 changes: 4 additions & 0 deletions versioned_docs/version-1.47/self-hosted/helm-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1358,6 +1358,10 @@ wildcardCertificate:
key: "ca.crt"
```

:::note
Setting `create: false` is not enough on its own to serve your own certificate. The [ingress-nginx](self-hosted/helm-configuration.mdx#ingress-nginx) ingress controller reads its default certificate from `ingress-nginx.controller.extraArgs.default-ssl-certificate`, which is not derived from `wildcardCertificate.name`. Whenever you set `create: false`, point that argument at the same secret, as shown in [configure your wildcard certificate](self-hosted/install/certificates/index.mdx). Otherwise that secret no longer exists, the ingress controller falls back to its own built-in fake certificate, and browsers show a certificate warning.
:::

## Dependencies

Okteto will automatically install two instances of [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) as part of the default installation, using its official [Helm chart](https://kubernetes.github.io/ingress-nginx).
Expand Down
21 changes: 21 additions & 0 deletions versioned_docs/version-1.47/self-hosted/install/certificates/cert-manager.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,27 @@ The Okteto community maintains guides on using cert-manager with different cloud
- [Google Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-google-cloud-dns/274/2)
- [Azure Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-azure-cloud-dns/275/2)

## Configure Okteto to use your certificate

Each guide creates a cert-manager `Certificate` that stores the issued certificate in a secret named `okteto-letsencrypt`. Once cert-manager has issued it, add the following to your Helm configuration file to tell Okteto and NGINX to use your certificate:

```yaml title="config.yaml"
wildcardCertificate:
create: false
name: okteto-letsencrypt

ingress-nginx:
controller:
extraArgs:
default-ssl-certificate: $(POD_NAMESPACE)/okteto-letsencrypt
```

:::warning
Both settings are required. `wildcardCertificate.create: false` stops Okteto from generating its self-signed certificate, which also removes the secret that `default-ssl-certificate` points at. If you don't update that argument as well, the ingress controller falls back to its own built-in fake certificate. This fails quietly: cert-manager reports your certificate as `Ready`, and the hosts Okteto creates ingresses for still serve it over SNI, but any request that doesn't match one of those hosts shows a certificate warning.
:::

Finally, [upgrade](self-hosted/manage/upgrade.mdx) your Okteto installation for the new configuration to be applied.

This video tutorial walks through configuring certificates for Okteto using cert-manager and Let's Encrypt:

<figure class="video_container">
Expand Down