Skip to content

OSSM 6707- Update cert-manager doc for OCP cert-manager's supported istio-csr #94843

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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: service-mesh-docs-main
Choose a base branch
from
Open

OSSM 6707- Update cert-manager doc for OCP cert-manager's supported istio-csr #94843

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f6cdac1
OSSM-6707
shreyasiddhartha Jun 17, 2025
01ff60a
Update after changes in draft doc
shreyasiddhartha Jun 18, 2025
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
27 changes: 5 additions & 22 deletions modules/ossm-about-cert-manager.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,14 @@
:_mod-docs-content-type: CONCEPT
[id="ossm-cert-manager-integration-istio_{context}"]
= About integrating Service Mesh with cert-manager and istio-csr
//TP1 content influx. Title, etc may change.

The cert-manager tool provides integration with Istio through an external agent called `istio-csr`. The `istio-csr` agent handles certificate signing requests (CSR) from Istio proxies and the `controlplane` in the following ways:
include::snippets/technology-preview-istiocsr.adoc[]

. Verifying the identity of the workload.
. Creating a CSR through cert-manager for the workload.
The {cert-manager-operator} enhances certificate management for securing workloads and control plane components in {SMProductName} and {istio}. It supports issuing, delivering, and renewing certificates used for mutual Transport Layer Security (mTLS) through cert-manager issuers.

The cert-manager tool then creates a CSR to the configured CA Issuer, which signs the certificate.
By integrating {istio} with the `istio-csr` agent managed by the cert-manager Operator, enables {istio} to request and manage the certificates directly. The integration simplifies security configuration and centralizes certificate management within the cluster.

[NOTE]
====
Red{nbsp}Hat provides support for integrating with `istio-csr` and cert-manager. Red{nbsp}Hat does not provide direct support for the `istio-csr` or the community cert-manager components. The use of community cert-manager shown here is for demonstration purposes only.
====

//For Istio users, cert-manager also provides integration with `istio-csr`, which is a certificate authority (CA) server that handles certificate signing requests (CSR) from Istio proxies. The server then delegates signing to cert-manager, which forwards CSRs to the configured CA server.

.Prerequisites
* One of these versions of cert-manager:
** Red Hat cert-manager Operator 1.10 or later
** community cert-manager Operator 1.11 or later
** cert-manager 1.11 or later
* {SMProductName} 3.0 or later
* An `IstioCNI` instance is running in the cluster
* Istio CLI (`istioctl`) tool is installed
* `jq` is installed
* Helm is installed

//Note to add {cert-manager-operator} to stand alone common attributes file. That is outside the scope of this PR and there is an existing Jira to add common attributes for OSSM GA.
The {cert-manager-operator} must be installed before you create and install your `{istio}` resource.
====
302 changes: 281 additions & 21 deletions modules/ossm-installing-cert-manager.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,18 @@
:_mod-docs-content-type: PROCEDURE
[id="ossm-installing-cert-manager_{context}"]
= Installing cert-manager
//TP1 content influx. Title, etc may change.
//Content is very similar to 2.x content
//all kinds of formatting things to fix. want to see if a build will generate to have a look, and see how it fits structurally with the IA.

You can integrate cert-manager with {SMProduct} by deploying `istio-csr` and then creating an `Istio` resource that uses the `istio-csr` agent to process workload and control plane certificate signing requests. This example creates a self-signed `Issuer`, but any other `Issuer` can be used instead.
include::snippets/technology-preview-istiocsr.adoc[]

[IMPORTANT]
====
You must install cert-manager before installing your `Istio` resource.
====
You can integrate cert-manager with the {SMProduct} by deploying the `istio-csr` and configuring an `{istio}` resource that uses the `istio-csr` agent to process workload and control plane certificate signing requests. The following procedure creates a self-signed `issuer` object.

.Prerequisites

* You have installed the {cert-manager-operator} version 1.15.1.
* You are logged in to {ocp-product-title} 4.14 or later.
* You have installed the {SMProduct} Operator.
* You have `IstioCNI` instance running in the cluster.
* You have installed the `istioctl` command.

.Procedure

Expand All @@ -25,10 +27,29 @@ You must install cert-manager before installing your `Istio` resource.
$ oc create namespace istio-system
----

. Create the root issuer by creating an `Issuer` object in a YAML file.
. Patch the cert-manager Operator to install the `istio-csr` agent by running the following command:
+
[source, terminal]
----
$ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type='merge' -p '{"spec":{"config":{"env":[{"name":"UNSUPPORTED_ADDON_FEATURES","value":"IstioCSR=true"}]}}}'
----

. Create the root certificate authority (CA) issuer by creating an `Issuer` object for the `istio-csr` agent:

.. Create a new project for installing the `istio-csr` agent by running the following command:
+
[source, terminal]
----
$ oc new-project istio-csr
----

.. Create an `Issuer` object similar to the following example:
+
[NOTE]
====
The `selfSigned` issuer is intended for demonstration, testing, or proof-of-concept environments. For production deployments, use a secure and trusted CA.
====
+
.Example `issuer.yaml` file
[source, yaml]
----
Expand All @@ -43,11 +64,11 @@ spec:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: istio-ca
namespace: istio-system
name: istio-ca
namespace: istio-system
spec:
isCA: true
duration: 87600h # 10 years
duration: 87600h
secretName: istio-ca
commonName: istio-ca
privateKey:
Expand All @@ -70,36 +91,275 @@ metadata:
spec:
ca:
secretName: istio-ca
---
----
+

.. Create the objects by running the following command:
+
[source, terminal]
+
----
$ oc apply -f issuer.yaml
----
+

.. Wait for the `istio-ca` certificate to contain the "Ready" status condition by running the following command:
+
[source, terminal]
----
$ oc wait --for=condition=Ready certificates/istio-ca -n istio-system
----

. Copy the `istio-ca` certificate to the `cert-manager` namespace so it can be used by istio-csr:
. Create the `IstioCSR` custom resource:

.. Create the `IstioCSR` custom resource similar to the following example:
+
.Example `istioCSR.yaml` file
[source, yaml]
----
apiVersion: operator.openshift.io/v1alpha1
kind: IstioCSR
metadata:
name: default
namespace: istio-csr
spec:
istioCSRConfig:
certManager:
issuerRef:
name: istio-ca
kind: Issuer
group: cert-manager.io
istiodTLSConfig:
trustDomain: cluster.local
istio:
namespace: istio-system
----

.. Create the `istio-csr` agent by by running the following command:
+
[source, terminal]
+
----
$ oc create -f istioCSR.yaml
----

.. Verify if the `istio-csr` deployment is ready by running the following command:
+
[source, terminal]
+
----
$ oc get deployment -n istio-csr
----

. Install the `istio` resource:
+
[NOTE]
====
The configuration disables the built-in CA server for {istio} and forwards certificate signing requests from `istiod` to `istio-csr`. The `istio-csr` agent obtains certificates for both `istiod` and mesh workloads from cert-manager. The istiod TLS certificate generated by `istio-csr` is mounted into the pod at a known location for use.
====

.. Create the `{istio}` object similar to the following example:
+
.Example `istio.yaml` file
[source, yaml]
----
apiVersion: sailoperator.io/v1
kind: Istio
metadata:
name: default
spec:
version: v1.24-latest
namespace: istio-system
values:
global:
caAddress: cert-manager-istio-csr.istio-csr.svc:443
pilot:
env:
ENABLE_CA_SERVER: "false"
----

.. Create the `{istio}` resource by running the following command:
+
[source, terminal]
+
----
$ oc apply -f istio.yaml
----

.. Wait for the `istio` resource to contain the "Ready" status condition by running the following command:
+
[source, terminal]
----
$ oc wait --for=condition=Ready istios/default -n istio-system
----

.Verification

You can use the sample `httpbin` service and `sleep` application to verify traffic between workloads. Check the workload proxy certificate to verify that the cert-manager is installed correctly.

. Create the namespaces:

.. Create the `apps-1` namespace by running the following command:
+
[source, terminal]
----
$ oc new-project apps-1
----

.. Create the `apps-2` namespace by running the following command:
+
[source, terminal]
----
$ oc new-project apps-2
----

. Enable istio-injection on the namespaces:

.. Enable the istio-injection on the `apps-1` namespace by running the following command:
+
[source, terminal]
----
$ oc label namespaces apps-1 istio-injection=enabled
----

.. Enable the istio-injection on the `apps-2` namespace by running the following command:
+
[source, terminal]
----
$ oc label namespaces apps-2 istio-injection=enabled
----

. Deploy the `httpbin` app in the namespaces:

.. Deploy the `httpbin` app in the `apps-1` namespace by running the following command:
+
[source, terminal]
----
$ oc apply -n apps-1 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/httpbin/httpbin.yaml
----

.. Deploy the `httpbin` app in the `apps-2` namespace by running the following command:
+
[source, terminal]
----
$ oc apply -n apps-2 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/httpbin/httpbin.yaml
----

. Deploy the `sleep` app in the namespaces:

.. Deploy the `sleep` app in the `apps-1` namespace by running the following command:
+
[source, terminal]
----
$ oc apply -n apps-1 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/sleep/sleep.yaml
----

.. Deploy the `sleep` app in the `apps-2` namespace by running the following command:
+
[source, terminal]
----
$ oc apply -n apps-2 -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/sleep/sleep.yaml
----

. Verify that the created apps have sidecars injected:

.. Verify that the created apps have sidecars injected for `apps-1` namespace by running the following command:
+
[source, terminal]
----
$ oc get pods -n apps-1
----

.. Verify that the created apps have sidecars injected for `apps-2` namespace by running the following command:
+
[source, terminal]
----
$ oc get pods -n apps-2
----

. Create a mesh-wide strict mutual Transport Layer Security (mTLS) policy similar to the following example:
+
[NOTE]
====
Enabling `PeerAuthentication` in strict mTLS mode verifies that certificates are distributed correctly and that mTLS communication between workloads work.
====
+
.Example `peer_auth.yaml` file
[source, yaml]
----
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: default
namespace: istio-system
spec:
mtls:
mode: STRICT
----

. Apply the mTLS policy by running the following command:
+
[source, terminal]
----
$ oc apply -f peer_auth.yaml
----

. Verify that the `apps-1/sleep` app can access the `apps-2/httpbin` service by running the following command:
+
.. Copy the secret to a local file by running the following command:
[source, terminal]
----
$ oc -n apps-1 exec "$(oc -n apps-1 get pod -l app=sleep -o jsonpath={.items..metadata.name})" -c sleep -- curl -sIL http://httpbin.apps-2.svc.cluster.local:8000
----
+
.Example output
+
[source, terminal]
----
HTTP/1.1 200 OK
access-control-allow-credentials: true
access-control-allow-origin: *
content-security-policy: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' camo.githubusercontent.com
content-type: text/html; charset=utf-8
date: Wed, 18 Jun 2025 09:20:55 GMT
x-envoy-upstream-service-time: 14
server: envoy
transfer-encoding: chunked
----

. Verify that the `apps-2/sleep` app can access the `apps-1/httpbin` service by running the following command:
+
[source, terminal]
----
$ oc -n apps-2 exec "$(oc -n apps-2 get pod -l app=sleep -o jsonpath={.items..metadata.name})" -c sleep -- curl -sIL http://httpbin.apps-1.svc.cluster.local:8000
----
+
.Example output
+
[source, terminal]
----
HTTP/1.1 200 OK
access-control-allow-credentials: true
access-control-allow-origin: *
content-security-policy: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' camo.githubusercontent.com
content-type: text/html; charset=utf-8
date: Wed, 18 Jun 2025 09:21:23 GMT
x-envoy-upstream-service-time: 16
server: envoy
transfer-encoding: chunked
----

. Verify that the `httpbin` workload certificate matches as expected by running the following command:
+
[source, terminal]
----
$ oc get -n istio-system secret istio-ca -o jsonpath='{.data.tls\.crt}' | base64 -d > ca.pem
$ istioctl proxy-config secret -n apps-1 $(oc get pods -n apps-1 -o jsonpath='{.items..metadata.name}' --selector app=httpbin) -o json | jq -r '.dynamicActiveSecrets[0].secret.tlsCertificate.certificateChain.inlineBytes' | base64 --decode | openssl x509 -text -noout
----
+
.. Create a secret from the local certificate file in the `cert-manager` namespace by running the following command:
.Example output
+
[source, terminal]
----
$ oc create secret generic -n cert-manager istio-root-ca --from-file=ca.pem=ca.pem
----
...
Issuer: O = cert-manager + O = cluster.local, CN = istio-ca
...
X509v3 Subject Alternative Name:
URI:spiffe://cluster.local/ns/apps-1/sa/httpbin
----
Loading