Bug 1712525, Ingress Controller requires CA to communicate with web console

[codyhoag]

https://bugzilla.redhat.com/show_bug.cgi?id=1712525

@bergerhoffer Can you take a look at these changes and let me know what you think? Mostly, I want to make sure I got the language right. Please let me know SME/QE resources I should run this through.

Just recently, a PR that may fix this issue for 4.3 was merged: openshift/console-operator#328. If it does (still waiting for confirmation), this will only be necessary for 4.2.

Thanks!

[openshift-docs-preview-bot]

The preview will be available shortly at:

• https://ingress-cert--ocpdocs.netlify.com/

[bergerhoffer]

@codyhoag Just a few comments.

I'd suggest to have @danehans review this update, and then from the BZ it looks like @lihongan is the QE contact.

[bergerhoffer]

A procedure module shouldn't have two sets of steps like this. You could always put these steps in a note, but if it's always going to be required, then I would add these as steps 4 and 5.

[codyhoag]

This workaround is required to accomplish several other processes, so I think it makes sense to just append as steps four and five. Thanks for the tip! 😊

[bergerhoffer]

This example-ca.crt - did the user need to have created this already? Or should it be tls.crt like earlier in the procedure refers to? Or should it be a replaceable value that we tell the user to replace?

[codyhoag]

Yes; that should've been created already. I skipped the creation process due to the listed prerequisite assuming the user already possessed a cert:

You must have a certificate/key pair in PEM-encoded files, where the certificate is signed by a trusted certificate authority and valid for the Ingress domain.

I'm now realizing that was for the TLS cert. I'll add another prerequisite for this one.

[bergerhoffer]

@codyhoag - @danehans would be the one to review this. It looks like from his comment [1] that there might be different steps depending on whether the cluster-wide proxy is already enabled or not. @danehans Can you confirm?

[1] https://bugzilla.redhat.com/show_bug.cgi?id=1712525#c40

[danehans]

Your Ingress Controller now uses the custom certificate to secure client-side connections using TLS. Some platform components (i.e. web console) use routes for communication and therefore must trust the Ingress Controller's custom certificate. This is accomplished through the trustedCA field of the Proxy resource. The trustedCA field is a reference to a ConfigMap containing the custom certificate and key pair used by the Ingress Controller.

@Miciah @bparees a Secret is used by the router and a ConfigMap is used for cluster-wide proxy. I think it would provide a better user experience if we settled on one resource type.

[bparees]

we chose a configmap for trusted CA because CAs are public information that does not need to be protected.

[danehans]

A note should be added that if proxy is already has a trustedCA reference, the existing ConfigMap should be updated ($oc edit) to include the custom certificate instead of creating a new configmap and patching proxy/cluster.

[danehans]

You may want to make make reference to $ oc get ingresscontroller/default -n openshift-ingress-operator -o yaml to verify the status of the default ingress controller after implementing the changes.

[Miciah]

This change is confusing: The current procedure explicitly states that the custom default certificate must be signed by a trusted certificate authority whereas BZ#1712525 concerns using a custom default certificate that is not signed by a trusted certificate authority (i.e., the cluster uses a custom PKI). I suggest defining a separate procedure for BZ#1712525, or else the procedure should be amended to make it clear that (a) the procedure covers both use cases, (b) the prerequisite that the certificate be signed by a trusted certificate authority only applies to the non-custom-PKI case, and (c) the additional steps are applicable only in the custom-PKI case.

@danehans, am I missing something?

[Miciah]

Thinking about it further, I wonder whether there should be a separate module completely apart from ingress for using the proxy config trustedCA setting to configure a custom PKI, in which case the prerequisite for the procedure in this module could be amended along the following lines (additions in italics): "You must have a certificate/key pair in PEM-encoded files, where the certificate is signed by a public trusted certificate authority or by a private trusted certificate authority that you have configured as described in the module "Configuring a Custom PKI" and the certificate is valid for the Ingress domain."

[codyhoag]

Hey @Miciah; there has been some confusion on my part for the first pass of this doc change. Your comments have surfaced some misconceptions I had in my original understanding.

It seems all the headaches are around this prereq snippet:

...where the certificate is signed by a trusted certificate authority and valid for the Ingress domain.

Users are coming in with their custom certificates, but they're not "trusted" from the Ingress domain's perspective. Does that accurately capture the overarching problem here?

So we should make it clear that the custom cert must either be signed by a trusted public CA (current prereq's assumption) or by a private trusted CA (scenario that BZ#1712525 is highlighting).

Can you confirm? Thanks!

[Miciah]

Users are coming in with their custom certificates, but they're not "trusted" from the Ingress domain's perspective. Does that accurately capture the overarching problem here?

That's about right: The custom certificates are not signed by a CA recognized by the console or other components running in the cluster. The ingress controller will blithely serve up the custom certificates, but when the console connects to the ingress controller, the console will complain that it does not trust the certificate since it does not recognize the signer.

So we should make it clear that the custom cert must either be signed by a trusted public CA (current prereq's assumption) or by a private trusted CA (scenario that BZ#1712525 is highlighting).

Can you confirm? Thanks!

Correct. The proxy trustedCA configuration is a way of telling everything running inside the cluster (or at least everything that looks at the proxy config), "You can trust certificates signed by this CA." The administrator can tell the ingress controller to use a certificate that has been signed by that CA, and then when the console connects to the ingress controller, it gets the custom certificate and sees that it has been signed by the trusted CA, and everything works.

[codyhoag]

Got it! Thanks for breaking that down for me @Miciah .

I agree with your proposed course of action. Here's what I'll plan to do:

1. Update the section's first prerequisite to the text your offered (i.e., include public AND private CA cert configuration options).

2. Note the possible issues with private CA certs and link to a separate module for configuring a custom PKI.

This abstracts away the CA signing options and only focuses on what the section is meant for: setting a certificate for the Ingress Controller.

Thanks again!

[codyhoag]

Finishing up another draft of this info. Since the decision was made to cover this topic more generically (Proxy API coverage for configuring privately signed certs cluster-wide), I'm closing this PR and will create a new one with the updated content.

[codyhoag]

Resent #18207