Skip to content

gateway: document the api.<apex> certSANs precondition for the TLS-passthrough shed #4196

Closed

Description

@kvaps

Split out of the review of #3342, carried as a follow-up rather than blocking the release.

Once that change ships, a hostname answered by a TLS-passthrough listener no longer earns an HTTPS-terminate listener or a Gateway-issued certificate. For the shipped defaults that means api.<apex>, and after the shed the only certificate a client sees on that name is the kube-apiserver's own serving certificate. It must therefore carry api.<apex> in its certSANs.

This is not a new requirement in spirit: on the ingress-nginx path packages/system/cozystack-api/templates/api-ingress.yaml already sets ssl-passthrough: "true" to Service kubernetes:443, so a cluster that never enabled the Gateway integration has always needed it. What changes is that it becomes unconditional on the Gateway path too. A cluster that moved to the Gateway integration and has been served by the ACME certificate since will not have the SAN, and loses api.<apex> on upgrade.

Nothing in this repository states the requirement — I could not find it in docs/, and the e2e clusters do not meet it either (hack/e2e-container-up.sh:263 and hack/e2e-prepare-cluster.bats:239 list IP SANs only).

Asking for one line in the release note and in the packages/extra/gateway upgrade section: before upgrading, confirm the management apiserver's serving certificate carries api.<apex>; if it does not, add the SAN, or take the migration path that moves the consumer to another hostname, which the README already names as the one that costs nothing.

Activity

  1. kvaps commented on Sep 10, 2026

    @kvaps
    MemberAuthor

    Documented in #3342 at 8af986398. packages/extra/gateway/README.md now carries the check ahead of the three migration paths: once the terminate listener is gone the only certificate on api.<apex> is the management kube-apiserver's own serving certificate, so that certificate has to carry api.<apex> in its SANs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triage/needs-triageIndicates an issue needs triage by a maintainer

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions