Skip to content

Commit 3998e0f

Browse files
skopacz1skopacz1
authored
Merge pull request #90302 from openshift-cherrypick-robot/cherry-pick-89608-to-enterprise-4.19
[enterprise-4.19] Added istio-csr feature section in cert-manager docs
2 parents d3d80fa + 2a1204a commit 3998e0f

8 files changed

+340
-1
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1218,6 +1218,8 @@ Topics:
12181218
File: cert-manager-creating-certificate
12191219
- Name: Securing routes with the cert-manager Operator for Red Hat OpenShift
12201220
File: cert-manager-securing-routes
1221+
- Name: Integrating the cert-manager Operator with Istio-CSR
1222+
File: cert-manager-operator-integrating-istio
12211223
- Name: Monitoring the cert-manager Operator for Red Hat OpenShift
12221224
File: cert-manager-monitoring
12231225
- Name: Configuring log levels for cert-manager and the cert-manager Operator for Red Hat OpenShift

‎modules/cert-manager-enabling-istio.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="cert-manager-enabling-istio_{context}"]
7+
= Enabling the Istio-CSR feature
8+
9+
Use this procedure to enable the Istio-CSR feature in {cert-manager-operator}.
10+
11+
.Prerequisites
12+
13+
* You have access to the cluster as a user with the `cluster-admin` role.
14+
15+
.Procedure
16+
17+
* Update the deployment for the {cert-manager-operator} to use the config map by running the following command:
18+
+
19+
[source,terminal]
20+
----
21+
$ oc -n cert-manager-operator patch subscription openshift-cert-manager-operator --type='merge' -p '{"spec":{"config":{"env":[{"name":"UNSUPPORTED_ADDON_FEATURES","value":"IstioCSR=true"}]}}}'
22+
----
23+
24+
.Verification
25+
26+
. Verify that the deployments have finished rolling out by running the following command:
27+
+
28+
[source,terminal]
29+
----
30+
$ oc rollout status deployment/cert-manager-operator-controller-manager -n cert-manager-operator
31+
----
32+
+
33+
.Example output
34+
[source,terminal]
35+
----
36+
deployment "cert-manager-operator-controller-manager" successfully rolled out
37+
----

‎modules/cert-manager-istio-creating-issuer.adoc‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="cert-manager-istio-creating-issuer_{context}"]
7+
= Creating a root CA issuer for the Istio-CSR agent
8+
9+
Use this procedure to create the root CA issuer for Istio-CSR agent.
10+
11+
[NOTE]
12+
====
13+
Other supported issuers can be used, except for the ACME issuer, which is not supported. For more information, see "{cert-manager-operator} issuer providers".
14+
====
15+
16+
* Create a YAML file, for example, `issuer.yaml`, that defines the `Issuer` and `Certificate` objects:
17+
+
18+
.Example `issuer.yaml` file
19+
[source,yaml]
20+
----
21+
apiVersion: cert-manager.io/v1
22+
kind: Issuer <1>
23+
metadata:
24+
name: selfsigned
25+
namespace: <istio_project_name> <2>
26+
spec:
27+
selfSigned: {}
28+
---
29+
apiVersion: cert-manager.io/v1
30+
kind: Certificate
31+
metadata:
32+
name: istio-ca
33+
namespace: <istio_project_name>
34+
spec:
35+
isCA: true
36+
duration: 87600h # 10 years
37+
secretName: istio-ca
38+
commonName: istio-ca
39+
privateKey:
40+
algorithm: ECDSA
41+
size: 256
42+
subject:
43+
organizations:
44+
- cluster.local
45+
- cert-manager
46+
issuerRef:
47+
name: selfsigned
48+
kind: Issuer <1>
49+
group: cert-manager.io
50+
---
51+
kind: Issuer
52+
metadata:
53+
name: istio-ca
54+
namespace: <istio_project_name> <2>
55+
spec:
56+
ca:
57+
secretName: istio-ca
58+
----
59+
<1> Specify the `Issuer` or `ClusterIssuer`.
60+
<2> Specify the name of the Istio project.
61+
62+
.Verification
63+
64+
* Verify that the Issuer is created and ready to use by running the following command:
65+
+
66+
[source,terminal]
67+
----
68+
$ oc get issuer istio-ca -n <istio_project_name>
69+
----
70+
+
71+
.Example output
72+
[source,terminal]
73+
----
74+
NAME READY AGE
75+
istio-ca True 3m
76+
----

‎modules/cert-manager-istio-csr-installing.adoc‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="cert-manager-istio-csr-installing_{context}"]
7+
= Creating the `IstioCSR` custom resource
8+
9+
Use this procedure to install the Istio-CSR agent through {cert-manager-operator}.
10+
11+
.Prerequisites
12+
13+
* You have access to the cluster with `cluster-admin` privileges.
14+
* You have enabled the Istio-CSR feature.
15+
* You have created the `Issuer` or `ClusterIssuer` resources required for generating certificates for the Istio-CSR agent.
16+
+
17+
[NOTE]
18+
====
19+
If you are using `Issuer` resource, create the `Issuer` and `Certificate` resources in the {SMProductName} or `Istiod` namespace. Certificate requests are generated in the same namespace, and role-based access control (RBAC) is configured accordingly.
20+
====
21+
22+
.Procedure
23+
24+
. Create a new project for installing Istio-CSR by running the following command. You can use an existing project and skip this step.
25+
+
26+
[source,terminal]
27+
----
28+
$ oc new-project <istio_csr_project_name>
29+
----
30+
31+
. Create the `IstioCSR` custom resource to enable Istio-CSR agent managed by the {cert-manager-operator} for processing Istio workload and control plane certificate signing requests.
32+
+
33+
[NOTE]
34+
====
35+
Only one `IstioCSR` custom resource (CR) is supported at a time. If multiple `IstioCSR` CRs are created, only one will be active. Use the `status` sub-resource of `IstioCSR` to check if a resource is unprocessed.
36+
37+
* If multiple `IstioCSR` CRs are created simultaneously, none will be processed.
38+
* If multiple `IstioCSR` CRs are created sequentially, only the first one will be processed.
39+
* To prevent new requests from being rejected, delete any unprocessed `IstioCSR` CRs.
40+
* The Operator does not automatically remove objects created for `IstioCSR`. If an active `IstioCSR` resource is deleted and a new one is created in a different namespace without removing the previous deployments, multiple `istio-csr` deployments may remain active. This behavior is not recommended and is not supported.
41+
====
42+
43+
.. Create a YAML file, for example, `istiocsr.yaml`, that defines the `IstioCSR` object:
44+
+
45+
.Example `IstioCSR.yaml` file
46+
[source,yaml]
47+
----
48+
apiVersion: operator.openshift.io/v1alpha1
49+
kind: IstioCSR
50+
metadata:
51+
name: default
52+
namespace: <istio_csr_project_name>
53+
spec:
54+
IstioCSRConfig:
55+
certManager:
56+
issuerRef:
57+
name: istio-ca <1>
58+
kind: Issuer <2>
59+
group: cert-manager.io
60+
istiodTLSConfig:
61+
trustDomain: cluster.local
62+
istio:
63+
namespace: istio-system
64+
----
65+
<1> Specify the `Issuer` or `ClusterIssuer` name. It should be the same name as the CA issuer defined in the `issuer.yaml` file.
66+
<2> Specify the `Issuer` or `ClusterIssuer` kind. It should be the same kind as the CA issuer defined in the `issuer.yaml` file.
67+
68+
.. Create the `IstioCSR` custom resource by running the following command:
69+
+
70+
[source,terminal]
71+
----
72+
$ oc create -f IstioCSR.yaml
73+
----
74+
75+
.Verification
76+
77+
. Verify that the Istio-CSR deployment is ready by running the following command:
78+
+
79+
[source,terminal]
80+
----
81+
$ oc get deployment -n <istio_csr_project_name>
82+
----
83+
+
84+
.Example output
85+
[source,terminal]
86+
----
87+
NAME READY UP-TO-DATE AVAILABLE AGE
88+
cert-manager-istio-csr 1/1 1 1 24s
89+
----
90+
91+
. Verify that the Istio-CSR pods are running by running the following command:
92+
+
93+
[source,terminal]
94+
----
95+
$ oc get pod -n <istio_csr_project_name>
96+
----
97+
+
98+
.Example output
99+
[source,terminal]
100+
----
101+
NAME READY STATUS RESTARTS AGE
102+
cert-manager-istio-csr-5c979f9b7c-bv57w 1/1 Running 0 45s
103+
----
104+
105+
** Verify that the Istio-CSR pod is not reporting any errors in the logs by running the following command:
106+
+
107+
[source,terminal]
108+
----
109+
$ oc -n <istio_csr_project_name> logs <istio_csr_pod_name>
110+
----
111+
112+
** Verify that the {cert-manager-operator} pod is not reporting any errors by running the following command:
113+
+
114+
[source,terminal]
115+
----
116+
$ oc -n cert-manager-operator logs <cert_manager_operator_pod_name>
117+
----

‎modules/cert-manager-istio-csr-uninstalling.adoc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="cert-manager-istio-csr-uninstalling_{context}"]
7+
= Uninstalling the Istio-CSR agent managed by {cert-manager-operator}
8+
9+
Use this procedure to uninstall the Istio-CSR agent managed by {cert-manager-operator}.
10+
11+
.Prerequisites
12+
13+
* You have access to the cluster with `cluster-admin` privileges.
14+
* You have enabled the Istio-CSR feature.
15+
* You have created the `IstioCSR` custom resource.
16+
17+
.Procedure
18+
19+
. Remove the `IstioCSR` custom resource by running the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ oc -n <istio-csr_project_name> delete istiocsrs.operator.openshift.io default
24+
----
25+
26+
. Remove related resources:
27+
+
28+
[IMPORTANT]
29+
====
30+
To avoid disrupting any {SMProductName} or Istio components, ensure that no component is referencing the Istio-CSR service or the certificates issued for Istio before removing the following resources.
31+
====
32+
33+
.. List the cluster scoped-resources by running the following command and save the names of the listed resources for later reference:
34+
+
35+
[source,terminal]
36+
----
37+
$ oc get clusterrolebindings,clusterroles -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr"
38+
----
39+
40+
.. List the resources in Istio-csr deployed namespace by running the following command and save the names of the listed resources for later reference:
41+
+
42+
[source,terminal]
43+
----
44+
$ 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>
45+
----
46+
47+
.. List the resources in {SMProductName} or Istio deployed namespaces by running the following command and save the names of the listed resources for later reference:
48+
+
49+
[source,terminal]
50+
----
51+
$ oc get roles,rolebindings -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n <istio_csr_project_name>
52+
----
53+
54+
.. For each resource listed in previous steps, delete the resource by running the following command:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc -n <istio_csr_project_name> delete <resource_type>/<resource_name>
59+
----
60+
+
61+
Repeat this process until all of the related resources have been deleted.

‎modules/cert-manager-istio-csr-updating.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="cert-manager-istio-csr-updating_{context}"]
7+
= Upgrading the {cert-manager-operator} with Istio-CSR feature enabled
8+
9+
When the Istio-CSR TechPreview feature gate is enabled, the Operator cannot be upgraded. To use to the next available version, you must uninstall the {cert-manager-operator} and remove all Istio-CSR resources before reinstalling it.

‎security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="cert-manager-operator-integrating-istio"]
3+
= Integrating the {cert-manager-operator} with Istio-CSR
4+
include::_attributes/common-attributes.adoc[]
5+
:context: cert-manager-operator-integrating-istio
6+
7+
toc::[]
8+
9+
:FeatureName: Istio-CSR integration for {cert-manager-operator}
10+
include::snippets/technology-preview.adoc[]
11+
12+
The {cert-manager-operator} provides enhanced support for securing workloads and control plane components in {SMProductName} or Istio. This includes support for certificates enabling mutual TLS (mTLS), which are signed, delivered, and renewed using cert-manager issuers. You can secure Istio workloads and control plane components by using the {cert-manager-operator} managed Istio-CSR agent.
13+
14+
With this Istio-CSR integration, Istio can now obtain certificates from the {cert-manager-operator}, simplifying security and certificate management.
15+
16+
[id="cert-manager-operator-istio-csr-installing_{context}"]
17+
== Installing the Istio-CSR agent through {cert-manager-operator}
18+
19+
// Enabling Istio-CSR
20+
include::modules/cert-manager-enabling-istio.adoc[leveloffset=+2]
21+
22+
// Creating issuer
23+
include::modules/cert-manager-istio-creating-issuer.adoc[leveloffset=+2]
24+
25+
[role="_additional-resources"]
26+
.Additional resources
27+
28+
* xref:../../security/cert_manager_operator/index.adoc#cert-manager-issuer-types_cert-manager-operator-about[{cert-manager-operator} issuer providers]
29+
30+
// Installing using Istio-CSR
31+
include::modules/cert-manager-istio-csr-installing.adoc[leveloffset=+2]
32+
33+
// Uninstalling cert-manager Operator with Istio-CSR
34+
include::modules/cert-manager-istio-csr-uninstalling.adoc[leveloffset=+1]
35+
36+
// Updating Istio-CSR
37+
include::modules/cert-manager-istio-csr-updating.adoc[leveloffset=+1]

‎security/cert_manager_operator/cert-manager-operator-uninstall.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,4 @@ You can remove the {cert-manager-operator} from {product-title} by uninstalling
1212
include::modules/cert-manager-uninstall-console.adoc[leveloffset=+1]
1313

1414
// Removing {cert-manager-operator} resources
15-
include::modules/cert-manager-remove-resources-console.adoc[leveloffset=+1]
15+
include::modules/cert-manager-remove-resources-console.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)