Skip to content

Commit 1ccdfca

Browse files
ShaunaDiazShaunaDiaz
authored
Merge pull request #94843 from shreyasiddhartha/OSSM-6707
OSSM 6707- Update cert-manager doc for OCP cert-manager's supported istio-csr
2 parents 5accee4 + b06e134 commit 1ccdfca

6 files changed

+383
-70
lines changed

‎install/ossm-cert-manager.adoc

Lines changed: 15 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -10,37 +10,27 @@ toc::[]
1010

1111
The cert-manager tool is a solution for X.509 certificate management on Kubernetes. It delivers a unified API to integrate applications with private or public key infrastructure (PKI), such as Vault, Google Cloud Certificate Authority Service, Let's Encrypt, and other providers.
1212

13+
The cert-manager tool ensures that the certificates are valid and up-to-date by attempting to renew certificates at a configured time before they expire.
14+
1315
[IMPORTANT]
1416
====
1517
The cert-manager tool must be installed before you create and install your `Istio` resource.
1618
====
1719

18-
The cert-manager tool ensures the certificates are valid and up-to-date by attempting to renew certificates at a configured time before they expire.
19-
2020
include::modules/ossm-about-cert-manager.adoc[leveloffset=+1]
21-
include::modules/ossm-installing-cert-manager.adoc[leveloffset=+1]
22-
23-
.Next steps
24-
To install `istio-csr`, you must follow the `istio-csr` installation instructions for the type of update strategy you want. By default, `spec.updateStrategy` is set to `InPlace` when you create and install your `Istio` resource. You create and install your `Istio` resource after you install `istio-csr`.
25-
26-
* xref:../install/ossm-cert-manager.adoc#inplace-istio-csr-installation_ossm-cert-manager[Installing the istio-csr agent by using the in place update strategy]
27-
* xref:../install/ossm-cert-manager.adoc#revision-based-istio-csr-installation_ossm-cert-manager[Installing the istio-csr agent by using the revision based update strategy]
28-
29-
include::modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc[leveloffset=+2]
21+
include::modules/ossm-installing-cert-manager.adoc[leveloffset=+2]
22+
include::modules/ossm-verifying-cert-manager.adoc[leveloffset=+2]
23+
include::modules/ossm-uninstalling-cert-manager.adoc[leveloffset=+2]
3024

31-
.Next steps
32-
* xref:../install/ossm-cert-manager.adoc#installing-istio-resource_ossm-cert-manager[Installing your Istio resource]
3325

34-
include::modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc[leveloffset=+2]
35-
36-
[id="additional-resources_{context}"]
26+
[role="_additional-resources"]
3727
.Additional resources
38-
* link:https://github.com/cert-manager/istio-csr/tree/main/deploy/charts/istio-csr#appistiorevisions0--string[istio-csr deployment]
39-
40-
41-
.Next steps
42-
* xref:../install/ossm-cert-manager.adoc#installing-istio-resource_ossm-cert-manager[Installing your Istio resource]
43-
44-
include::modules/ossm-cert-manager-installing-istio-resource.adoc[leveloffset=+2]
45-
include::modules/ossm-cert-manager-verifying-install.adoc[leveloffset=+2]
46-
include::modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc[leveloffset=+1]
28+
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-install[Installing the cert-manager Operator for Red Hat OpenShift]
29+
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/security_and_compliance/cert-manager-operator-for-red-hat-openshift#cert-manager-operator-integrating-istio[Integrating the cert-manager Operator for Red Hat OpenShift with Istio-CSR]
30+
31+
//include::modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc[leveloffset=+2]
32+
//include::modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc[leveloffset=+2]
33+
//include::modules/ossm-cert-manager-installing-istio-resource.adoc[leveloffset=+2]
34+
//include::modules/ossm-cert-manager-verifying-install.adoc[leveloffset=+2]
35+
//include::modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc[leveloffset=+1]
36+
//The above modules are no longer valid for 3.0

‎modules/ossm-about-cert-manager.adoc

Lines changed: 6 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,32 +4,15 @@
44

55
:_mod-docs-content-type: CONCEPT
66
[id="ossm-cert-manager-integration-istio_{context}"]
7-
= About integrating Service Mesh with cert-manager and istio-csr
8-
//TP1 content influx. Title, etc may change.
7+
= About the cert-manager Operator istio-csr agent
98

10-
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:
9+
include::snippets/technology-preview-istiocsr.adoc[]
1110

12-
. Verifying the identity of the workload.
13-
. Creating a CSR through cert-manager for the workload.
11+
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.
1412

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

1715
[NOTE]
1816
====
19-
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.
20-
====
21-
22-
//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.
23-
24-
.Prerequisites
25-
* One of these versions of cert-manager:
26-
** Red Hat cert-manager Operator 1.10 or later
27-
** community cert-manager Operator 1.11 or later
28-
** cert-manager 1.11 or later
29-
* {SMProductName} 3.0 or later
30-
* An `IstioCNI` instance is running in the cluster
31-
* Istio CLI (`istioctl`) tool is installed
32-
* `jq` is installed
33-
* Helm is installed
34-
35-
//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.
17+
The {cert-manager-operator} must be installed before you create and install your `{istio}` resource.
18+
====

‎modules/ossm-installing-cert-manager.adoc

Lines changed: 109 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
// Module included in the following assemblies:
22
//
3-
// * service-mesh-docs-main/install/ossm-installing-openshift-service-mesh.adoc
3+
// * service-mesh-docs-main/install/ossm-cert-manager.adoc
44

55
:_mod-docs-content-type: PROCEDURE
66
[id="ossm-installing-cert-manager_{context}"]
7-
= Installing cert-manager
8-
//TP1 content influx. Title, etc may change.
9-
//Content is very similar to 2.x content
10-
//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.
7+
= Integrating Service Mesh with the cert-manager Operator by using the istio-csr agent
118

12-
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.
9+
You can integrate the cert-manager Operator with {SMProduct} by deploying the `istio-csr` agent 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.
1310

14-
[IMPORTANT]
15-
====
16-
You must install cert-manager before installing your `Istio` resource.
17-
====
11+
.Prerequisites
12+
13+
* You have installed the {cert-manager-operator} version 1.15.1.
14+
* You are logged in to {ocp-product-title} 4.14 or later.
15+
* You have installed the {SMProduct} Operator.
16+
* You have a `IstioCNI` instance running in the cluster.
17+
* You have installed the `istioctl` command.
1818
1919
.Procedure
2020

@@ -25,10 +25,31 @@ You must install cert-manager before installing your `Istio` resource.
2525
$ oc create namespace istio-system
2626
----
2727

28-
. Create the root issuer by creating an `Issuer` object in a YAML file.
28+
. Patch the cert-manager Operator to install the `istio-csr` agent by running the following command:
29+
+
30+
[source, terminal]
31+
----
32+
$ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator \
33+
--type='merge' -p \
34+
'{"spec":{"config":{"env":[{"name":"UNSUPPORTED_ADDON_FEATURES","value":"IstioCSR=true"}]}}}'
35+
----
36+
37+
. Create the root certificate authority (CA) issuer by creating an `Issuer` object for the `istio-csr` agent:
38+
39+
.. Create a new project for installing the `istio-csr` agent by running the following command:
2940
+
41+
[source, terminal]
42+
----
43+
$ oc new-project istio-csr
44+
----
45+
3046
.. Create an `Issuer` object similar to the following example:
3147
+
48+
[NOTE]
49+
====
50+
The `selfSigned` issuer is intended for demonstration, testing, or proof-of-concept environments. For production deployments, use a secure and trusted CA.
51+
====
52+
+
3253
.Example `issuer.yaml` file
3354
[source, yaml]
3455
----
@@ -43,11 +64,11 @@ spec:
4364
apiVersion: cert-manager.io/v1
4465
kind: Certificate
4566
metadata:
46-
name: istio-ca
47-
namespace: istio-system
67+
name: istio-ca
68+
namespace: istio-system
4869
spec:
4970
isCA: true
50-
duration: 87600h # 10 years
71+
duration: 87600h
5172
secretName: istio-ca
5273
commonName: istio-ca
5374
privateKey:
@@ -70,36 +91,102 @@ metadata:
7091
spec:
7192
ca:
7293
secretName: istio-ca
73-
---
7494
----
75-
+
95+
7696
.. Create the objects by running the following command:
7797
+
7898
[source, terminal]
7999
+
80100
----
81101
$ oc apply -f issuer.yaml
82102
----
83-
+
103+
84104
.. Wait for the `istio-ca` certificate to contain the "Ready" status condition by running the following command:
85105
+
86106
[source, terminal]
87107
----
88108
$ oc wait --for=condition=Ready certificates/istio-ca -n istio-system
89109
----
90110

91-
. Copy the `istio-ca` certificate to the `cert-manager` namespace so it can be used by istio-csr:
111+
. Create the `IstioCSR` custom resource:
112+
113+
.. Create the `IstioCSR` custom resource similar to the following example:
92114
+
93-
.. Copy the secret to a local file by running the following command:
115+
.Example `istioCSR.yaml` file
116+
[source, yaml]
117+
----
118+
apiVersion: operator.openshift.io/v1alpha1
119+
kind: IstioCSR
120+
metadata:
121+
name: default
122+
namespace: istio-csr
123+
spec:
124+
istioCSRConfig:
125+
certManager:
126+
issuerRef:
127+
name: istio-ca
128+
kind: Issuer
129+
group: cert-manager.io
130+
istiodTLSConfig:
131+
trustDomain: cluster.local
132+
istio:
133+
namespace: istio-system
134+
----
135+
136+
.. Create the `istio-csr` agent by by running the following command:
137+
+
138+
[source, terminal]
139+
+
140+
----
141+
$ oc create -f istioCSR.yaml
142+
----
143+
144+
.. Verify that the `istio-csr` deployment is ready by running the following command:
94145
+
95146
[source, terminal]
147+
+
96148
----
97-
$ oc get -n istio-system secret istio-ca -o jsonpath='{.data.tls\.crt}' | base64 -d > ca.pem
149+
$ oc get deployment -n istio-csr
98150
----
151+
152+
. Install the `istio` resource:
153+
+
154+
[NOTE]
155+
====
156+
The configuration disables the built-in CA server for {istio} and forwards certificate signing requests from `istiod` to the `istio-csr` agent. The `istio-csr` agent obtains certificates for both `istiod` and mesh workloads from the cert-manager Operator. The `istiod` TLS certificate that is generated by the `istio-csr` agent is mounted into the pod at a known location for use.
157+
====
158+
159+
.. Create the `{istio}` object similar to the following example:
99160
+
100-
.. Create a secret from the local certificate file in the `cert-manager` namespace by running the following command:
161+
.Example `istio.yaml` file
162+
[source, yaml]
163+
----
164+
apiVersion: sailoperator.io/v1
165+
kind: Istio
166+
metadata:
167+
name: default
168+
spec:
169+
version: v1.24-latest
170+
namespace: istio-system
171+
values:
172+
global:
173+
caAddress: cert-manager-istio-csr.istio-csr.svc:443
174+
pilot:
175+
env:
176+
ENABLE_CA_SERVER: "false"
177+
----
178+
179+
.. Create the `{istio}` resource by running the following command:
180+
+
181+
[source, terminal]
182+
+
183+
----
184+
$ oc apply -f istio.yaml
185+
----
186+
187+
.. Verify that the `istio` resource displays the "Ready" status condition by running the following command:
101188
+
102189
[source, terminal]
103190
----
104-
$ oc create secret generic -n cert-manager istio-root-ca --from-file=ca.pem=ca.pem
191+
$ oc wait --for=condition=Ready istios/default -n istio-system
105192
----

‎modules/ossm-uninstalling-cert-manager.adoc

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service-mesh-docs-main/install/ossm-cert-manager.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ossm-uninstalling-cert-manager_{context}"]
7+
= Uninstalling Service Mesh with the cert-manager Operator by using the istio-csr agent
8+
9+
You can uninstall the cert-manager Operator with {SMProduct} by completing the following procedure. Before you remove the following resources, verify that no {SMProductName} or {istio} components reference the `Istio-CSR` agent or the certificates it issued. Removing these resources while they are still in use might disrupt mesh functionality.
10+
11+
.Procedure
12+
13+
. Remove the `IstioCSR` custom resource by running the following command:
14+
+
15+
[source, terminal]
16+
----
17+
$ oc -n <istio-csr_project_name> delete istiocsrs.operator.openshift.io default
18+
----
19+
20+
. Remove the related resources:
21+
22+
.. List the cluster scoped-resources by running the following command:
23+
+
24+
[source, terminal]
25+
----
26+
$ oc get clusterrolebindings,clusterroles -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr"
27+
----
28+
+
29+
Save the names of the listed resources for later reference.
30+
31+
.. List the resources in `istio-csr` agent deployed namespace by running the following command:
32+
+
33+
[source, terminal]
34+
----
35+
$ oc get certificate,deployments,services,serviceaccounts -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n <istio_csr_project_name>
36+
----
37+
+
38+
Save the names of the listed resources for later reference.
39+
40+
.. List the resources in {SMProductName} or {istio} deployed namespaces by running the following command:
41+
+
42+
[source, terminal]
43+
----
44+
$ oc get roles,rolebindings \
45+
-l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" \
46+
-n <istio_csr_project_name>
47+
----
48+
+
49+
Save the names of the listed resources for later reference.
50+
51+
.. For each resource listed in previous steps, delete the resources by running the following command:
52+
+
53+
[source, terminal]
54+
----
55+
$ oc -n <istio_csr_project_name> delete <resource_type>/<resource_name>
56+
----

0 commit comments

Comments
 (0)