From 15ec26371ff347984bf367531d5c572d3d25a820 Mon Sep 17 00:00:00 2001 From: Julie Stickler Date: Wed, 2 Dec 2020 17:40:14 -0500 Subject: [PATCH] Manual cherry pick #27812 to 4.5 branch. --- _topic_map.yml | 2 + modules/ossm-security-cert-manage-1x.adoc | 169 ++++++++++++++++++++++ modules/ossm-security-cert-manage.adoc | 54 ++++--- service_mesh/v1x/installing-ossm.adoc | 14 -- service_mesh/v1x/ossm-architecture.adoc | 16 +- service_mesh/v1x/ossm-security.adoc | 2 +- service_mesh/v1x/removing-ossm.adoc | 13 ++ service_mesh/v2x/installing-ossm.adoc | 13 -- service_mesh/v2x/ossm-architecture.adoc | 12 +- service_mesh/v2x/removing-ossm.adoc | 13 ++ 10 files changed, 238 insertions(+), 70 deletions(-) create mode 100644 modules/ossm-security-cert-manage-1x.adoc create mode 100644 service_mesh/v1x/removing-ossm.adoc create mode 100644 service_mesh/v2x/removing-ossm.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 0d210b660fcf..ba826675f81b 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2193,6 +2193,8 @@ Topics: File: ossm-traffic-manage - Name: Using the 3scale Istio adapter File: threescale-adapter + - Name: Removing Service Mesh + File: removing-ossm --- Name: Jaeger Dir: jaeger diff --git a/modules/ossm-security-cert-manage-1x.adoc b/modules/ossm-security-cert-manage-1x.adoc new file mode 100644 index 000000000000..839ed8a84a89 --- /dev/null +++ b/modules/ossm-security-cert-manage-1x.adoc @@ -0,0 +1,169 @@ +// Module included in the following assemblies: +// +// * service_mesh/v1x/ossm-security.adoc + + +[id="ossm-cert-manage_{context}"] += Adding an external certificate authority key and certificate + +By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the user-defined certificate and key to sign workload certificates, with user-defined root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}. + +.Prerequisites + +* You must have installed {ProductName} with mutual TLS enabled to configure certificates. +* This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority. +* You must deploy the Bookinfo sample application to verify the results with these instructions. + +[id="ossm-cert-manage-add-cert-key_{context}"] +== Adding an existing certificate and key + +To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is called `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is called `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file. + +Add the certificates to {ProductShortName} by following these steps. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-1.1/samples/certs[Maistra repo] locally and replace `` with the path to your certificates. + +. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`. ++ +[source,terminal] +---- +$ oc create secret generic cacerts -n istio-system --from-file=/ca-cert.pem \ + --from-file=/ca-key.pem --from-file=/root-cert.pem \ + --from-file=/cert-chain.pem +---- ++ +. In the `ServiceMeshControlPlane` resource set `global.mtls.enabled` to `true` and `security.selfSigned` set to `false`. {ProductShortName} reads the certificates and key from the secret-mount files. ++ +[source,yaml] +---- +apiVersion: maistra.io/v1 +kind: ServiceMeshControlPlane +spec: + istio: + global: + mtls: + enabled: true + security: + selfSigned: false +---- ++ +. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads. ++ +[source,terminal] +---- +$ oc delete secret istio.default +---- + +[id="ossm-cert-manage-verify-cert_{context}"] +== Verifying your certificates + +Use the Bookinfo sample application to verify your certificates are mounted correctly. First, retrieve the mounted certificates. Then, verify the certificates mounted on the pod. + +. Store the pod name in the variable `RATINGSPOD`. ++ +[source,terminal] +---- +$ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'` +---- ++ +. Run the following commands to retrieve the certificates mounted on the proxy. ++ +[source,terminal] +---- +$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem +---- ++ +The file `/tmp/pod-root-cert.pem` contains the root certificate propagated to the pod. ++ +[source,terminal] +---- +$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem +---- ++ +The file `/tmp/pod-cert-chain.pem` contains the workload certificate and the CA certificate propagated to the pod. ++ +. Verify the root certificate is the same as the one specified by the Operator. Replace `` with the path to your certificates. ++ +[source,terminal] +---- +$ openssl x509 -in /root-cert.pem -text -noout > /tmp/root-cert.crt.txt +---- ++ +[source,terminal] +---- +$ openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt +---- ++ +[source,terminal] +---- +$ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt +---- ++ +Expect the output to be empty. ++ +. Verify the CA certificate is the same as the one specified by Operator. Replace `` with the path to your certificates. ++ +[source,terminal] +---- +$ sed '0,/^-----END CERTIFICATE-----/d' /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem +---- ++ +[source,terminal] +---- +$ openssl x509 -in /ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt +---- ++ +[source,terminal] +---- +$ openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt +---- ++ +[source,terminal] +---- +$ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt +---- ++ +Expect the output to be empty. ++ +. Verify the certificate chain from the root certificate to the workload certificate. Replace `` with the path to your certificates. ++ +[source,terminal] +---- +$ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem +---- ++ +[source,terminal] +---- +$ openssl verify -CAfile <(cat /ca-cert.pem /root-cert.pem) /tmp/pod-cert-chain-workload.pem +---- ++ +.Example output +[source,terminal] +---- +/tmp/pod-cert-chain-workload.pem: OK +---- + +[id="ossm-cert-cleanup_{context}"] +== Removing the certificates + +To remove the certificates you added, follow these steps. + +. Remove the secret `cacerts`. ++ +[source,terminal] +---- +$ oc delete secret cacerts -n istio-system +---- ++ +. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource. ++ +[source,yaml] +---- +apiVersion: maistra.io/v1 +kind: ServiceMeshControlPlane +spec: + istio: + global: + mtls: + enabled: true + security: + selfSigned: true +---- diff --git a/modules/ossm-security-cert-manage.adoc b/modules/ossm-security-cert-manage.adoc index 89e64b1cf452..2f5a6c738859 100644 --- a/modules/ossm-security-cert-manage.adoc +++ b/modules/ossm-security-cert-manage.adoc @@ -1,17 +1,16 @@ // Module included in the following assemblies: // -// * service_mesh/v1x/ossm-security.adoc // * service_mesh/v2x/ossm-security.adoc [id="ossm-cert-manage_{context}"] = Adding an external certificate authority key and certificate -By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the Operator-specified certificate and key to sign workload certificates, with Operator-specified root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}. +By default, {ProductName} generates self-signed root certificate and key, and uses them to sign the workload certificates. You can also use the user-defined certificate and key to sign workload certificates, with user-defined root certificate. This task demonstrates an example to plug certificates and key into {ProductShortName}. .Prerequisites * You must have installed {ProductName} with mutual TLS enabled to configure certificates. -* This example uses the certificates from link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repo]. For production, use your own certificates from your certificate authority. +* This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority. * You must deploy the Bookinfo sample application to verify the results with these instructions. [id="ossm-cert-manage-add-cert-key_{context}"] @@ -19,9 +18,9 @@ By default, {ProductName} generates self-signed root certificate and key, and us To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is called `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is called `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file. -Add the certificates to {ProductShortName} by following these steps. Save the certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repo] locally and replace `` with the path to your certificates. +Add the certificates to {ProductShortName} by following these steps. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-2.0/samples/certs[Maistra repo] locally and replace `` with the path to your certificates. -1. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`. +. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`. + [source,terminal] ---- @@ -30,22 +29,25 @@ $ oc create secret generic cacerts -n istio-system --from-file=/ca-cert.pe --from-file=/cert-chain.pem ---- + -2. In the `ServiceMeshControlPlane` resource set `global.mtls.enabled` to `true` and `security.selfSigned` set to `false`. {ProductShortName} reads the certificates and key from the secret-mount files. +. In the `ServiceMeshControlPlane` resource set `spec.security.dataPlane.mtls: true` to `true` and configure your certificateAuthority like the following example. The default `rootCADir` is `/etc/cacerts`. You do not need to set the `privateKey` if the key and certs are mounted in the default location. {ProductShortName} reads the certificates and key from the secret-mount files. + [source,yaml] ---- -apiVersion: maistra.io/v1 +apiVersion: maistra.io/v2 kind: ServiceMeshControlPlane spec: - istio: - global: - mtls: - enabled: true - security: - selfSigned: false + security: + dataPlane: + mtls: true + certificateAuthority: + type: Istiod + istiod: + type: PrivateKey + privateKey: + rootCADir: /etc/cacerts ---- + -3. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads. +. To make sure the workloads add the new certificates promptly, delete the secrets generated by {ProductShortName}, named `istio.*`. In this example, `istio.default`. {ProductShortName} issues new certificates for the workloads. + [source,terminal] ---- @@ -57,14 +59,14 @@ $ oc delete secret istio.default Use the Bookinfo sample application to verify your certificates are mounted correctly. First, retrieve the mounted certificates. Then, verify the certificates mounted on the pod. -1. Store the pod name in the variable `RATINGSPOD`. +. Store the pod name in the variable `RATINGSPOD`. + [source,terminal] ---- $ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'` ---- + -Run the following commands to retrieve the certificates mounted on the proxy. +. Run the following commands to retrieve the certificates mounted on the proxy. + [source,terminal] ---- @@ -80,7 +82,7 @@ $ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > + The file `/tmp/pod-cert-chain.pem` contains the workload certificate and the CA certificate propagated to the pod. + -3. Verify the root certificate is the same as the one specified by the Operator. Replace `` with the path to your certificates. +. Verify the root certificate is the same as the one specified by the Operator. Replace `` with the path to your certificates. + [source,terminal] ---- @@ -99,7 +101,7 @@ $ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt + Expect the output to be empty. + -4. Verify the CA certificate is the same as the one specified by Operator. Replace `` with the path to your certificates. +. Verify the CA certificate is the same as the one specified by Operator. Replace `` with the path to your certificates. + [source,terminal] ---- @@ -123,7 +125,7 @@ $ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt + Expect the output to be empty. + -5. Verify the certificate chain from the root certificate to the workload certificate. Replace `` with the path to your certificates. +. Verify the certificate chain from the root certificate to the workload certificate. Replace `` with the path to your certificates. + [source,terminal] ---- @@ -146,24 +148,20 @@ $ openssl verify -CAfile <(cat /ca-cert.pem /root-cert.pem) /tmp/pod To remove the certificates you added, follow these steps. -1. Remove the secret `cacerts`. +. Remove the secret `cacerts`. + [source,terminal] ---- $ oc delete secret cacerts -n istio-system ---- + -2. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource. +. Redeploy {ProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource. + [source,yaml] ---- -apiVersion: maistra.io/v1 +apiVersion: maistra.io/v2 kind: ServiceMeshControlPlane spec: - istio: - global: - mtls: - enabled: true - security: - selfSigned: true + dataPlane: + mtls: true ---- diff --git a/service_mesh/v1x/installing-ossm.adoc b/service_mesh/v1x/installing-ossm.adoc index 5746f58d0a79..6546c7119601 100644 --- a/service_mesh/v1x/installing-ossm.adoc +++ b/service_mesh/v1x/installing-ossm.adoc @@ -37,13 +37,10 @@ include::modules/ossm-install-kiali.adoc[leveloffset=+1] include::modules/ossm-install-ossm-operator.adoc[leveloffset=+1] - - include::modules/ossm-control-plane-deploy-1x.adoc[leveloffset=+1] For a multitenant installation, {ProductName} supports multiple independent control planes within the cluster. You can create reusable configurations with `ServiceMeshControlPlane` templates. For more information, see xref:../../service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc#ossm-control-plane-templates_deploying-applications-ossm-v1x[Creating control plane templates]. - include::modules/ossm-member-roll-create.adoc[leveloffset=+1] include::modules/ossm-member-roll-modify.adoc[leveloffset=+1] @@ -55,19 +52,8 @@ OLM uses CatalogSources, which use the Operator Registry API, to query for avail * For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-overview_olm-understanding-olm[Operator Lifecycle Manager] documentation. - include::modules/ossm-update-app-sidecar.adoc[leveloffset=+2] -= Removing {ProductName} - -This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. - -include::modules/ossm-member-roll-delete.adoc[leveloffset=+2] - -include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] - -include::modules/ossm-operatorhub-remove.adoc[leveloffset=+1] - == Next steps * xref:../../service_mesh/v1x/customizing-installation-ossm.adoc#customize-installation-ossm-v1x[Customize the {ProductName} installation]. diff --git a/service_mesh/v1x/ossm-architecture.adoc b/service_mesh/v1x/ossm-architecture.adoc index 6ef976ae04f4..95973e84796f 100644 --- a/service_mesh/v1x/ossm-architecture.adoc +++ b/service_mesh/v1x/ossm-architecture.adoc @@ -10,17 +10,17 @@ include::modules/ossm-understanding-service-mesh.adoc[leveloffset=+1] include::modules/ossm-architecture-1x.adoc[leveloffset=+1] -= Understanding Kiali +== Understanding Kiali Kiali provides visibility into your service mesh by showing you the microservices in your service mesh, and how they are connected. -include::modules/ossm-kiali-overview.adoc[leveloffset=+1] +include::modules/ossm-kiali-overview.adoc[leveloffset=+2] -include::modules/ossm-kiali-architecture.adoc[leveloffset=+1] +include::modules/ossm-kiali-architecture.adoc[leveloffset=+2] -include::modules/ossm-kiali-features.adoc[leveloffset=+1] +include::modules/ossm-kiali-features.adoc[leveloffset=+2] -= Understanding Jaeger +== Understanding Jaeger Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate in order to produce a response. The path of this request is a distributed transaction. @@ -34,11 +34,11 @@ Jaeger records the execution of individual requests across the whole stack of mi A *span* represents a logical unit of work in Jaeger that has an operation name, the start time of the operation, and the duration. Spans may be nested and ordered to model causal relationships. -include::modules/jaeger-product-overview.adoc[leveloffset=+1] +include::modules/jaeger-product-overview.adoc[leveloffset=+2] -include::modules/jaeger-architecture.adoc[leveloffset=+1] +include::modules/jaeger-architecture.adoc[leveloffset=+2] -include::modules/jaeger-features.adoc[leveloffset=+1] +include::modules/jaeger-features.adoc[leveloffset=+2] == Next steps diff --git a/service_mesh/v1x/ossm-security.adoc b/service_mesh/v1x/ossm-security.adoc index 69324db33ddb..a9f27a49103e 100644 --- a/service_mesh/v1x/ossm-security.adoc +++ b/service_mesh/v1x/ossm-security.adoc @@ -11,4 +11,4 @@ include::modules/ossm-security-mtls.adoc[leveloffset=+1] include::modules/ossm-security-cipher.adoc[leveloffset=+1] -include::modules/ossm-security-cert-manage.adoc[leveloffset=+1] +include::modules/ossm-security-cert-manage-1x.adoc[leveloffset=+1] diff --git a/service_mesh/v1x/removing-ossm.adoc b/service_mesh/v1x/removing-ossm.adoc new file mode 100644 index 000000000000..0bfd4aec6a59 --- /dev/null +++ b/service_mesh/v1x/removing-ossm.adoc @@ -0,0 +1,13 @@ +[id="removing-ossm-v1x"] += Removing {ProductName} +include::modules/ossm-document-attributes-1x.adoc[] +:context: removing-ossm-v1x +toc::[] + +This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. + +include::modules/ossm-member-roll-delete.adoc[leveloffset=+1] + +include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] + +include::modules/ossm-operatorhub-remove.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/installing-ossm.adoc b/service_mesh/v2x/installing-ossm.adoc index 15de4ddf798d..97faa93b981c 100644 --- a/service_mesh/v2x/installing-ossm.adoc +++ b/service_mesh/v2x/installing-ossm.adoc @@ -37,12 +37,10 @@ include::modules/ossm-install-kiali.adoc[leveloffset=+1] include::modules/ossm-install-ossm-operator.adoc[leveloffset=+1] - include::modules/ossm-control-plane-deploy.adoc[leveloffset=+1] For a multitenant installation, {ProductName} supports multiple independent control planes within the cluster. You can create reusable configurations with `ServiceMeshControlPlane` templates. For more information, see xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-control-plane-templates_deploying-applications-ossm[Creating control plane templates]. - include::modules/ossm-member-roll-create.adoc[leveloffset=+1] include::modules/ossm-member-roll-modify.adoc[leveloffset=+1] @@ -54,19 +52,8 @@ OLM uses CatalogSources, which use the Operator Registry API, to query for avail * For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-overview_olm-understanding-olm[Operator Lifecycle Manager] documentation. - include::modules/ossm-update-app-sidecar.adoc[leveloffset=+2] -= Removing {ProductName} - -This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. - -include::modules/ossm-member-roll-delete.adoc[leveloffset=+2] - -include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] - -include::modules/ossm-operatorhub-remove.adoc[leveloffset=+1] - == Next steps * xref:../../service_mesh/v2x/customizing-installation-ossm.adoc#customize-installation-ossm[Customize the {ProductName} installation]. diff --git a/service_mesh/v2x/ossm-architecture.adoc b/service_mesh/v2x/ossm-architecture.adoc index 02b02f111cf8..c247a1fbc8e8 100644 --- a/service_mesh/v2x/ossm-architecture.adoc +++ b/service_mesh/v2x/ossm-architecture.adoc @@ -14,11 +14,11 @@ include::modules/ossm-architecture.adoc[leveloffset=+1] Kiali provides visibility into your service mesh by showing you the microservices in your service mesh, and how they are connected. -include::modules/ossm-kiali-overview.adoc[leveloffset=+1] +include::modules/ossm-kiali-overview.adoc[leveloffset=+2] -include::modules/ossm-kiali-architecture.adoc[leveloffset=+1] +include::modules/ossm-kiali-architecture.adoc[leveloffset=+2] -include::modules/ossm-kiali-features.adoc[leveloffset=+1] +include::modules/ossm-kiali-features.adoc[leveloffset=+2] = Understanding Jaeger @@ -34,11 +34,11 @@ Jaeger records the execution of individual requests across the whole stack of mi A *span* represents a logical unit of work in Jaeger that has an operation name, the start time of the operation, and the duration. Spans may be nested and ordered to model causal relationships. -include::modules/jaeger-product-overview.adoc[leveloffset=+1] +include::modules/jaeger-product-overview.adoc[leveloffset=+2] -include::modules/jaeger-architecture.adoc[leveloffset=+1] +include::modules/jaeger-architecture.adoc[leveloffset=+2] -include::modules/jaeger-features.adoc[leveloffset=+1] +include::modules/jaeger-features.adoc[leveloffset=+2] == Next steps diff --git a/service_mesh/v2x/removing-ossm.adoc b/service_mesh/v2x/removing-ossm.adoc new file mode 100644 index 000000000000..0118f63a769e --- /dev/null +++ b/service_mesh/v2x/removing-ossm.adoc @@ -0,0 +1,13 @@ +[id="removing-ossm"] += Removing {ProductName} +include::modules/ossm-document-attributes.adoc[] +:context: removing-ossm +toc::[] + +This process allows you to remove {ProductName} from an existing {product-title} instance. Remove the control plane before removing the operators. + +include::modules/ossm-member-roll-delete.adoc[leveloffset=+1] + +include::modules/ossm-control-plane-remove.adoc[leveloffset=+1] + +include::modules/ossm-operatorhub-remove.adoc[leveloffset=+1]