From a251e4c22f940a1efd72aebc2584ad1ab64eb180 Mon Sep 17 00:00:00 2001 From: Julie Stickler Date: Wed, 2 Dec 2020 17:40:14 -0500 Subject: [PATCH] OSSMDOC-162 Resolve headings generating errors. --- _topic_map.yml | 4 ++++ modules/ossm-security-cert-manage-1x.adoc | 20 ++++++++++---------- modules/ossm-security-cert-manage.adoc | 22 +++++++++++----------- service_mesh/v1x/installing-ossm.adoc | 14 -------------- service_mesh/v1x/ossm-architecture.adoc | 16 ++++++++-------- 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 +++++++++++++ 9 files changed, 65 insertions(+), 62 deletions(-) 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 c21f2a5e54b2..534d56bc032a 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2245,6 +2245,8 @@ Topics: File: ossm-extensions - Name: Using the 3scale Istio adapter File: threescale-adapter + - Name: Removing Service Mesh + File: removing-ossm - Name: Service Mesh 1.x Dir: v1x Topics: @@ -2272,6 +2274,8 @@ Topics: File: ossm-custom-resources - 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 index 83bfa495cb34..839ed8a84a89 100644 --- a/modules/ossm-security-cert-manage-1x.adoc +++ b/modules/ossm-security-cert-manage-1x.adoc @@ -21,7 +21,7 @@ To use an existing signing (CA) certificate and key, you must create a chain of 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. -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,7 +30,7 @@ $ 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 `global.mtls.enabled` to `true` and `security.selfSigned` set to `false`. {ProductShortName} reads the certificates and key from the secret-mount files. + [source,yaml] ---- @@ -45,7 +45,7 @@ spec: selfSigned: false ---- + -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 +57,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 +80,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 +99,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 +123,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,14 +146,14 @@ $ 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] ---- diff --git a/modules/ossm-security-cert-manage.adoc b/modules/ossm-security-cert-manage.adoc index a1be267979f5..2f5a6c738859 100644 --- a/modules/ossm-security-cert-manage.adoc +++ b/modules/ossm-security-cert-manage.adoc @@ -20,7 +20,7 @@ To use an existing signing (CA) certificate and key, you must create a chain of 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] ---- @@ -29,7 +29,7 @@ $ oc create secret generic cacerts -n istio-system --from-file=/ca-cert.pe --from-file=/cert-chain.pem ---- + -2. 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. +. 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] ---- @@ -44,10 +44,10 @@ spec: istiod: type: PrivateKey privateKey: - rootCADir: /etc/cacerts + 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] ---- @@ -59,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] ---- @@ -82,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] ---- @@ -101,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] ---- @@ -125,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] ---- @@ -148,14 +148,14 @@ $ 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] ---- diff --git a/service_mesh/v1x/installing-ossm.adoc b/service_mesh/v1x/installing-ossm.adoc index 261c24607ab4..6d743249bdbe 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-1x_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/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 285c08ef16c0..307248f2740d 100644 --- a/service_mesh/v2x/installing-ossm.adoc +++ b/service_mesh/v2x/installing-ossm.adoc @@ -32,12 +32,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` profiles. For more information, see xref:../../service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc#ossm-control-plane-profiles_deploying-applications-ossm[Creating control plane profiles]. - include::modules/ossm-member-roll-create.adoc[leveloffset=+1] include::modules/ossm-member-roll-modify.adoc[leveloffset=+1] @@ -49,19 +47,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-v2x[Customize the {ProductName} installation]. diff --git a/service_mesh/v2x/ossm-architecture.adoc b/service_mesh/v2x/ossm-architecture.adoc index 9d772ab6945c..70a04f15be08 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]