diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 5e0f877aeb2e..19e47c0334c7 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1126,6 +1126,8 @@ Topics: File: cert-manager-creating-certificate - Name: Enabling monitoring for the cert-manager Operator for Red Hat OpenShift File: cert-manager-monitoring + - Name: Integrating the cert-manager Operator with Istio-CSR + File: cert-manager-operator-integrating-istio - Name: Configuring the egress proxy for the cert-manager Operator for Red Hat OpenShift File: cert-manager-operator-proxy - Name: Customizing cert-manager by using the cert-manager Operator API fields diff --git a/modules/cert-manager-enabling-istio.adoc b/modules/cert-manager-enabling-istio.adoc new file mode 100644 index 000000000000..becb153d282f --- /dev/null +++ b/modules/cert-manager-enabling-istio.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cert-manager-enabling-istio_{context}"] += Enabling the Istio-CSR feature + +Use this procedure to enable the Istio-CSR feature in {cert-manager-operator}. + +.Prerequisites + +* You have access to the cluster as a user with the `cluster-admin` role. + +.Procedure + +* Update the deployment for the {cert-manager-operator} to use the config map 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"}]}}}' +---- + +.Verification + +. Verify that the deployments have finished rolling out by running the following command: ++ +[source,terminal] +---- +$ oc rollout status deployment/cert-manager-operator-controller-manager -n cert-manager-operator +---- ++ +.Example output +[source,terminal] +---- +deployment "cert-manager-operator-controller-manager" successfully rolled out +---- \ No newline at end of file diff --git a/modules/cert-manager-istio-creating-issuer.adoc b/modules/cert-manager-istio-creating-issuer.adoc new file mode 100644 index 000000000000..b44b77b6eff4 --- /dev/null +++ b/modules/cert-manager-istio-creating-issuer.adoc @@ -0,0 +1,76 @@ +// Module included in the following assemblies: +// +// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cert-manager-istio-creating-issuer_{context}"] += Creating a root CA issuer for the Istio-CSR agent + +Use this procedure to create the root CA issuer for Istio-CSR agent. + +[NOTE] +==== +Other supported issuers can be used, except for the ACME issuer, which is not supported. For more information, see "{cert-manager-operator} issuer providers". +==== + +* Create a YAML file, for example, `issuer.yaml`, that defines the `Issuer` and `Certificate` objects: ++ +.Example `issuer.yaml` file +[source,yaml] +---- +apiVersion: cert-manager.io/v1 +kind: Issuer <1> +metadata: + name: selfsigned + namespace: <2> +spec: + selfSigned: {} +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: istio-ca + namespace: +spec: + isCA: true + duration: 87600h # 10 years + secretName: istio-ca + commonName: istio-ca + privateKey: + algorithm: ECDSA + size: 256 + subject: + organizations: + - cluster.local + - cert-manager + issuerRef: + name: selfsigned + kind: Issuer <1> + group: cert-manager.io +--- +kind: Issuer +metadata: + name: istio-ca + namespace: <2> +spec: + ca: + secretName: istio-ca +---- +<1> Specify the `Issuer` or `ClusterIssuer`. +<2> Specify the name of the Istio project. + +.Verification + +* Verify that the Issuer is created and ready to use by running the following command: ++ +[source,terminal] +---- +$ oc get issuer istio-ca -n +---- ++ +.Example output +[source,terminal] +---- +NAME READY AGE +istio-ca True 3m +---- diff --git a/modules/cert-manager-istio-csr-installing.adoc b/modules/cert-manager-istio-csr-installing.adoc new file mode 100644 index 000000000000..75fdf33ccd83 --- /dev/null +++ b/modules/cert-manager-istio-csr-installing.adoc @@ -0,0 +1,117 @@ +// Module included in the following assemblies: +// +// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cert-manager-istio-csr-installing_{context}"] += Creating the `IstioCSR` custom resource + +Use this procedure to install the Istio-CSR agent through {cert-manager-operator}. + +.Prerequisites + +* You have access to the cluster with `cluster-admin` privileges. +* You have enabled the Istio-CSR feature. +* You have created the `Issuer` or `ClusterIssuer` resources required for generating certificates for the Istio-CSR agent. ++ +[NOTE] +==== +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. +==== + +.Procedure + +. Create a new project for installing Istio-CSR by running the following command. You can use an existing project and skip this step. ++ +[source,terminal] +---- +$ oc new-project +---- + +. 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. ++ +[NOTE] +==== +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. + +* If multiple `IstioCSR` CRs are created simultaneously, none will be processed. +* If multiple `IstioCSR` CRs are created sequentially, only the first one will be processed. +* To prevent new requests from being rejected, delete any unprocessed `IstioCSR` CRs. +* 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. +==== + +.. Create a YAML file, for example, `istiocsr.yaml`, that defines the `IstioCSR` object: ++ +.Example `IstioCSR.yaml` file +[source,yaml] +---- +apiVersion: operator.openshift.io/v1alpha1 +kind: IstioCSR +metadata: + name: default + namespace: +spec: + IstioCSRConfig: + certManager: + issuerRef: + name: istio-ca <1> + kind: Issuer <2> + group: cert-manager.io + istiodTLSConfig: + trustDomain: cluster.local + istio: + namespace: istio-system +---- +<1> Specify the `Issuer` or `ClusterIssuer` name. It should be the same name as the CA issuer defined in the `issuer.yaml` file. +<2> Specify the `Issuer` or `ClusterIssuer` kind. It should be the same kind as the CA issuer defined in the `issuer.yaml` file. + +.. Create the `IstioCSR` custom resource by running the following command: ++ +[source,terminal] +---- +$ oc create -f IstioCSR.yaml +---- + +.Verification + +. Verify that the Istio-CSR deployment is ready by running the following command: ++ +[source,terminal] +---- +$ oc get deployment -n +---- ++ +.Example output +[source,terminal] +---- +NAME READY UP-TO-DATE AVAILABLE AGE +cert-manager-istio-csr 1/1 1 1 24s +---- + +. Verify that the Istio-CSR pods are running by running the following command: ++ +[source,terminal] +---- +$ oc get pod -n +---- ++ +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +cert-manager-istio-csr-5c979f9b7c-bv57w 1/1 Running 0 45s +---- + +** Verify that the Istio-CSR pod is not reporting any errors in the logs by running the following command: ++ +[source,terminal] +---- +$ oc -n logs +---- + +** Verify that the {cert-manager-operator} pod is not reporting any errors by running the following command: ++ +[source,terminal] +---- +$ oc -n cert-manager-operator logs +---- \ No newline at end of file diff --git a/modules/cert-manager-istio-csr-uninstalling.adoc b/modules/cert-manager-istio-csr-uninstalling.adoc new file mode 100644 index 000000000000..440fc3763bbd --- /dev/null +++ b/modules/cert-manager-istio-csr-uninstalling.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cert-manager-istio-csr-uninstalling_{context}"] += Uninstalling the Istio-CSR agent managed by {cert-manager-operator} + +Use this procedure to uninstall the Istio-CSR agent managed by {cert-manager-operator}. + +.Prerequisites + +* You have access to the cluster with `cluster-admin` privileges. +* You have enabled the Istio-CSR feature. +* You have created the `IstioCSR` custom resource. + +.Procedure + +. Remove the `IstioCSR` custom resource by running the following command: ++ +[source,terminal] +---- +$ oc -n delete istiocsrs.operator.openshift.io default +---- + +. Remove related resources: ++ +[IMPORTANT] +==== +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. +==== + +.. List the cluster scoped-resources by running the following command and save the names of the listed resources for later reference: ++ +[source,terminal] +---- +$ oc get clusterrolebindings,clusterroles -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" +---- + +.. List the resources in Istio-csr deployed namespace by running the following command and save the names of the listed resources for later reference: ++ +[source,terminal] +---- +$ oc get certificate,deployments,services,serviceaccounts -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n +---- + +.. 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: ++ +[source,terminal] +---- +$ oc get roles,rolebindings -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n +---- + +.. For each resource listed in previous steps, delete the resource by running the following command: ++ +[source,terminal] +---- +$ oc -n delete / +---- ++ +Repeat this process until all of the related resources have been deleted. diff --git a/modules/cert-manager-istio-csr-updating.adoc b/modules/cert-manager-istio-csr-updating.adoc new file mode 100644 index 000000000000..ae71dcc8a211 --- /dev/null +++ b/modules/cert-manager-istio-csr-updating.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc + +:_mod-docs-content-type: CONCEPT +[id="cert-manager-istio-csr-updating_{context}"] += Upgrading the {cert-manager-operator} with Istio-CSR feature enabled + +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. \ No newline at end of file diff --git a/security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc b/security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc new file mode 100644 index 000000000000..cfaf8bc15c03 --- /dev/null +++ b/security/cert_manager_operator/cert-manager-operator-integrating-istio.adoc @@ -0,0 +1,37 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cert-manager-operator-integrating-istio"] += Integrating the {cert-manager-operator} with Istio-CSR +include::_attributes/common-attributes.adoc[] +:context: cert-manager-operator-integrating-istio + +toc::[] + +:FeatureName: Istio-CSR integration for {cert-manager-operator} +include::snippets/technology-preview.adoc[] + +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. + +With this Istio-CSR integration, Istio can now obtain certificates from the {cert-manager-operator}, simplifying security and certificate management. + +[id="cert-manager-operator-istio-csr-installing_{context}"] +== Installing the Istio-CSR agent through {cert-manager-operator} + +// Enabling Istio-CSR +include::modules/cert-manager-enabling-istio.adoc[leveloffset=+2] + +// Creating issuer +include::modules/cert-manager-istio-creating-issuer.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../../security/cert_manager_operator/index.adoc#cert-manager-issuer-types_cert-manager-operator-about[{cert-manager-operator} issuer providers] + +// Installing using Istio-CSR +include::modules/cert-manager-istio-csr-installing.adoc[leveloffset=+2] + +// Uninstalling cert-manager Operator with Istio-CSR +include::modules/cert-manager-istio-csr-uninstalling.adoc[leveloffset=+1] + +// Updating Istio-CSR +include::modules/cert-manager-istio-csr-updating.adoc[leveloffset=+1] \ No newline at end of file diff --git a/security/cert_manager_operator/cert-manager-operator-uninstall.adoc b/security/cert_manager_operator/cert-manager-operator-uninstall.adoc index 7b41223b021d..8e5976ddaa7c 100644 --- a/security/cert_manager_operator/cert-manager-operator-uninstall.adoc +++ b/security/cert_manager_operator/cert-manager-operator-uninstall.adoc @@ -12,4 +12,4 @@ You can remove the {cert-manager-operator} from {product-title} by uninstalling include::modules/cert-manager-uninstall-console.adoc[leveloffset=+1] // Removing {cert-manager-operator} resources -include::modules/cert-manager-remove-resources-console.adoc[leveloffset=+1] +include::modules/cert-manager-remove-resources-console.adoc[leveloffset=+1] \ No newline at end of file