diff --git a/modules/ossm-cert-manage-verify-cert.adoc b/modules/ossm-cert-manage-verify-cert.adoc index 349754acfc95..b8077754f139 100644 --- a/modules/ossm-cert-manage-verify-cert.adoc +++ b/modules/ossm-cert-manage-verify-cert.adoc @@ -4,9 +4,9 @@ :_content-type: PROCEDURE [id="ossm-cert-manage-verify-cert_{context}"] -== Verifying your certificates += Verifying your certificates -Use the Bookinfo sample application to verify that the workload certificates are signed by the certificates that were plugged into the CA. This requires you have `openssl` installed on your machine +Use the Bookinfo sample application to verify that the workload certificates are signed by the certificates that were plugged into the CA. This process requires that you have `openssl` installed on your machine. . To extract certificates from bookinfo workloads use the following command: + diff --git a/modules/ossm-cert-manager-installation.adoc b/modules/ossm-cert-manager-installation.adoc new file mode 100644 index 000000000000..f50135ce127d --- /dev/null +++ b/modules/ossm-cert-manager-installation.adoc @@ -0,0 +1,253 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/ossm-security.adoc + +:_content-type: PROCEDURE +[id="ossm-cert-manager-installation_{context}"] += Installing cert-manager + +To install cert-manager, follow these steps: + +.Procedure + +. Create the root cluster issuer: ++ +[source, terminal] +---- +$ oc apply -f cluster-issuer.yaml +---- ++ +[source, terminal] +---- +$ oc apply -n istio-system -f istio-ca.yaml +---- ++ +.Example `cluster-issuer.yaml` +[source, yaml] +---- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-root-issuer + namespace: cert-manager +spec: + selfSigned: {} +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: root-ca + namespace: cert-manager +spec: + isCA: true + duration: 21600h # 900d + secretName: root-ca + commonName: root-ca.my-company.net + subject: + organizations: + - my-company.net + issuerRef: + name: selfsigned-root-issuer + kind: Issuer + group: cert-manager.io +--- +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: root-ca +spec: + ca: + secretName: root-ca +---- ++ +.Example `istio-ca.yaml` +[source, yaml] +---- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: istio-ca + namespace: istio-system +spec: + isCA: true + duration: 21600h + secretName: istio-ca + commonName: istio-ca.my-company.net + subject: + organizations: + - my-company.net + issuerRef: + name: root-ca + kind: ClusterIssuer + group: cert-manager.io +--- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: istio-ca + namespace: istio-system +spec: + ca: + secretName: istio-ca +---- ++ +==== +[NOTE] +The namespace of the `selfsigned-root-issuer` issuer and `root-ca` certificate is `cert-manager` because `root-ca` is a cluster issuer, so the cert-manager looks for a referenced secret in its own namespace. Its own namespace is `cert-manager` in the case of the {cert-manager-operator}. +==== + +. Install `istio-csr`: ++ +[source, terminal] +---- +$ helm install istio-csr jetstack/cert-manager-istio-csr \ + -n istio-system \ + -f deploy/examples/cert-manager/istio-csr/istio-csr.yaml +---- ++ +.Example `istio-csr.yaml` +[source, yaml] +---- +replicaCount: 2 + +image: + repository: quay.io/jetstack/cert-manager-istio-csr + tag: v0.6.0 + pullSecretName: "" + +app: + certmanager: + namespace: istio-system + issuer: + group: cert-manager.io + kind: Issuer + name: istio-ca + + controller: + configmapNamespaceSelector: "maistra.io/member-of=istio-system" + leaderElectionNamespace: istio-system + + istio: + namespace: istio-system + revisions: ["basic"] + + server: + maxCertificateDuration: 5m + + tls: + certificateDNSNames: + # This DNS name must be set in the SMCP spec.security.certificateAuthority.cert-manager.address + - cert-manager-istio-csr.istio-system.svc +---- + +. Deploy SMCP: ++ +[source, terminal] +---- +$ oc apply -f mesh.yaml -n istio-system +---- ++ +.Example `mesh.yaml` +[source, yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic +spec: + addons: + grafana: + enabled: false + kiali: + enabled: false + prometheus: + enabled: false + proxy: + accessLogging: + file: + name: /dev/stdout + security: + certificateAuthority: + cert-manager: + address: cert-manager-istio-csr.istio-system.svc:443 + type: cert-manager + dataPlane: + mtls: true + identity: + type: ThirdParty + tracing: + type: None +--- +apiVersion: maistra.io/v1 +kind: ServiceMeshMemberRoll +metadata: + name: default +spec: + members: + - httpbin + - sleep +---- + +==== +[NOTE] +`security.identity.type: ThirdParty` must be set when `security.certificateAuthority.type: cert-manager` is configured. +==== + +.Verification + +To verify cert-manager is installed, follow these steps: + +. Deploy the HTTP and `sleep` apps: ++ +[source, terminal] +---- +$ oc new-project +---- ++ +[source, terminal] +---- +$ oc apply -f https://raw.githubusercontent.com/maistra/istio/maistra-2.4/samples/httpbin/httpbin.yaml +---- ++ +[source, terminal] +---- +$ oc apply -f https://raw.githubusercontent.com/maistra/istio/maistra-2.4/samples/sleep/sleep.yaml +---- + +. Verify that `sleep` can access the `httpbin` service: ++ +[source, terminal] +---- +$ oc exec "$(oc get pod -l app=sleep -n \ + -o jsonpath={.items..metadata.name})" -c sleep -n -- \ + curl http://httpbin.:8000/ip -s -o /dev/null \ + -w "%{http_code}\n" +---- ++ +.Example output: +[source, terminal] +---- +200 +---- + +. Check mTLS traffic from the ingress gateway to the `httpbin` service: ++ +[source, terminal] +---- +$ oc apply -n -f https://raw.githubusercontent.com/maistra/istio/maistra-2.4/samples/httpbin/httpbin-gateway.yaml +---- + +. Get the `istio-ingressgateway` route: ++ +[source, terminal] +---- +INGRESS_HOST=$(oc -n istio-system get routes istio-ingressgateway -o jsonpath='{.spec.host}') +---- + +. Verify mTLS traffic from the ingress gateway to the `httpbin` service: ++ +[source, terminal] +---- +$ curl -s -I http://$INGRESS_HOST/headers -o /dev/null -w "%{http_code}" -s +---- + diff --git a/modules/ossm-cert-manager-integration-istio.adoc b/modules/ossm-cert-manager-integration-istio.adoc new file mode 100644 index 000000000000..60634446aa69 --- /dev/null +++ b/modules/ossm-cert-manager-integration-istio.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/ossm-security.adoc + +:_content-type: CONCEPT +[id="ossm-cert-manager-integration-istio_{context}"] += About integrating Service Mesh with cert-manager and istio-csr + +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 the certificates are valid and up-to-date by attempting to renew certificates at a configured time before they expire. + +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. + +[NOTE] +==== +Red Hat provides support for integrating with `istio-csr` and cert-manager. Red 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. +==== + +.Prerequisites +* One of these versions of cert-manager: +** {cert-manager-operator} 1.10 or later +** community cert-manager Operator 1.11 or later +** cert-manager 1.11 or later + +* OpenShift Service Mesh Operator 2.4 or later +* `istio-csr` 0.6.0 or later + +[NOTE] +==== +To avoid creating config maps in all namespaces when the `istio-csr` server is installed with the `jetstack/cert-manager-istio-csr` Helm chart, use the following setting: `app.controller.configmapNamespaceSelector: "maistra.io/member-of: "` in the `istio-csr.yaml` file. +==== + + diff --git a/service_mesh/v2x/ossm-security.adoc b/service_mesh/v2x/ossm-security.adoc index a09dceafca4a..07c005c6af34 100644 --- a/service_mesh/v2x/ossm-security.adoc +++ b/service_mesh/v2x/ossm-security.adoc @@ -34,6 +34,22 @@ include::modules/ossm-security-cert-manage.adoc[leveloffset=+1] include::modules/ossm-cert-manage-add-cert-key.adoc[leveloffset=+1] -include::modules/ossm-cert-manage-verify-cert.adoc[leveloffset=+1] +include::modules/ossm-cert-manage-verify-cert.adoc[leveloffset=+2] -include::modules/ossm-cert-cleanup.adoc[leveloffset=+1] \ No newline at end of file +include::modules/ossm-cert-cleanup.adoc[leveloffset=+1] + +include::modules/ossm-cert-manager-integration-istio.adoc[leveloffset=+1] + +include::modules/ossm-cert-manager-installation.adoc[leveloffset=+2] + +[role="_additional-resources"] +[id="additional-resources_cert-manager-operator-red-hat-openshift"] +== Additional resources + +For information about how to install the cert-manager Operator for {product-title}, see: +ifndef::openshift-rosa,openshift-dedicated[] +xref:../../security/cert_manager_operator/cert-manager-operator-install.adoc[Installing the cert-manager Operator for Red Hat OpenShift]. +endif::[] +ifdef::openshift-rosa,openshift-dedicated[] +link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html-single/security_and_compliance/index#cert-manager-operator-install[Installing the cert-manager Operator for Red Hat OpenShift]. +endif::[] \ No newline at end of file