Merge pull request #43238 from JStickler/OSSMDOC-463

OSSMDOC-463 Verify sidecar injection.

Author: JStickler

images/ossm-icon-missing-sidecar.png

@@ -7,63 +7,76 @@
 [id="ossm-automatic-sidecar-injection_{context}"]
 = Enabling automatic sidecar injection
 
-When deploying an application, you must opt-in to injection by setting the `sidecar.istio.io/inject` annotation to `"true"`. Opting in ensures that the sidecar injection does not interfere with other {product-title} features such as builder pods used by numerous frameworks within the {product-title} ecosystem.
+When deploying an application, you must opt-in to injection by configuring the annotation `sidecar.istio.io/inject` in `spec.template.metadata.annotations` to `true` in the `deployment` object. Opting in ensures that the sidecar injection does not interfere with other {product-title} features such as builder pods used by numerous frameworks within the {product-title} ecosystem.
 
 .Prerequisites
 
-* Identify the deployments for which you want to enable automatic sidecar injection.
+* Identify the namespaces that are part of your service mesh and the deployments that need automatic sidecar injection.
 
 .Procedure
 
-. Open the application's deployment configuration YAML file in an editor. To find a deployment use the `oc get` command. For example, for an app called `sleep` in the `sleep` namespace, use the following command to see the resource in YAML format.
+. To find your deployments use the `oc get` command.
 +
 [source,terminal]
 ----
-$ oc get deployment sleep -o yaml
+$ oc get deployment -n <namespace>
 ----
++
+For example, to view the deployment file for the 'ratings-v1' microservice in the `bookinfo` namespace, use the following command to see the resource in YAML format.
++
+[source,terminal]
+----
+oc get deployment -n bookinfo ratings-v1 -o yaml
+----
++
+. Open the application's deployment configuration YAML file in an editor.
 
-. Add `sidecar.istio.io/inject` to the configuration YAML with a value of `"true"` in the `spec.template.metadata.annotations.sidecar.istio/inject` field. See the following example for an app called `sleep`.
+. Add `spec.template.metadata.annotations.sidecar.istio/inject` to your Deployment YAML and set `sidecar.istio.io/inject` to `true` as shown in the following example.
 +
-.Sleep test application example sleep.yaml
+.Example snippet from bookinfo deployment-ratings-v1.yaml
 [source,yaml]
 ----
 apiVersion: apps/v1
 kind: Deployment
 metadata:
+  name: ratings-v1
+  namespace: bookinfo
   labels:
-    app: sleep
-  name: sleep
+    app: ratings
+    version: v1
 spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: sleep
   template:
     metadata:
       annotations:
-        sidecar.istio.io/inject: "true"
-      labels:
-        app: sleep
-    spec:
-      containers:
-      - name: sleep
-        image: curlimages/curl
-        command: ["/bin/sleep","3650d"]
-        imagePullPolicy: IfNotPresent
+        sidecar.istio.io/inject: 'true'
 ----
++
+. Save the Deployment configuration file.
 
-. Save the configuration file.
-
-. Add the file back to the project that contains your app. In this example,  `sleep` is the name of the project that contains the `sleep` app and `sleep.yaml` is the file you edited.
+. Add the file back to the project that contains your app.
 +
 [source,terminal]
 ----
-$ oc apply -n sleep -f sleep.yaml
+$ oc apply -n <namespace> -f deployment.yaml
 ----
-
++
+In this example, `bookinfo` is the name of the project that contains the `ratings-v1` app and `deployment-ratings-v1.yaml` is the file you edited.
++
+[source,terminal]
+----
+$ oc apply -n bookinfo -f deployment-ratings-v1.yaml
+----
++
 . To verify that the resource uploaded successfully, run the following command.
 +
 [source,terminal]
 ----
-$ oc get deployment sleep -o yaml
+$ oc get deployment -n <namespace> <deploymentName> -o yaml
+----
++
+For example,
++
+[source,terminal]
+----
+$ oc get deployment -n bookinfo ratings-v1 -o yaml
 ----

images/ossm-node-badge-missing-sidecar.svg

@@ -11,13 +11,12 @@ You can view logs for your workloads in the Kiali console.  The *Workload Detail
 
 To change the logging level on the logs displayed in Kiali, you change the logging configuration for the workload or the proxy.
 
-// TODO once released - Kiali can also add-in trace span information to help identify important traces based on associated logging. More powerful features include substring or regex Show/Hide, full-screen, and the ability to set proxy log level without a pod restart.
-
 .Prerequisites
 
 * Service Mesh installed and configured.
 * Kiali installed and configured.
 * The address for the Kiali console.
+* Application or Bookinfo sample application added to the mesh.
 
 .Procedure
 
@@ -31,6 +30,11 @@ The Kiali Overview page displays namespaces that have been added to the mesh tha
 
 . On the *Workloads* page, select the project from the *Namespace* menu.
 
-. If necessary, use the filter to find the workload whose logs you want to view.  Click the workload *Name*.
+. If necessary, use the filter to find the workload whose logs you want to view.  Click the workload *Name*.  For example, click *ratings-v1*.
 
 . On the *Workload Details* page, click the *Logs* tab to view the logs for the workload.
+
+[TIP]
+====
+If you do not see any log entries, you may need to adjust either the Time Range or the Refresh interval.
+====

modules/ossm-automatic-sidecar-injection.adoc

@@ -3,10 +3,13 @@
 // * service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc
 // * service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc
 
+:_content-type: CONCEPT
 [id="ossm-sidecar-injection-env-var_{context}"]
-= Setting environment variables on the proxy in applications through annotations
+= Setting proxy environment variables through annotations
 
-You can set environment variables on the sidecar proxy for applications by adding pod annotations in the deployment in the `injection-template.yaml` file. The environment variables are injected to the sidecar.
+Configuration for the Envoy sidecar proxies is managed by the `ServiceMeshControlPlane`.
+
+You can set environment variables for the sidecar proxy for applications by adding pod annotations to the deployment in the `injection-template.yaml` file. The environment variables are injected to the sidecar.
 
 .Example injection-template.yaml
 [source,yaml]
@@ -28,5 +31,5 @@ spec:
 
 [WARNING]
 ====
-`maistra.io/` labels and annotations should never be included in user-created resources, because they indicate that the resources are generated and managed by the Operator. If you are copying content from an Operator-generated resource when creating your own resources, do not include labels or annotations that start with `maistra.io/` or your resource will be overwritten or deleted by the Operator during the next reconciliation.
+You should never include `maistra.io/` labels and annotations when creating your own custom resources.  These labels and annotations indicate that the resources are generated and managed by the Operator. If you are copying content from an Operator-generated resource when creating your own resources, do not include labels or annotations that start with `maistra.io/`.  Resources that include these labels or annotations will be overwritten or deleted by the Operator during the next reconciliation.
 ====

modules/ossm-kiali-viewing-logs.adoc

@@ -0,0 +1,31 @@
+////
+This module included in the following assemblies:
+* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc
+////
+:_content-type: CONCEPT
+[id="ossm-validating-sidecar_{context}"]
+= Validating sidecar injection
+
+The Kiali console offers several ways to validate whether or not your applications, services, and workloads have a sidecar proxy.
+
+.Missing sidecar badge
+image::ossm-node-badge-missing-sidecar.svg[Missing Sidecar badge]
+
+The *Graph* page displays a node badge indicating a *Missing Sidecar* on the following graphs:
+
+* App graph
+* Versioned app graph
+* Workload graph
+
+.Missing sidecar icon
+image::ossm-icon-missing-sidecar.png[Missing Sidecar icon]
+
+The *Applications* page displays a *Missing Sidecar* icon in the *Details* column for any applications in a namespace that do not have a sidecar.
+
+The *Workloads* page displays a *Missing Sidecar* icon in the *Details* column for any applications in a namespace that do not have a sidecar.
+
+The *Services* page displays a *Missing Sidecar* icon in the *Details* column for any applications in a namespace that do not have a sidecar. When there are multiple versions of a service, you use the *Service Details* page to view *Missing Sidecar* icons.
+
+The *Workload Details* page has a special unified *Logs* tab that lets you view and correlate application and proxy logs. You can view the Envoy logs as another way to validate sidecar injection for your application workloads.
+
+The *Workload Details* page also has an *Envoy* tab for any workload that is an Envoy proxy or has been injected with an Envoy proxy. This tab displays a built-in Envoy dashboard that includes subtabs for *Clusters*, *Listeners*, *Routes*, *Bootstrap*, *Config*, and *Metrics*.

modules/ossm-sidecar-injection-env-var.adoc

@@ -1,12 +1,13 @@
 // Module included in the following assemblies:
 //
-// * service_mesh/v1x/installing-ossm.adoc
-// * service_mesh/v2x/installing-ossm.adoc
+// * service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc
+// * service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc
 
+:_content-type: PROCEDURE
 [id="ossm-update-app-sidecar_{context}"]
-= Updating your application pods
+= Updating sidecar proxies
 
-If you selected the Automatic Approval Strategy when you were installing your Operators, then the Operators update the control plane automatically but not your applications. Existing applications continue to be part of the mesh and function accordingly. The application administrator must restart applications to upgrade the sidecar.
+In order to update the configuration for sidecar proxies the application administrator must restart the application pods.
 
 If your deployment uses automatic sidecar injection, you can update the pod template in the deployment by adding or modifying an annotation. Run the following command to redeploy the pods:
 
@@ -15,4 +16,4 @@ If your deployment uses automatic sidecar injection, you can update the pod temp
 $ oc patch deployment/<deployment> -p '{"spec":{"template":{"metadata":{"annotations":{"kubectl.kubernetes.io/restartedAt": "'`date -Iseconds`'"}}}}}'
 ----
 
-If your deployment does not use automatic sidecar injection, you must manually update the sidecars by modifying the sidecar container image specified in the deployment or pod.
+If your deployment does not use automatic sidecar injection, you must manually update the sidecars by modifying the sidecar container image specified in the deployment or pod, and then restart the pods.

modules/ossm-sidecar-validate-kiali.adoc

@@ -2,7 +2,7 @@
 Module included in the following assemblies:
 -service_mesh/v2x/ossm-vs-community.adoc
 ////
-
+:_content-type: CONCEPT
 [id="ossm-vs-istio_{context}"]
 = Differences between Istio and {SMProductName}
 
@@ -29,6 +29,29 @@ The upstream Istio community installation automatically injects the sidecar into
 
 {SMProductName} does not automatically inject the sidecar to any pods, but requires you to opt in to injection using an annotation without labeling projects. This method requires fewer privileges and does not conflict with other OpenShift capabilities such as builder pods. To enable automatic injection you specify the `sidecar.istio.io/inject` annotation as described in the Automatic sidecar injection section.
 
+////
+Hold for OSSMDOC-547 as to what we support
+.Sidecar injection label and annotation settings
+[options="header"]
+[cols="a, a, a"]
+|===
+|
+|Upstream Istio
+|{ProductName}
+
+|Namespace Label
+|supports "enabled" and "disabled"
+|not supported
+
+|Pod Label
+|supports "true" and "false"
+|not supported
+
+|Pod Annotation
+|supports "false" only
+|"true" and "false"
+|===
+////
 [id="ossm-rbac_{context}"]
 == Istio Role Based Access Control features