diff --git a/install/ossm-cert-manager.adoc b/install/ossm-cert-manager.adoc index 8db3dbb6e8c7..902c9eb6c8db 100644 --- a/install/ossm-cert-manager.adoc +++ b/install/ossm-cert-manager.adoc @@ -10,37 +10,27 @@ toc::[] 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. +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. + [IMPORTANT] ==== The cert-manager tool must be installed before you create and install your `Istio` resource. ==== -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. - include::modules/ossm-about-cert-manager.adoc[leveloffset=+1] -include::modules/ossm-installing-cert-manager.adoc[leveloffset=+1] - -.Next steps -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`. - -* 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] -* 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] - -include::modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc[leveloffset=+2] +include::modules/ossm-installing-cert-manager.adoc[leveloffset=+2] +include::modules/ossm-verifying-cert-manager.adoc[leveloffset=+2] +include::modules/ossm-uninstalling-cert-manager.adoc[leveloffset=+2] -.Next steps -* xref:../install/ossm-cert-manager.adoc#installing-istio-resource_ossm-cert-manager[Installing your Istio resource] -include::modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc[leveloffset=+2] - -[id="additional-resources_{context}"] +[role="_additional-resources"] .Additional resources -* link:https://github.com/cert-manager/istio-csr/tree/main/deploy/charts/istio-csr#appistiorevisions0--string[istio-csr deployment] - - -.Next steps -* xref:../install/ossm-cert-manager.adoc#installing-istio-resource_ossm-cert-manager[Installing your Istio resource] - -include::modules/ossm-cert-manager-installing-istio-resource.adoc[leveloffset=+2] -include::modules/ossm-cert-manager-verifying-install.adoc[leveloffset=+2] -include::modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc[leveloffset=+1] +* 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] +* 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] + +//include::modules/ossm-cert-manager-istio-csr-inplace-update-strategy.adoc[leveloffset=+2] +//include::modules/ossm-cert-manager-istio-csr-revisionbased-strategy.adoc[leveloffset=+2] +//include::modules/ossm-cert-manager-installing-istio-resource.adoc[leveloffset=+2] +//include::modules/ossm-cert-manager-verifying-install.adoc[leveloffset=+2] +//include::modules/ossm-cert-manager-update-istio-csr-revisionbased-only.adoc[leveloffset=+1] +//The above modules are no longer valid for 3.0 diff --git a/modules/ossm-about-cert-manager.adoc b/modules/ossm-about-cert-manager.adoc index 52dfdcdef6b9..8c1ae510aa03 100644 --- a/modules/ossm-about-cert-manager.adoc +++ b/modules/ossm-about-cert-manager.adoc @@ -4,32 +4,15 @@ :_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. += About the cert-manager Operator istio-csr agent -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 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. [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. \ No newline at end of file +The {cert-manager-operator} must be installed before you create and install your `{istio}` resource. +==== \ No newline at end of file diff --git a/modules/ossm-installing-cert-manager.adoc b/modules/ossm-installing-cert-manager.adoc index 96e314f48b36..f5cc257d3d93 100644 --- a/modules/ossm-installing-cert-manager.adoc +++ b/modules/ossm-installing-cert-manager.adoc @@ -1,20 +1,20 @@ // Module included in the following assemblies: // -// * service-mesh-docs-main/install/ossm-installing-openshift-service-mesh.adoc +// * service-mesh-docs-main/install/ossm-cert-manager.adoc :_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. += Integrating Service Mesh with the cert-manager Operator by using the istio-csr agent -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. +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. -[IMPORTANT] -==== -You must install cert-manager before installing your `Istio` resource. -==== +.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 a `IstioCNI` instance running in the cluster. +* You have installed the `istioctl` command. .Procedure @@ -25,10 +25,31 @@ 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] ---- @@ -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: @@ -70,9 +91,8 @@ metadata: spec: ca: secretName: istio-ca ---- ---- -+ + .. Create the objects by running the following command: + [source, terminal] @@ -80,7 +100,7 @@ spec: ---- $ oc apply -f issuer.yaml ---- -+ + .. Wait for the `istio-ca` certificate to contain the "Ready" status condition by running the following command: + [source, terminal] @@ -88,18 +108,85 @@ $ oc apply -f issuer.yaml $ 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: + -.. Copy the secret to a local file by running the following command: +.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 that the `istio-csr` deployment is ready by running the following command: + [source, terminal] ++ ---- -$ oc get -n istio-system secret istio-ca -o jsonpath='{.data.tls\.crt}' | base64 -d > ca.pem +$ 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 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. +==== + +.. Create the `{istio}` object similar to the following example: + -.. Create a secret from the local certificate file in the `cert-manager` namespace by running the following command: +.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 +---- + +.. Verify that the `istio` resource displays the "Ready" status condition by running the following command: + [source, terminal] ---- -$ oc create secret generic -n cert-manager istio-root-ca --from-file=ca.pem=ca.pem +$ oc wait --for=condition=Ready istios/default -n istio-system ---- \ No newline at end of file diff --git a/modules/ossm-uninstalling-cert-manager.adoc b/modules/ossm-uninstalling-cert-manager.adoc new file mode 100644 index 000000000000..16547b7b183c --- /dev/null +++ b/modules/ossm-uninstalling-cert-manager.adoc @@ -0,0 +1,56 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-cert-manager.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-uninstalling-cert-manager_{context}"] += Uninstalling Service Mesh with the cert-manager Operator by using the istio-csr agent + +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. + +.Procedure + +. Remove the `IstioCSR` custom resource by running the following command: ++ +[source, terminal] +---- +$ oc -n delete istiocsrs.operator.openshift.io default +---- + +. Remove the related resources: + +.. List the cluster scoped-resources by running the following command: ++ +[source, terminal] +---- +$ oc get clusterrolebindings,clusterroles -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" +---- ++ +Save the names of the listed resources for later reference. + +.. List the resources in `istio-csr` agent deployed namespace by running the following command: ++ +[source, terminal] +---- +$ oc get certificate,deployments,services,serviceaccounts -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" -n +---- ++ +Save the names of the listed resources for later reference. + +.. List the resources in {SMProductName} or {istio} deployed namespaces by running the following command: ++ +[source, terminal] +---- +$ oc get roles,rolebindings \ + -l "app=cert-manager-istio-csr,app.kubernetes.io/name=cert-manager-istio-csr" \ + -n +---- ++ +Save the names of the listed resources for later reference. + +.. For each resource listed in previous steps, delete the resources by running the following command: ++ +[source, terminal] +---- +$ oc -n delete / +---- \ No newline at end of file diff --git a/modules/ossm-verifying-cert-manager.adoc b/modules/ossm-verifying-cert-manager.adoc new file mode 100644 index 000000000000..372c6ec8565a --- /dev/null +++ b/modules/ossm-verifying-cert-manager.adoc @@ -0,0 +1,185 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/install/ossm-cert-manager.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-verifying-cert-manager_{context}"] += Verifying Service Mesh with the cert-manager Operator using the istio-csr agent + +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 Operator 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 +---- + +. Add the `istio-injection=enabled` label on the namespaces: + +.. Add the `istio-injection=enabled` label on the `apps-1` namespace by running the following command: ++ +[source, terminal] +---- +$ oc label namespaces apps-1 istio-injection=enabled +---- + +.. Add the `istio-injection=enabled` label 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 functions between workloads. +==== ++ +.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: ++ +[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-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: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] +---- +$ 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 +---- ++ +.Example output ++ +[source, terminal] +---- +... +Issuer: O = cert-manager + O = cluster.local, CN = istio-ca +... +X509v3 Subject Alternative Name: +URI:spiffe://cluster.local/ns/apps-1/sa/httpbin +---- \ No newline at end of file diff --git a/snippets/technology-preview-istiocsr.adoc b/snippets/technology-preview-istiocsr.adoc new file mode 100644 index 000000000000..dd0c94d8b41f --- /dev/null +++ b/snippets/technology-preview-istiocsr.adoc @@ -0,0 +1,12 @@ +// snippet included in the following modules: +// +// * service-mesh-docs-main/modules/ossm-about-cert-manager.adoc +// * service-mesh-docs-main/modules/ossm-installing-cert-manager.adoc + + +[IMPORTANT] +==== +`istio-csr` integration for {cert-manager-operator} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. +==== \ No newline at end of file