From d337b38cd00ee315e1e6c85537309a7d3b2421c8 Mon Sep 17 00:00:00 2001 From: Jamie Longmuir Date: Fri, 29 Nov 2024 01:58:57 -0500 Subject: [PATCH] Use bookinfo for injection examples (#169) * Use bookinfo for injection examples * Update docs/ossm/injection/README.md Co-authored-by: Filip Brychta * Feedback from PR, and add exclusion example * Update docs/ossm/injection/README.md Co-authored-by: Filip Brychta * Further updates from review, remove extra restarts not needed --------- Co-authored-by: Filip Brychta --- docs/ossm/injection/README.md | 219 ++++++++++++++++++++++++---------- 1 file changed, 159 insertions(+), 60 deletions(-) diff --git a/docs/ossm/injection/README.md b/docs/ossm/injection/README.md index 09b30e9cf..60045f18e 100644 --- a/docs/ossm/injection/README.md +++ b/docs/ossm/injection/README.md @@ -49,81 +49,180 @@ The injector is configured with the following logic: 1. If either label (`istio-injection` or `sidecar.istio.io/inject`) is disabled, the pod is not injected. 2. If either label (`istio-injection` or `sidecar.istio.io/inject` or `istio.io/rev`) is enabled, the pod is injected. -### Example: Enabling sidecar injection +### Sidecar injection examples + +The following examples use the [Bookinfo application](https://docs.openshift.com/service-mesh/3.0.0tp1/install/ossm-installing-openshift-service-mesh.html#deploying-book-info_ossm-about-bookinfo-application) to demonstrate different approaches for configuring side car injection. + +> Note: If you have followed the procedure to deploy the Bookinfo application, step 5 added a sidecar injection label to the `bookinfo` namespace, and these steps are not necessary to repeat. + Prerequisites: -- The OpenShift Service Mesh operator has been installed -- An Istio CNI resource has been created +- You have installed the Red Hat OpenShift Service Mesh Operator, created an `Istio` resource, and the Operator has deployed Istio. +- You have created the `IstioCNI` resource, and the Operator has deployed the necessary IstioCNI pods. +- You have created the namespaces that are to be part of the mesh, and they are [discoverable by the Istio control plane](https://docs.openshift.com/service-mesh/3.0.0tp1/install/ossm-installing-openshift-service-mesh.html#ossm-scoping-service-mesh-with-discoveryselectors_ossm-creating-istiocni-resource). +- (Optional) You have deployed the workloads to be included in the mesh. In the following examples, the [Bookinfo has been deployed](https://docs.redhat.com/en/documentation/red_hat_openshift_service_mesh/3.0.0tp1/html-single/installing/index#ossm-about-bookinfo-application_ossm-discoveryselectors-scope-service-mesh) to the `bookinfo` namespace, but sidecar injection (step 5) has not been configured. + +#### Example 1: Enabling sidecar injection with namespace labels + +In this example, all workloads within a namespace will be injected with a sidecar proxy. This is the best approach if most of the workloads within a namespace are to be included in the mesh. + +Procedure: + +1. Verify the revision name of the Istio control plane: -1. Create the `istio-system` namespace: ```bash - oc create ns istio-system + $ oc get istiorevision + NAME TYPE READY STATUS IN USE VERSION AGE + default Local True Healthy False v1.23.0 4m57s ``` -1. Prepare `default` `istio.yaml`: - ```yaml - kind: Istio - apiVersion: sailoperator.io/v1alpha1 - metadata: - name: default - spec: - namespace: istio-system - updateStrategy: - type: InPlace - version: v1.23.0 - ``` -1. Create the `default` Istio CR in `istio-system` namespace: + Since the revision name is `default`, we can used the default injection labels and do not need to reference the specific revision name. + +1. For workloads already running in the desired namespace, verify that they show "1/1" containers as "READY", indicating that the pods are currently running without sidecars: + ```bash - oc apply -f istio.yaml + $ oc get pods -n bookinfo + NAME READY STATUS RESTARTS AGE + details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s + productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s + ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s + reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s + reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s + reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s ``` -1. Wait for `Istio` to become ready. + +1. Apply the injection label to the bookinfo namespace by entering the following command at the CLI: ```bash - oc wait --for=condition=Ready istios/default -n istio-system + $ oc label namespace bookinfo istio-injection=enabled + namespace/bookinfo labeled ``` -1. Deploy the `sleep` app: + +1. Workloads that were already running when the injection label was added will need to be redeployed for sidecar injection to occur. The following command can be used to perform a rolling update of all workloads in the `bookinfo` namespace: ```bash - oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/sleep/sleep.yaml + oc -n bookinfo rollout restart deployment ``` -1. Verify both the deployment and pod have a single container: + +1. Verify that once rolled out, the new pods show "2/2" containers "READY", indicating that the sidecars have been successfully injected: + ```bash - oc get deployment -o wide - NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR - sleep 1/1 1 1 16s sleep curlimages/curl app=sleep - oc get pod -l app=sleep - NAME READY STATUS RESTARTS AGE - sleep-5577c64d7c-ntn9d 1/1 Running 0 16s + $ oc get pods -n bookinfo + NAME READY STATUS RESTARTS AGE + details-v1-7745f84ff-bpf8f 2/2 Running 0 55s + productpage-v1-54f48db985-gd5q9 2/2 Running 0 55s + ratings-v1-5d645c985f-xsw7p 2/2 Running 0 55s + reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 55s + reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 55s + reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 55s ``` -1. Label the `default` namespace with `istio-injection=enabled`: - ```bash - oc label namespace default istio-injection=enabled +#### Example 2: Exclude a workload from the mesh + +There may be times when you want to exclude individual workloads from a namespace where all workloads are otherwise injected with sidecars. This continues the previous example to exclude the `details` service from the mesh. + + > Note: This example is for demonstration purposes only, and the bookinfo application requires all workloads to be part of the mesh for it to work. + +Procedure: + +1. Open the application’s `Deployment` resource in an editor. In this case, we will exclude the `ratings-v1` service. + +1. Modify the `spec.template.metadata.labels` section of your `Deployment` resource to include the appropriate pod injection or revision label to set injection to "false". In this case, `sidecar.istio.io/inject: false`: + + ```yaml + kind: Deployment + apiVersion: apps/v1 + metadata: + name: ratings-v1 + namespace: bookinfo + labels: + app: ratings + version: v1 + spec: + template: + metadata: + labels: + sidecar.istio.io/inject: 'false' ``` -1. Injection occurs at pod creation time. Remove the running pod to be injected with a proxy sidecar. + > Note: Adding the label to the `Deployment`'s top level `labels` section will not impact sidecar injection. + +Updating the deployment will result in a rollout, where a new `ReplicaSet` is created with updated pod(s). + +1. Verify that the updated pod(s) do not contain a sidecar container, and shows "1/1" containers "Running": ```bash - oc delete pod -l app=sleep + oc get pods -n bookinfo + NAME READY STATUS RESTARTS AGE + details-v1-6bc7b69776-7f6wz 1/1 Running 0 7s + productpage-v1-54f48db985-gd5q9 2/2 Running 0 29m + ratings-v1-5d645c985f-xsw7p 2/2 Running 0 29m + reviews-v1-bd5f54b8c-zns4v 2/2 Running 0 29m + reviews-v2-5d7b9dbf97-wbpjr 2/2 Running 0 29m + reviews-v3-5fccc48c8c-bjktn 2/2 Running 0 29m ``` -1. Verify a new pod is created with the injected sidecar. The original pod has `1/1 READY` containers, and the pod with injected sidecar has `2/2 READY` containers. - ```bash - oc get pod -l app=sleep - NAME READY STATUS RESTARTS AGE - sleep-5577c64d7c-w9vpk 2/2 Running 0 12s + +### Example 3: Enabling sidecar injection with pod labels + +Rather than including all workloads within a namespace, you can include individual workloads for sidecar injection. This approach is ideal when only a few workloads within a namespace will be part of a service mesh. + +This example also demonstrates the use of a revision label for sidecar injection. In this case, the `Istio` resource has been created with the name "my-mesh". A unique resource `Istio` name is needed when there are multiple Istio control planes present in the same cluster, or a revision based control plane upgrade is in progress. + +Procedure: + +1. Verify the revision name of the Istio control plane: + + ```console + $ oc get istiorevision + NAME TYPE READY STATUS IN USE VERSION AGE + my-mesh Local True Healthy False v1.23.0 47s ``` -1. View the detailed state of the injected pod. You should see the injected `istio-proxy` container. + Since the revision name is `my-mesh`, we must use the a revision label to enable sidecar injection. In this case, `istio.io/rev=my-mesh`. + +1. For workloads already running, verify that they show "1/1" containers as "READY", indicating that the pods are currently running without sidecars: + ```bash - oc describe pod -l app=sleep - ... - Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Scheduled 50s default-scheduler Successfully assigned default/sleep-5577c64d7c-w9vpk to user-rhos-d-1-v8rnx-worker-0-rwjrr - Normal AddedInterface 50s multus Add eth0 [10.128.2.179/23] from ovn-kubernetes - Normal Pulled 50s kubelet Container image "registry.redhat.io/openshift-service-mesh-tech-preview/istio-proxyv2-rhel9@sha256:c0170ef9a34869828a5f2fea285a7cda543d99e268f7771e6433c54d6b2cbaf4" already present on machine - Normal Created 50s kubelet Created container istio-validation - Normal Started 50s kubelet Started container istio-validation - Normal Pulled 50s kubelet Container image "curlimages/curl" already present on machine - Normal Created 50s kubelet Created container sleep - Normal Started 50s kubelet Started container sleep - Normal Pulled 50s kubelet Container image "registry.redhat.io/openshift-service-mesh-tech-preview/istio-proxyv2-rhel9@sha256:c0170ef9a34869828a5f2fea285a7cda543d99e268f7771e6433c54d6b2cbaf4" already present on machine - Normal Created 50s kubelet Created container istio-proxy - Normal Started 50s kubelet Started container istio-proxy - ... + $ oc get pods -n bookinfo + NAME READY STATUS RESTARTS AGE + details-v1-65cfcf56f9-gm6v7 1/1 Running 0 4m55s + productpage-v1-d5789fdfb-8x6bk 1/1 Running 0 4m53s + ratings-v1-7c9bd4b87f-6v7hg 1/1 Running 0 4m55s + reviews-v1-6584ddcf65-6wqtw 1/1 Running 0 4m54s + reviews-v2-6f85cb9b7c-w9l8s 1/1 Running 0 4m54s + reviews-v3-6f5b775685-mg5n6 1/1 Running 0 4m54s + ``` + +1. Open the application’s `Deployment` resource in an editor. In this case, we will update the `ratings-v1` service. + +1. Update the `spec.template.metadata.labels` section of your `Deployment` to include the appropriate pod injection or revision label. In this case, `istio.io/rev: my-mesh`: + + ```yaml + kind: Deployment + apiVersion: apps/v1 + metadata: + name: ratings-v1 + namespace: bookinfo + labels: + app: ratings + version: v1 + spec: + template: + metadata: + labels: + istio.io/rev: my-mesh ``` -> [!CAUTION] -> Injection using the `istioctl kube-inject` which is not supported by Red Hat OpenShift Service Mesh. + + > Note: Adding the label to the `Deployment`'s top level `labels` section will not impact sidecar injection. + + Updating the deployment will result in a rollout, where a new `ReplicaSet` is created with updated pod(s). + +1. Verify that only the `ratings-v1` pod now shows "2/2" containers "READY", indicating that the sidecar has been successfully injected: + ``` + oc get pods -n bookinfo + NAME READY STATUS RESTARTS AGE + details-v1-559cd49f6c-b89hw 1/1 Running 0 42m + productpage-v1-5f48cdcb85-8ppz5 1/1 Running 0 42m + ratings-v1-848bf79888-krdch 2/2 Running 0 9s + reviews-v1-6b7444ffbd-7m5wp 1/1 Running 0 42m + reviews-v2-67876d7b7-9nmw5 1/1 Running 0 42m + reviews-v3-84b55b667c-x5t8s 1/1 Running 0 42m + ``` + +1. Repeat for other workloads that you wish to include in the mesh. + + +Additional Resources +- [Istio Sidecar injection problems](https://istio.io/latest/docs/ops/common-problems/injection/) \ No newline at end of file