TP12 Modularization Work

_topic_map.yml

@@ -773,16 +773,31 @@ Topics:
 #  Topics:
 #  - Name: CNV Release Notes Placeholder
 #    File: cnv-release-notes-placeholder
-#---
-#Name: Service Mesh
-#Dir: service_mesh
-#Distros: openshift-enterprise
-#Topics:
-#- Name: Service Mesh Installation
-#  Dir: service_mesh_install
-#  Topics:
-#  - Name: Service Mesh Insatll Assemblies Placeholder
-#    File: service-mesh-install-placeholder
+---
+Name: Service Mesh
+Dir: service_mesh
+Distros: openshift-enterprise
+Topics:
+- Name: Service Mesh Installation
+  Dir: service_mesh_install
+  Topics:
+  - Name: Understanding service mesh
+    File: understanding-ossm
+  - Name: Preparing to install service mesh
+    File: preparing-ossm-installation
+  - Name: Installing service mesh
+    File: installing-ossm
+  - Name: Installing a multi-tenant service mesh
+    File: installing-mt-ossm
+  - Name: Deploying applications on service mesh
+    File: prepare-to-deploy-applications-ossm
+  - Name: Removing service mesh
+    File: removing-ossm
+- Name: 3scale adapter
+  Dir: threescale_adapter
+  Topics:
+  - Name: Using the 3scale Istio adapter
+    File: threescale-adapter
 #- Name: Service Mesh Release Notes
 #  Dir: service_mesh_release_notes
 #  Topics:

modules/ossm-architecture.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_install/understanding-ossm.adoc
+
+[id="ossm-architecture_{context}"]
+= {ProductName} Architecture
+
+{ProductName} is logically split into a data plane and a control plane:
+
+The *data plane* is a set of intelligent proxies deployed as sidecars. These proxies intercept and control all inbound and outbound network communication between microservices in the service mesh. Sidecar proxies also communicate with Mixer, the general-purpose policy and telemetry hub.
+
+* *Envoy proxy* intercepts all inbound and outbound traffic for all services in the service mesh. Envoy is deployed as a sidecar to the relevant service in the same pod.
+
+The *control plane* manages and configures proxies to route traffic, and configures Mixers to enforce policies and collect telemetry.
+
+* *Mixer* enforces access control and usage policies (such as authorization, rate limits, quotas, authentication, request tracing) and collects telemetry data from the Envoy proxy and other services.
+* *Pilot* configures the proxies at runtime. Pilot provides service discovery for the Envoy sidecars, traffic management capabilities for intelligent routing (for example, A/B tests or canary deployments), and resiliency (timeouts, retries, and circuit breakers).
+* *Citadel* issues and rotates certificates. Citadel provides strong service-to-service and end-user authentication with built-in identity and credential management. You can use Citadel to upgrade unencrypted traffic in the service mesh. Operators can enforce policies based on service identity rather than on network controls using Citadel.
+* *Galley* ingests the service mesh configuration, then validates, processes, and distributes the configuration. Galley protects the other service mesh components from obtaining user configuration details from {product-title}.
+
+{ProductName} also uses the *istio-operator* to manage the installation of the control plane. An _Operator_ is a piece of software that enables you to implement and automate common activities in your OpenShift cluster. It acts as a controller, allowing you to set or change the desired state of objects in your cluster.

modules/ossm-automatic-sidecar-injection.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
+
+[id="ossm-automatic-sidecar-injection_{context}"]
+= Enabling automatic sidecar injection
+When deploying an application into the {ProductName} you must opt in to injection by specifying the `sidecar.istio.io/inject` annotation with a value of `true`. Opting in ensures that the sidecar injection does not interfere with other OpenShift features such as builder pods used by numerous frameworks within the OpenShift ecosystem.
+
+.Prerequisites
+
+* Identify the deployments for which you want to enable automatic sidecar injection.
+* Locate the application's yaml configuration file.
+
+.Procedure
+
+. Open the application's configuration yaml file in an editor.
+
+. Add `sidecar.istio.io/inject` to the configuration yaml with a value of `true` as illustrated here:
++
+.Sleep test application example
+[source,yaml]
+----
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: sleep
+spec:
+  replicas: 1
+  template:
+    metadata:
+      annotations:
+        sidecar.istio.io/inject: "true"
+      labels:
+        app: sleep
+    spec:
+      containers:
+      - name: sleep
+        image: tutum/curl
+        command: ["/bin/sleep","infinity"]
+        imagePullPolicy: IfNotPresent
+----
+
+. Save the configuration file.

modules/ossm-configure-security-constraints.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_install/prepare-to-deploy-applications-ossm.adoc
+
+
+[id="ossm-configure-security-constraints_{context}"]
+= Configuring {ProductName} security constraints
+
+Configure service accounts that require additional permissions to run in the {ProductShortName} with `anyuid` or `privileged` Security Context Constraints (SCCs).
+
+[NOTE]
+====
+You do not need to follow this procedure if you are using {product-title} 4.1.
+====
+
+.Prerequisites
+
+* Identify the service accounts that require SCC changes.
+* Identify the namespaces associated with the service accounts that require SCC changes.
+
+
+.Procedure
+
+. Identify the service account(s) that require relaxed privileges.
++
+[NOTE]
+====
+Replace `<service account>` and `<namespace>` with values specific to your application in the commands in this procedure.
+====
+
+. Run this command for each service account that requires the `anyuid` SCC for its associated sidecar container.
++
+----
+$ oc adm policy add-scc-to-user anyuid -z <service account> -n <namespace>
+----
+
+. Run this command for each service account that requires the `privileged` SCC to allow successful updates to its pod's networking configuration:
++
+----
+$ oc adm policy add-scc-to-user privileged -z <service account> -n <namespace>
+----

modules/ossm-control-plane-deploy.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_install/installing-ossm.adoc
+
+[id="ossm-control-plane-deploy_{context}"]
+
+= Deploying the control plane
+
+With the introduction of {product-title} 4.1, the network capabilities of the host are now based on nftables rather than iptables. This change impacts the initialization of the {ProductName} application components. {ProductShortName} needs to know what host operating system OpenShift is running on to correctly initialize {ProductShortName} networking components.
+
+[NOTE]
+====
+You do not need to follow this procedure if you are using {product-title} 4.1.
+====
+
+If the OpenShift installation is deployed on a Red Hat Enterprise Linux (RHEL) 7 host, then the custom resource must explicitly request the RHEL 7 `proxy-init` container image by including the following:
+
+.Enabling the proxy-init container for RHEL 7 hosts
+
+[subs=+macros]
+----
+  apiVersion: maistra.io/v1
+   kind: ServiceMeshControlPlane
+   spec:
+     istio:
+       global:
+        pass:quotes[*proxy_init:*]
+          pass:quotes[*image: proxy-init*]
+----
+
+Use the custom resource definition file you created to deploy the {ProductShortName} control plane.
+
+
+.Procedure
+
+. Create a custom resource definition file named `istio-installation.yaml`.
+
+. Run this command to deploy the control plane:
++
+----
+$ oc create -n istio-system -f istio-installation.yaml
+----
+
+. Run this command to watch the progress of the pods during the installation process:
++
+----
+$ oc get pods -n istio-system -w
+----

modules/ossm-control-plane-verify.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_install/installing-ossm.adoc
+
+[id="ossm-control-plane-verify_{context}"]
+
+= Verifying the control plane installation
+
+Verify that the control plane installation completed successfully.
+
+.Procedure
+
+[NOTE]
+====
+The name of the resource is `istio-installation`.
+====
+
+. Run this command to determine if the Operator finished deploying the control plane:
++
+----
+$ oc get servicemeshcontrolplane/basic-install -n istio-system --template='{{range .status.conditions}}{{printf "%s=%s, reason=%s, message=%s\n\n" .type .status .reason .message}}{{end}}'
+----
++
+When the control plane installation is finished, the output is similar to the following:
++
+----
+Installed=True, reason=InstallSuccessful, message=%!s()
+
+Reconciled=True, reason=InstallSuccessful, message=%!s()
+----
+
+. After the control plane is deployed, run this command to check the status of the pods:
++
+----
+$ oc get pods -n istio-system
+----
+
+. Verify that the pods are in a state similar to this:
++
+[NOTE]
+====
+The results returned when you run this verification step vary depending on your configuration including the number of nodes in the cluster, and whether you are using 3scale, Jaeger, Kiali, or Prometheus.
+====
++
+----
+NAME                                          READY     STATUS      RESTARTS   AGE
+3scale-istio-adapter-67b96f97b5-cwvgt         1/1       Running     0          99s
+grafana-75f4cbbc6-xw99s                       1/1       Running     0          54m
+istio-citadel-8489b8bb96-ttqfd                1/1       Running     0          54m
+stio-egressgateway-5ccd4d5ddd-wtp2h           1/1       Running     0          52m
+istio-galley-58ff8db57c-jrpkz                 1/1       Running     0          54m
+istio-ingressgateway-698674848f-bk57s         1/1       Running     0          52m
+istio-node-2d764                              1/1       Running     0          54m
+istio-node-4h926                              1/1       Running     0          54m
+istio-node-6qxcj                              1/1       Running     0          54m
+istio-node-8fxqz                              1/1       Running     0          54m
+istio-node-gzg5v                              1/1       Running     0          54m
+istio-node-vxx5p                              1/1       Running     0          54m
+istio-pilot-764966cf69-9nlhp                  2/2       Running     0          19m
+istio-policy-7c856f7d5f-4fjk4                 2/2       Running     2          53m
+istio-sidecar-injector-757b8ccdbf-znggc       1/1       Running     0          49m
+istio-telemetry-65d8b47c98-jrp9h              2/2       Running     2          53m
+jaeger-f775b79f8-cmbb2	                      2/2	      Running	    0	         54m
+kiali-7646d796cd-kfx29	                      1/1	      Running	    0	         20m
+prometheus-56cb9c859b-dlqmn	                  2/2	      Running	    0	         54m
+----

modules/ossm-cr-cni.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_install/installing-ossm.adoc
+
+[id="ossm-cr-cni_{context}"]
+= Container Network Interface (CNI) example
+
+This example illustrates the CNI parameter and its values for {ProductName}.
+
+[WARNING]
+====
+If Container Network Interface (CNI) is enabled, manual sidecar injection will work, but pods will not be able to communicate with the control plane unless they are a part of the `ServiceMeshMemberRoll` resource.
+====
+
+
+.CNI example
+[source,yaml]
+----
+  apiVersion: maistra.io/v1
+  kind: ServiceMeshControlPlane
+  metadata:
+   name: basic-install
+  spec:
+
+    istio:
+      istio_cni:
+        enabled: true
+----
+
+
+.CNI parameter
+|===
+|Type |Parameter |Description |Values |Default value
+
+|`istio_cni`
+|`enabled`
+|This parameter enables the Container Network Interface (CNI).
+|`true`/`false`
+|`false`
+|===

modules/ossm-cr-example.adoc

@@ -0,0 +1,75 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/service_mesh_install/installing-ossm.adoc
+
+[id="ossm-cr-example_{context}"]
+= {ProductName} custom resource
+
+[NOTE]
+====
+The `istio-system` namespace is used an example throughout the {ProductShortName} documentation, but you can use other namespaces as necessary.
+====
+
+To deploy the {ProductShortName} control plane, you must create a custom resource. A _custom resource_ allows you to introduce your own API into a Kubernetes project or cluster. You create a custom resource yaml file that defines the project parameters and creates the object. This example custom resource yaml file contains all of the supported parameters and deploys {ProductName} {ProductVersion} images based on Red Hat Enterprise Linux (RHEL).
+
+[IMPORTANT]
+====
+The 3scale Istio Adapter is deployed and configured in the custom resource file. It also requires a working 3scale account (link:https://www.3scale.net/signup/[SaaS] or link:https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.4/html/infrastructure/onpremises-installation[On-Premises]).
+====
+
+.Full example istio-installation.yaml
+
+[source,yaml]
+----
+  apiVersion: maistra.io/v1
+  kind: ServiceMeshControlPlane
+  metadata:
+    name: basic-install
+
+    threeScale:
+      enabled: false
+
+    istio:
+      global:
+        proxy:
+          resources:
+            requests:
+              cpu: 100m
+              memory: 128Mi
+            limits:
+              cpu: 500m
+              memory: 128Mi
+        multitenant: true
+
+      gateways:
+        istio-egressgateway:
+          autoscaleEnabled: false
+        istio-ingressgateway:
+          autoscaleEnabled: false
+          ior_enabled: false
+
+      mixer:
+        policy:
+          autoscaleEnabled: false
+
+        telemetry:
+          autoscaleEnabled: false
+          resources:
+            requests:
+              cpu: 100m
+              memory: 1G
+            limits:
+              cpu: 500m
+              memory: 4G
+
+      pilot:
+        autoscaleEnabled: false
+        traceSampling: 100.0
+
+      kiali:
+       dashboard:
+          user: admin
+          passphrase: admin
+      tracing:
+        enabled: true
+----