|
| 1 | +# Quickstart: OSSM3 with Kiali, Tempo, Bookinfo |
| 2 | +This quickstart guide provides step-by-step instructions on how to set up OSSM3 with Kiali, Tempo, Open Telemetry, and Bookinfo app. |
| 3 | +By the end of this quickstart, you will have installed OSSM3, where tracing information is collected by Open Telemetry Collector and Tempo, and monitoring is managed by an in-cluster monitoring stack. The Bookinfo sample application will be included in the service mesh, with a traffic generator sending one request per second to simualte traffic. Additionally, the Kiali UI and OSSMC plugin will be set up to provide a graphical overview. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | +- The OpenShift Service Mesh 3, Kiali, Tempo, Red Hat build of OpenTelemetry operators have been installed (you can install it by `./installOperators.sh` script which installs the particular operator versions (see subscriptions.yaml)) |
| 7 | +- The cluster that has available Persistent Volumes or supports dynamic provisioning storage (for installing MiniO) |
| 8 | + |
| 9 | +## What is located where |
| 10 | +The quickstart |
| 11 | + * installs MiniO and Tempo to `tracing-system` namespace |
| 12 | + * installs OpenTelemetryCollector to `opentelemetrycollector` namespace |
| 13 | + * installs OSSM3 (Istio CR) with Kiali and OSSMC to `istio-system` namespace |
| 14 | + * installs IstioCNI to `istio-cni` namespace |
| 15 | + * installs Istio ingress gateway to `istio-ingress` namespace |
| 16 | + * installs bookinfo app with traffic generator in `bookinfo` namespace |
| 17 | + |
| 18 | +## Shortcut to the end |
| 19 | +To skip all the following steps and set everything up automatically (e.g., for demo purposes), simply run the prepared `./install_ossm3_demo.sh` script which will perform all steps automatically. |
| 20 | + |
| 21 | +## Steps |
| 22 | +All required YAML resources are in the `./resources` folder. |
| 23 | +For a more detailed description about what is set and why, see OpenShift Service Mesh documentation. |
| 24 | + |
| 25 | +Set up Tempo and OpenTelemetryCollector |
| 26 | +------------ |
| 27 | +```bash |
| 28 | +oc new-project tracing-system |
| 29 | +``` |
| 30 | +First, set up MiniO storage which is used by Tempo to store data (or you can use S3 storage, see Tempo documentation) |
| 31 | +```bash |
| 32 | +oc apply -f ./resources/TempoOtel/minio.yaml -n tracing-system |
| 33 | +oc wait --for condition=Available deployment/minio --timeout 150s -n tracing-system |
| 34 | +``` |
| 35 | +Then, set up Tempo CR |
| 36 | +```bash |
| 37 | +oc apply -f ./resources/TempoOtel/tempo.yaml -n tracing-system |
| 38 | +oc wait --for condition=Ready TempoStack/sample --timeout 150s -n tracing-system |
| 39 | +oc wait --for condition=Available deployment/tempo-sample-compactor --timeout 150s -n tracing-system |
| 40 | +``` |
| 41 | +Expose Jaeger UI route which will be used in the Kiali CR later |
| 42 | +```bash |
| 43 | +oc expose svc tempo-sample-query-frontend --port=jaeger-ui --name=tracing-ui -n tracing-system |
| 44 | +``` |
| 45 | +Next, set up OpenTelemetryCollector |
| 46 | +```bash |
| 47 | +oc new-project opentelemetrycollector |
| 48 | +oc apply -f ./resources/TempoOtel/opentelemetrycollector.yaml -n opentelemetrycollector |
| 49 | +oc wait --for condition=Available deployment/otel-collector --timeout 60s -n opentelemetrycollector |
| 50 | +``` |
| 51 | + |
| 52 | +Set up OSSM3 |
| 53 | +------------ |
| 54 | +```bash |
| 55 | +oc new-project istio-system |
| 56 | +``` |
| 57 | +First, install Istio custom resource |
| 58 | +> **_NOTE:_** In this example, the `.spec.version` is missing so the istio version is automatically set by OSSM operator. You can specify the version manually, but it must be one that is supported by the operator; otherwise, a validation error will occur. |
| 59 | +```bash |
| 60 | +oc apply -f ./resources/OSSM3/istiocr.yaml -n istio-system |
| 61 | +oc wait --for condition=Ready istio/default --timeout 60s -n istio-system |
| 62 | +``` |
| 63 | +> **_NOTE:_** When you name your IstioCR differently as `default`, you need to use `istio.io/rev=<istioCR_NAME>` label instead of `istio-injection=enabled` in the all next steps of this example. |
| 64 | +> |
| 65 | +> Also, you will need to update values `config_map_name`, `istio_sidecar_injector_config_map_name`, `istiod_deployment_name`, `url_service_version` in the Kiali CR with `-<istioCR_NAME>` suffix. |
| 66 | +> |
| 67 | +> e.g. when Istio cr name is `default`: |
| 68 | +> ``` |
| 69 | +> config_map_name: istio |
| 70 | +> istio_sidecar_injector_config_map_name: istio-sidecar-injector |
| 71 | +> istiod_deployment_name: istiod |
| 72 | +> url_service_version: 'http://istiod.istio-system:15014/version' |
| 73 | +>``` |
| 74 | +> e.g. when Istio cr name is `main` (or something else): |
| 75 | +> ``` |
| 76 | +> config_map_name: istio-main |
| 77 | +> istio_sidecar_injector_config_map_name: istio-sidecar-injector-main |
| 78 | +> istiod_deployment_name: istiod-main |
| 79 | +> url_service_version: 'http://istiod-main.istio-system:15014/version' |
| 80 | +>``` |
| 81 | +
|
| 82 | +Then, set up Telemetry resource to enable tracers defined in Istio custom resource |
| 83 | +```bash |
| 84 | +oc apply -f ./resources/TempoOtel/istioTelemetry.yaml -n istio-system |
| 85 | +``` |
| 86 | +The opentelemetrycollector namespace needs to be added as a member of the mesh |
| 87 | +```bash |
| 88 | +oc label namespace opentelemetrycollector istio-injection=enabled |
| 89 | +``` |
| 90 | + |
| 91 | +Then, install IstioCNI |
| 92 | +> **_NOTE:_** In this example, the `.spec.version` is missing so the istio version is automatically set by OSSM operator. the `.spec.version` is missing so the istio version is automatically set by OSSM operator. You can specify the version manually, but it must be one that is supported by the operator. |
| 93 | +```bash |
| 94 | +oc new-project istio-cni |
| 95 | +oc apply -f ./resources/OSSM3/istioCni.yaml -n istio-cni |
| 96 | +oc wait --for condition=Ready istiocni/default --timeout 60s -n istio-cni |
| 97 | +``` |
| 98 | + |
| 99 | +Set up the ingress gateway in a different namespace as istio-system. |
| 100 | +Add that namespace as a member of the mesh. |
| 101 | +```bash |
| 102 | +oc new-project istio-ingress |
| 103 | +oc label namespace istio-ingress istio-injection=enabled |
| 104 | +oc apply -f ./resources/OSSM3/istioIngressGateway.yaml -n istio-ingress |
| 105 | +oc wait --for condition=Available deployment/istio-ingressgateway --timeout 60s -n istio-ingress |
| 106 | +``` |
| 107 | +Expose Istio ingress route which will be used in the bookinfo traffic generator later (and via that URL, we will be accessing to the bookinfo app) |
| 108 | +```bash |
| 109 | +oc expose svc istio-ingressgateway --port=http2 --name=istio-ingressgateway -n istio-ingress |
| 110 | +``` |
| 111 | + |
| 112 | +Set up OCP user monitoring workflow |
| 113 | +------------ |
| 114 | +First, OCP user monitoring needs to be enabled |
| 115 | +```bash |
| 116 | +oc apply -f ./resources/Monitoring/ocpUserMonitoring.yaml |
| 117 | +``` |
| 118 | +Then, create service monitor and pod monitor for istio namespaces |
| 119 | +```bash |
| 120 | +oc apply -f ./resources/Monitoring/serviceMonitor.yaml -n istio-system |
| 121 | +oc apply -f ./resources/Monitoring/podMonitor.yaml -n istio-system |
| 122 | +oc apply -f ./resources/Monitoring/podMonitor.yaml -n istio-ingress |
| 123 | +``` |
| 124 | + |
| 125 | +Set up Kiali |
| 126 | +------------ |
| 127 | +Create cluster role binding for kiali to be able to read ocp monitoring |
| 128 | +```bash |
| 129 | +oc apply -f ./resources/Kiali/kialiCrb.yaml -n istio-system |
| 130 | +``` |
| 131 | +Set up Kiali CR. The URL for Jaeger UI (which was exposed earlier) needs to be set to Kiali CR in `.spec.external_services.tracing.url` |
| 132 | +> **_NOTE:_** In this example, the `.spec.version` is missing so the istio version is automatically set by Kiali operator. You can specify the version manually, but it must be one that is supported by the operator; otherwise, an error will appear in events on the Kiali resource. |
| 133 | +```bash |
| 134 | +export TRACING_INGRESS_ROUTE="http://$(oc get -n tracing-system route tracing-ui -o jsonpath='{.spec.host}')" |
| 135 | +cat ./resources/Kiali/kialiCr.yaml | JAEGERROUTE="${TRACING_INGRESS_ROUTE}" envsubst | oc -n istio-system apply -f - |
| 136 | +oc wait --for condition=Successful kiali/kiali --timeout 150s -n istio-system |
| 137 | +``` |
| 138 | +Increase timeout for the Kiali ui route in OCP since big queries for spans can take longer |
| 139 | +```bash |
| 140 | +oc annotate route kiali haproxy.router.openshift.io/timeout=60s -n istio-system |
| 141 | +``` |
| 142 | +Optionally, OSSMC plugin can be installed as well |
| 143 | +> **_NOTE:_** In this example, the `.spec.version` is missing so the istio version is automatically set by Kiali operator. You can specify the version manually, but it must be one that is supported by the operator and the version needs to be **the same as Kiali CR**. |
| 144 | +```bash |
| 145 | +oc apply -f ./resources/Kiali/kialiOssmcCr.yaml -n istio-system |
| 146 | +oc wait -n istio-system --for=condition=Successful OSSMConsole ossmconsole --timeout 120s |
| 147 | +``` |
| 148 | + |
| 149 | +Set up BookInfo |
| 150 | +------------ |
| 151 | +Create bookinfo namespace and add that namespace as a member of the mesh |
| 152 | +```bash |
| 153 | +oc new-project bookinfo |
| 154 | +oc label namespace bookinfo istio-injection=enabled |
| 155 | +``` |
| 156 | +Create pod monitor for bookinfo namespaces |
| 157 | +```bash |
| 158 | +oc apply -f ./resources/Monitoring/podMonitor.yaml -n bookinfo |
| 159 | +``` |
| 160 | +> **_NOTE(shortcut):_** It takes some time till pod monitor shows in Metrics targets, you can check it in OCP console Observe->Targets. The Kiali UI will not show the metrics till the targets are ready. |
| 161 | + |
| 162 | +Install the Bookinfo app (the bookinfo resources are from `release-1.23` istio release branch) |
| 163 | +```bash |
| 164 | +oc apply -f ./resources/Bookinfo/bookinfo.yaml -n bookinfo |
| 165 | +oc apply -f ./resources/Bookinfo/bookinfo-gateway.yaml -n bookinfo |
| 166 | +oc wait --for=condition=Ready pods --all -n bookinfo --timeout 60s |
| 167 | +``` |
| 168 | + |
| 169 | +Optionally, install a traffic generator for booking app which every second generates a request to simulate traffic |
| 170 | +```bash |
| 171 | +export INGRESSHOST=$(oc get route istio-ingressgateway -n istio-ingress -o=jsonpath='{.spec.host}') |
| 172 | +cat ./resources/Bookinfo/traffic-generator-configmap.yaml | ROUTE="http://${INGRESSHOST}/productpage" envsubst | oc -n bookinfo apply -f - |
| 173 | +oc apply -f ./resources/Bookinfo/traffic-generator.yaml -n bookinfo |
| 174 | +``` |
| 175 | + |
| 176 | +Test that everything works correctly |
| 177 | +------------ |
| 178 | +Now, everything should be set. |
| 179 | +Check the Bookinfo app via the ingress route |
| 180 | +```bash |
| 181 | +INGRESSHOST=$(oc get route istio-ingressgateway -n istio-ingress -o=jsonpath='{.spec.host}') |
| 182 | +echo "http://${INGRESSHOST}/productpage" |
| 183 | +``` |
| 184 | +Check Kiali UI |
| 185 | +```bash |
| 186 | +KIALI_HOST=$(oc get route kiali -n istio-system -o=jsonpath='{.spec.host}') |
| 187 | +echo "https://${KIALI_HOST}" |
| 188 | +``` |
| 189 | +You can check all namespaces that all pods running correctly: |
| 190 | +```bash |
| 191 | +oc get pods -n tracing-system |
| 192 | +oc get pods -n opentelemetrycollector |
| 193 | +oc get pods -n istio-system |
| 194 | +oc get pods -n istio-cni |
| 195 | +oc get pods -n istio-ingress |
| 196 | +oc get pods -n bookinfo |
| 197 | +``` |
| 198 | +Output (the number of istio-cni pods is equals to the number of OCP nodes): |
| 199 | +```bash |
| 200 | +NAME READY STATUS RESTARTS AGE |
| 201 | +minio-6f8c5c79-fmjpd 1/1 Running 0 10m |
| 202 | +tempo-sample-compactor-dcffd76dc-7mnll 1/1 Running 0 10m |
| 203 | +tempo-sample-distributor-7dbbf4b5d7-xw5w5 1/1 Running 0 10m |
| 204 | +tempo-sample-ingester-0 1/1 Running 0 10m |
| 205 | +tempo-sample-querier-7bbcc6dd9b-gtl4q 1/1 Running 0 10m |
| 206 | +tempo-sample-query-frontend-5885fff6bf-cklc5 2/2 Running 0 10m |
| 207 | +NAME READY STATUS RESTARTS AGE |
| 208 | +otel-collector-77b6b4b58d-dwk6q 1/1 Running 0 9m23s |
| 209 | +NAME READY STATUS RESTARTS AGE |
| 210 | +istiod-6847b886d5-s8vz8 1/1 Running 0 9m8s |
| 211 | +kiali-6b7dbdf67b-cczm5 1/1 Running 0 7m56s |
| 212 | +ossmconsole-7b64979c75-f9fbf 1/1 Running 0 7m22s |
| 213 | +NAME READY STATUS RESTARTS AGE |
| 214 | +istio-cni-node-8h4mr 1/1 Running 0 8m44s |
| 215 | +istio-cni-node-qvmw4 1/1 Running 0 8m44s |
| 216 | +istio-cni-node-vpv9v 1/1 Running 0 8m44s |
| 217 | +istio-cni-node-wml9b 1/1 Running 0 8m44s |
| 218 | +istio-cni-node-x8np2 1/1 Running 0 8m44s |
| 219 | +NAME READY STATUS RESTARTS AGE |
| 220 | +istio-ingressgateway-7f8878b6b4-6k8tj 1/1 Running 0 8m19s |
| 221 | +istio-ingressgateway-7f8878b6b4-f5744 1/1 Running 0 8m36s |
| 222 | +NAME READY STATUS RESTARTS AGE |
| 223 | +details-v1-65cfcf56f9-72k5p 2/2 Running 0 3m4s |
| 224 | +kiali-traffic-generator-cblht 2/2 Running 0 77s |
| 225 | +productpage-v1-d5789fdfb-rlkhl 2/2 Running 0 3m |
| 226 | +ratings-v1-7c9bd4b87f-5qmmp 2/2 Running 0 3m3s |
| 227 | +reviews-v1-6584ddcf65-mhd75 2/2 Running 0 3m2s |
| 228 | +reviews-v2-6f85cb9b7c-q8mc2 2/2 Running 0 3m2s |
| 229 | +reviews-v3-6f5b775685-ctb65 2/2 Running 0 3m1s |
| 230 | +``` |
0 commit comments