[WIP]OSDOCS-19695: adds X.509certificate support to RCHL by ShaunaDiaz · Pull Request #111690 · openshift/openshift-docs

ShaunaDiaz · 2026-05-14T18:20:47Z

Version(s):
rhcl-docs-main
rhcl-docs.1.4

Issue:
OSDOCS-19695

Link to docs preview:
https://111690--ocpdocs-pr.netlify.app/rhcl/latest/deployment/rhcl-using-x509-crypt-id-verify.html

QE review:

QE has approved this change.

openshift-ci-robot · 2026-05-14T18:20:51Z

@ShaunaDiaz: This pull request references OSDOCS-19695 which is a valid jira issue.

Details

In response to this:

Version(s):
rhcl-docs-main
rhcl-docs.1.4

Issue:
OSDOCS-19695

Link to docs preview:

QE review:

QE has approved this change.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

ocpdocs-previewbot · 2026-05-14T18:33:52Z

🤖 Fri May 15 15:46:43 - Prow CI generated the docs preview:

https://111690--ocpdocs-pr.netlify.app/rhcl/latest/deployment/deployment.html
https://111690--ocpdocs-pr.netlify.app/rhcl/latest/deployment/rhcl-using-x509-crypt-id-verify.html

guicassolato · 2026-05-15T09:40:55Z

 [IMPORTANT]
 ====
-In a multicluster environment, for {prodname} to balance traffic by using DNS across clusters, you must specify a gateway with a shared hostname. You can define this by using an HTTPS listener with a wildcard hostname based on the root domain.
+If you require cryptographic identity verification, see "Istio: EnvoyFilter configuration" for a Gateway object example to use instead of this default.


Did you mean "Using X.509 cryptographic identity verification" instead of "Istio: EnvoyFilter configuration" perhaps?

guicassolato · 2026-05-15T09:45:26Z

+
+//Q: would we create this filter manually on OpenShift, or just use the Gateway or AuthPolicy?
+
+Create an EnvoyFilter to configure Envoy's DownstreamTlsContext for client certificate validation:


We're missing a step before this one: mounting the CA cert from the ConfigMap into the gateway pods: https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/user-guides/auth/x509-tier2-provider-specific.md#step-4-mount-ca-certificate-into-gateway-pods

guicassolato · 2026-05-15T09:46:48Z

+$ oc apply -f
+----
+
+//Q: can I use gRCP with this also?


Yes. It should work with GRPCRoutes just like HTTPRoutes AFAIAK. I haven't tested it though.

guicassolato · 2026-05-15T09:47:11Z

+[role="_abstract"]
+To use the X.509 format for certificate, you must create an `HTTPRoute` custom resource (CR) that references your `Gateway` object.
+
+//Q: Can we also use a GRCPRoute instead? If yes, is there anything we should caveat about fields there?


Yes. It should work with GRPCRoutes just like HTTPRoutes AFAIAK. I haven't tested it though.

guicassolato · 2026-05-15T09:48:37Z

+[id="rhcl-ts-x509-auth"]
+= Troubleshooting X.509 authentication
+
+//Q: would we use all of these on OpenShift?


guicassolato · 2026-05-15T09:58:07Z

+[id="rhcl-x509-auth-prep-cas-and-certs"]
+= Prepare certificate authorites and client certificates
+
+//Q: downstream, would we use cert-manager or Service CA for some or all of this procedure?


IDK for sure, but I was wondering about the instructions to create a TLS-enabled gateway anyway.

The upstream user guide provides top-to-bottom instructions to enable this feature, from defining a gateway, to testing the authentication using a test client cert. We have documentation about how to enable TLS on a Gateway using the TLSPolicy. For the "Using X.509 cryptographic identity verification" guide, because this is focused on Tier 2, if you prefer, we could skip the procedure for defining the Gateway object, which includes the cert-manager CR and the TLSPolicy, to just refer to this other doc and mention that gateway is assumed to be called mtls-gateway, in the gateway-system namespace, for the next steps.

Please let me know what you prefer.

This content is from Step 3, https://github.com/Kuadrant/kuadrant-operator/blob/main/doc/user-guides/auth/x509-tier2-provider-specific.md#step-3-configure-gateway. I just pulled in the YAMLs from the link.

I'm pretty sure we don't give instructions anywhere in the current docs for the cert-manager CR. We probably want it here, right?

The cert-manager CR is only for the TLSPolicy to work. If we have a page where we explain about the TLSPolicy and how to use it, that's the one.

Do we always need cert-manager for all TLSPolicies? This is the existing doc: https://docs.redhat.com/en/documentation/red_hat_connectivity_link/1.3/html/deploying_red_hat_connectivity_link/rhcl-config-deploy-gateway-policies#proc-set-tls-policy_rhcl-config-deploy-gateway-policies

Yes. It's not explicitly mentioned as a prerequisite in section 1.2.2, but spread all over the doc. In fact, section 1.2.1 is all about using cert-manager in preparation for a TLSPolicy. And as you can see from the example TLSPolicy resource provided further below, there's a issuerRef field that references a cert-manager object (of Issuer or ClusterIssuer kind).

guicassolato · 2026-05-15T10:01:33Z

+
+* You are logged into {ocp} as a cluster administrator.
+* You installed {prodname} using Istio as your `Gateway` object controller.
+//Q: if I installed RHCL with openshift-ingress as my Gateway controller, can I make a new Gateway and delete the old one? or do i have to reinstall RHCL?


If you installed RHCL with openshift-ingress, I don't think you get a gateway created by default AFAIAK. So there's no old gateway to delete, I suppose.

Definitely, you do not need to reinstall RHCL.

The only important thing regarding this IMO is making sure whatever gateway controller is being used (OSSM or CIO), the Gateway object (if created as part of trying this feature) must specify the correct gatewayClassName.

Does X.509 work if Istio is not the Gateway controller? I thought it had to be istio for the gatewayClassName.

Tier 2 works with all supported gateway controllers, including istio and openshift.io/gateway-controller/v1.

guicassolato · 2026-05-15T10:07:38Z

+EOF
+----
+
+//Q: how would we automate these steps if we're using enterprise openshift?


Automating this step is out of scope. Customers interested in using X.509 client certificates for cryptographic identity verification must have their way of provisioning the certificates.

What we need to do is to highlight the requisites RHCL imposes in relation to this process:

Include the extendedKeyUsage=clientAuth parameter in the client certs

Mount the root CA cert into the gateway pods (for 1st layer validation)

Store the CA cert used to sign the client certs in a Secret, labeled for discovery by Authorino (for 2nd layer validation)

guicassolato · 2026-05-15T10:18:34Z

+$ oc apply -f
+----
+
+//Q: are these just general required steps? e.g, create an SA, Service, and Deployment; does an OpenShift user need these YAMLs as examples?


This is so we have a fully functional backend application to test the end-to-end flow of authenticating requests by X.509 client certs. It should work in OpenShift just like in vanilla Kubernetes, with the exception of possibly some OpenShift policies regarding things like securityContext, which as out of scope for this doc IMO.

At this point, users should be able to infer this application is provided just as an example, and understand the process of deploying and running a real one on the target platform.

guicassolato · 2026-05-15T10:23:32Z

+[id="rhcl-verifying-x509-auth"]
+= Verifying X.509 authentication
+
+//Q: would we test this way on OpenShift?


This feature is covered by our automated tests from our test suite that run on OpenShift: Kuadrant/testsuite#894.

openshift-ci · 2026-05-15T15:48:14Z

@ShaunaDiaz: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/validate-asciidoc	`0cb6fd3`	link	true	`/test validate-asciidoc`

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label May 14, 2026

openshift-ci Bot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label May 14, 2026

ShaunaDiaz changed the title ~~OSDOCS-19695: adds X.509certificate support to RCHL~~ [WIP]OSDOCS-19695: adds X.509certificate support to RCHL May 14, 2026

openshift-ci Bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label May 14, 2026

ShaunaDiaz force-pushed the OSDOCS-19695 branch from c6edf3c to 568b39c Compare May 14, 2026 19:10

guicassolato reviewed May 15, 2026

View reviewed changes

Comment thread deployment/rhcl-using-x509-crypt-id-verify.adoc

guicassolato reviewed May 15, 2026

View reviewed changes

Comment thread deployment/rhcl-using-x509-crypt-id-verify.adoc Outdated

guicassolato reviewed May 15, 2026

View reviewed changes

OSDOCS-19695: adds X.509certificate support to RCHL

0cb6fd3

ShaunaDiaz force-pushed the OSDOCS-19695 branch from 568b39c to 0cb6fd3 Compare May 15, 2026 15:41


		//Q: would we create this filter manually on OpenShift, or just use the Gateway or AuthPolicy?

		Create an EnvoyFilter to configure Envoy's DownstreamTlsContext for client certificate validation:

Conversation

ShaunaDiaz commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented May 14, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci Bot commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ShaunaDiaz commented May 14, 2026 •

edited

Loading

openshift-ci-robot commented May 14, 2026 •

edited by openshift-ci Bot

Loading

ocpdocs-previewbot commented May 14, 2026 •

edited

Loading