Bug 1886892
| Summary: | Need to document TLS CommonName deprecation | ||
|---|---|---|---|
| Product: | OpenShift Container Platform | Reporter: | Scott Dodson <sdodson> |
| Component: | Documentation | Assignee: | Andrea Hoffer <ahoffer> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | zhou ying <yinzhou> |
| Severity: | urgent | Docs Contact: | Vikram Goyal <vigoyal> |
| Priority: | urgent | ||
| Version: | 4.6 | CC: | ahoffer, aos-bugs, dmoessne, jokerman, mnewby, somalley |
| Target Milestone: | --- | ||
| Target Release: | 4.6.0 | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | If docs needed, set a value | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2021-01-14 20:00:45 UTC | Type: | Bug |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
| Embargoed: | |||
|
Description
Scott Dodson
2020-10-09 16:46:02 UTC
Documentation and a release note for 'oc' regarding Go 1.15 deprecation of using the CommonName field for hostname in TLS certificates is needed. 'oc' is built with Go 1.15 as of 4.6. With 'oc' commands that require TLS verification and certificates without SAN, oc will return the following golang error: "x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0" See golang's release notes linked in the description above. When encountered, a user has 2 options: 1) precede the oc command with the following "GODEBUG=x509ignoreCN=0" 2) update the certificate to one with a proper SAN This issue will arise when users are working with local or private image registries with self-signed certificates. Commands such as "oc image" or "oc adm release" "oc adm catalog" will throw the legacy CN field error if using such a registry. PR for deprecation notice and known issue entry in the release notes: https://github.com/openshift/openshift-docs/pull/26334 @ahoffer I'm not sure who owns the documentation[1] on setting up a disconnected registry, but we could improve the documentation[1][2] to either: 1) tell users to precede 'oc adm release' commands with the GODEBUG=x509ignoreCN=0 if using a self-signed certificate without SAN (as many local private registries do, if they have certificates at all) OR 2) update the setup to document how to create a certificate with SAN. This is actually tricky to do, and not well documented anywhere. I searched the internet extensively to come up with a working setup for my own local testing: https://gist.github.com/sallyom/dc168cfecfd478547cbf5e0a85fb9334 and I have no idea if it's the best/only/most efficient setup but it works for me (See note below about the docs) NOTE: These are 4.2 docs, any docs past 4.2 the registry setup is not included, only the mirroring steps. If we don't have plans to include the registry setup in our docs, we can simply mention that if using self-signed certs (simple vanilla openssl command generated, no CSRs) then users can precede the `oc adm release` commands with the `GODEBUG=x509ignoreCN=0`. Also I came across blogs instructing users to set up local registry, and these also reference the self-signed SAN-less certificate setup: https://www.openshift.com/blog/openshift-4-2-disconnected-install That will also leave users with broken registry without the GODEBUG added. [1] 4.2 - included registry setup: https://docs.openshift.com/container-platform/4.2/installing/install_config/installing-restricted-networks-preparations.html#installation-creating-mirror-registry_installing-restricted-networks-preparations [2] 4.6 - no registry setup only mirroring steps: https://docs.openshift.com/container-platform/4.6/installing/install_config/installing-restricted-networks-preparations.html#installation-creating-mirror-registry_installing-restricted-networks-preparations Hi @Sally, We only support 4.4+ docs, so I've added a note about adding setting 'GODEBUG=x509ignoreCN=0'. Can you please review and see if that's what you were looking for? Thanks! PR: https://github.com/openshift/openshift-docs/pull/27524 Preview: https://bz-1886892-update--ocpdocs.netlify.app/openshift-enterprise/latest/installing/install_config/installing-restricted-networks-preparations.html#installation-mirror-repository_installing-restricted-networks-preparations @Ying Zhou Can you please review this update to notify users to use `GODEBUG=x509ignoreCN=0` for these CLI commands if they use certs that don't set a SAN? PR: https://github.com/openshift/openshift-docs/pull/27524 Preview: https://bz-1886892-update--ocpdocs.netlify.app/openshift-enterprise/latest/installing/install_config/installing-restricted-networks-preparations.html#installation-mirror-repository_installing-restricted-networks-preparations PR has been merged. Changes will be live shortly. |