OpenShift - Container - Platform 4.3 Service - Mesh en US
OpenShift - Container - Platform 4.3 Service - Mesh en US
OpenShift - Container - Platform 4.3 Service - Mesh en US
Service Mesh
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is
available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must
provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift,
Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States
and other countries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States
and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.
Node.js ® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the
official Joyent Node.js open source or commercial project.
The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other
countries and are used with the OpenStack Foundation's permission. We are not affiliated with,
endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
Abstract
This document provides information on how to use Service Mesh in OpenShift Container Platform
Table of Contents
Table of Contents
.CHAPTER
. . . . . . . . . . 1.. .SERVICE
. . . . . . . . . .MESH
. . . . . . RELEASE
. . . . . . . . . . NOTES
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . . . . .
1.1. RED HAT OPENSHIFT SERVICE MESH OVERVIEW 5
1.2. GETTING SUPPORT 5
1.3. RED HAT OPENSHIFT SERVICE MESH SUPPORTED CONFIGURATIONS 5
1.3.1. Supported configurations for Kiali on Red Hat OpenShift Service Mesh 6
1.3.2. Supported Mixer adapters 6
1.3.3. New features Red Hat OpenShift Service Mesh 1.0.9 6
1.3.4. New features Red Hat OpenShift Service Mesh 1.0.8 6
1.3.5. New features Red Hat OpenShift Service Mesh 1.0.7 6
1.3.6. New features Red Hat OpenShift Service Mesh 1.0.6 7
1.3.7. New features Red Hat OpenShift Service Mesh 1.0.5 7
1.3.8. New features Red Hat OpenShift Service Mesh 1.0.4 7
1.3.9. New features Red Hat OpenShift Service Mesh 1.0.3 7
1.3.10. New features Red Hat OpenShift Service Mesh 1.0.2 7
1.3.11. New features Red Hat OpenShift Service Mesh 1.0.1 7
1.3.12. New features Red Hat OpenShift Service Mesh 1.0 7
1.4. KNOWN ISSUES 7
1.4.1. Red Hat OpenShift Service Mesh known issues 8
1.4.2. Kiali known issues 8
1.5. FIXED ISSUES 9
1.5.1. Red Hat OpenShift Service Mesh fixed issues 9
1.5.2. Kiali fixed issues 10
.CHAPTER
. . . . . . . . . . 2.
. . SERVICE
. . . . . . . . . .MESH
. . . . . . .ARCHITECTURE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11. . . . . . . . . . . . .
2.1. UNDERSTANDING RED HAT OPENSHIFT SERVICE MESH 11
2.1.1. Understanding service mesh 11
2.1.2. Red Hat OpenShift Service Mesh Architecture 11
2.1.3. Red Hat OpenShift Service Mesh control plane 12
2.1.4. Multi-tenancy in Red Hat OpenShift Service Mesh versus cluster-wide installations 12
2.1.5. Automatic injection 13
2.1.6. Istio Role Based Access Control features 13
2.1.7. OpenSSL 14
2.1.8. The Istio Container Network Interface (CNI) plug-in 14
2.2. KIALI OVERVIEW 14
2.2.1. Kiali overview 14
2.2.2. Kiali architecture 14
2.2.3. Kiali features 15
2.3. UNDERSTANDING JAEGER 16
2.3.1. Jaeger overview 16
2.3.2. Jaeger architecture 16
2.3.3. Jaeger features 17
2.4. COMPARING SERVICE MESH AND ISTIO 17
2.4.1. Red Hat OpenShift Service Mesh control plane 17
2.4.2. Multi-tenancy in Red Hat OpenShift Service Mesh versus cluster-wide installations 17
2.4.3. Automatic injection 18
2.4.4. Istio Role Based Access Control features 18
2.4.5. OpenSSL 19
2.4.6. The Istio Container Network Interface (CNI) plug-in 19
2.4.7. Kiali and service mesh 19
2.4.8. Jaeger and service mesh 20
1
OpenShift Container Platform 4.3 Service Mesh
.CHAPTER
. . . . . . . . . . 3.
. . SERVICE
. . . . . . . . . . MESH
. . . . . . .INSTALLATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
..............
3.1. PREPARING TO INSTALL RED HAT OPENSHIFT SERVICE MESH 21
3.1.1. Red Hat OpenShift Service Mesh supported configurations 21
3.1.1.1. Supported configurations for Kiali on Red Hat OpenShift Service Mesh 21
3.1.1.2. Supported Mixer adapters 22
3.1.2. Red Hat OpenShift Service Mesh installation activities 22
3.2. INSTALLING RED HAT OPENSHIFT SERVICE MESH 22
3.2.1. Installing the Operators from OperatorHub 23
3.2.1.1. Installing the Elasticsearch Operator 23
3.2.1.2. Installing the Jaeger Operator 24
3.2.1.3. Installing the Kiali Operator 25
3.2.1.4. Installing the Red Hat OpenShift Service Mesh Operator 26
3.2.1.5. Deploying the Red Hat OpenShift Service Mesh control plane 27
3.2.1.5.1. Deploying the control plane from the web console 27
3.2.1.5.2. Deploying the control plane from the CLI 28
3.2.1.6. Creating the Red Hat OpenShift Service Mesh member roll 29
3.2.1.6.1. Creating the member roll from the web console 29
3.2.1.6.2. Creating the member roll from the CLI 30
3.2.1.7. Adding or removing projects from the service mesh 31
3.2.1.7.1. Modifying the member roll from the web console 31
3.2.1.7.2. Modifying the member roll from the CLI 32
3.2.1.8. Deleting the Red Hat OpenShift Service Mesh member roll 32
3.2.2. Updating your application pods 33
3.3. CUSTOMIZING THE RED HAT OPENSHIFT SERVICE MESH INSTALLATION 33
3.3.1. Red Hat OpenShift Service Mesh custom resources 33
3.3.2. ServiceMeshControlPlane parameters 35
3.3.2.1. Istio global example 35
3.3.2.2. Istio gateway configuration 37
3.3.2.3. Istio Mixer configuration 38
3.3.2.4. Istio Pilot configuration 40
3.3.3. Configuring Kiali 41
3.3.3.1. Configuring Kiali for Grafana 42
3.3.3.2. Configuring Kiali for Jaeger 42
3.3.4. Configuring Jaeger 42
3.3.4.1. Configuring Elasticsearch 43
3.3.5. 3scale configuration 46
3.4. UPGRADING RED HAT OPENSHIFT SERVICE MESH 48
3.5. REMOVING RED HAT OPENSHIFT SERVICE MESH 48
3.5.1. Removing the Red Hat OpenShift Service Mesh control plane 48
3.5.1.1. Removing the control plane with the web console 48
3.5.1.2. Removing the control plane from the CLI 49
3.5.2. Removing the installed Operators 49
3.5.2.1. Removing the Red Hat OpenShift Service Mesh Operator 49
3.5.2.2. Removing the Jaeger Operator 50
3.5.2.3. Removing the Kiali Operator 50
3.5.2.4. Removing the Elasticsearch Operator 51
3.5.2.5. Clean up Operator resources 51
. . . . . . . . . . . 4.
CHAPTER . . .DAY
. . . . .TWO
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
..............
4.1. DEPLOYING APPLICATIONS ON RED HAT OPENSHIFT SERVICE MESH 53
4.1.1. Creating control plane templates 53
4.1.1.1. Creating the ConfigMap 53
4.1.2. Red Hat OpenShift Service Mesh's sidecar injection 54
2
Table of Contents
.CHAPTER
. . . . . . . . . . 5.
. . 3SCALE
. . . . . . . . . ADAPTER
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
..............
5.1. USING THE 3SCALE ISTIO ADAPTER 70
5.1.1. Integrate the 3scale adapter with Red Hat OpenShift Service Mesh 70
5.1.1.1. Generating 3scale custom resources 71
5.1.1.1.1. Generate templates from URL examples 72
5.1.1.2. Generating manifests from a deployed adapter 72
5.1.1.3. Routing service traffic through the adapter 73
5.1.2. Configure the integration settings in 3scale 73
5.1.3. Caching behavior 74
5.1.4. Authenticating requests 74
5.1.4.1. Applying authentication patterns 74
5.1.4.1.1. API key authentication method 74
5.1.4.1.2. Application ID and application key pair authentication method 75
5.1.4.1.3. OpenID authentication method 75
5.1.4.1.4. Hybrid authentication method 76
5.1.5. 3scale Adapter metrics 77
3
OpenShift Container Platform 4.3 Service Mesh
4
CHAPTER 1. SERVICE MESH RELEASE NOTES
The term service mesh describes the network of microservices that make up applications in a distributed
microservice architecture and the interactions between those microservices. As a service mesh grows in
size and complexity, it can become harder to understand and manage.
Based on the open source Istio project, Red Hat OpenShift Service Mesh adds a transparent layer on
existing distributed applications without requiring any changes to the service code. You add Red Hat
OpenShift Service Mesh support to services by deploying a special sidecar proxy throughout your
environment that intercepts all network communication between microservices. You configure and
manage the service mesh using the control plane features.
Red Hat OpenShift Service Mesh provides an easy way to create a network of deployed services that
provides discovery, load balancing, service-to-service authentication, failure recovery, metrics, and
monitoring. A service mesh also provides more complex operational functionality, including A/B testing,
canary releases, rate limiting, access control, and end-to-end authentication.
Search or browse through the Red Hat Knowledgebase of technical support articles about Red
Hat products
If you have a suggestion for improving this guide or have found an error, please submit a Bugzilla report
at http://bugzilla.redhat.com against Product for the Documentation component. Please provide
specific details, such as the section number, guide name, and Service Mesh version so we can easily
locate the content.
NOTE
OpenShift Online and OpenShift Dedicated are not supported for Red Hat OpenShift
Service Mesh 1.0.9.
The deployment must be contained to a single OpenShift Container Platform cluster that is not
5
OpenShift Container Platform 4.3 Service Mesh
The deployment must be contained to a single OpenShift Container Platform cluster that is not
federated.
This release of Red Hat OpenShift Service Mesh is only available on OpenShift Container
Platform x86_64.
This release only supports configurations where all Service Mesh components are contained in
the OpenShift cluster in which it operates. It does not support management of microservices
that reside outside of the cluster, or in a multi-cluster scenario.
This release only supports configurations that do not integrate external services such as virtual
machines.
1.3.1. Supported configurations for Kiali on Red Hat OpenShift Service Mesh
The Kiali observability console is only supported on the two most recent releases of the Chrome,
Edge, Firefox, or Safari browsers.
Red Hat OpenShift Service Mesh provides a number of key capabilities uniformly across a network of
services:
Traffic Management - Control the flow of traffic and API calls between services, make calls
more reliable, and make the network more robust in the face of adverse conditions.
Service Identity and Security - Provide services in the mesh with a verifiable identity and
provide the ability to protect service traffic as it flows over networks of varying degrees of
trustworthiness.
Policy Enforcement - Apply organizational policy to the interaction between services, ensure
access policies are enforced and resources are fairly distributed among consumers. Policy
changes are made by configuring the mesh, not by changing application code.
Telemetry - Gain understanding of the dependencies between services and the nature and flow
of traffic between them, providing the ability to quickly identify issues.
This release of Red Hat OpenShift Service Mesh addresses Common Vulnerabilities and Exposures
6
CHAPTER 1. SERVICE MESH RELEASE NOTES
This release of Red Hat OpenShift Service Mesh addresses Common Vulnerabilities and Exposures
(CVEs).
The control plane is configured for multitenancy by default. Single tenant, cluster-wide control
plane configurations are deprecated.
The Elasticsearch, Jaeger, Kiali, and Service Mesh Operators are installed from OperatorHub.
Red Hat OpenShift Service Mesh does not support IPv6 , as it is not supported by the upstream
7
OpenShift Container Platform 4.3 Service Mesh
Red Hat OpenShift Service Mesh does not support IPv6 , as it is not supported by the upstream
Istio project, nor fully supported by OpenShift.
Graph layout - The layout for the Kiali graph can render differently, depending on your
application architecture and the data to display (number of graph nodes and their interactions).
Because it is difficult if not impossible to create a single layout that renders nicely for every
situation, Kiali offers a choice of several different layouts. To choose a different layout, you can
choose a different Layout Schema from the Graph Settings menu.
Red Hat OpenShift Service Mesh does not support installation on a restricted network.
NOTE
While Kafka publisher is included in the release as part of Jaeger, it is not supported.
Istio-14743 Due to limitations in the version of Istio that this release of Red Hat OpenShift
Service Mesh is based on, there are several applications that are currently incompatible with
Service Mesh. See the linked community issue for details.
MAISTRA-858 The following Envoy log messages describing deprecated options and
configurations associated with Istio 1.1.x are expected:
[2019-06-03 07:03:28.943][19][warning][misc]
[external/envoy/source/common/protobuf/utility.cc:129] Using deprecated option
'envoy.api.v2.listener.Filter.config'. This configuration will be removed from Envoy soon.
[2019-08-12 22:12:59.001][13][warning][misc]
[external/envoy/source/common/protobuf/utility.cc:174] Using deprecated option
'envoy.api.v2.Listener.use_original_dst' from file lds.proto. This configuration will be
removed from Envoy soon.
MAISTRA-681 and KIALI-2686 When the control plane has many namespaces, it can lead to
performance issues.
MAISTRA-465 The Maistra operator fails to create a service for operator metrics.
MAISTRA-453 If you create a new project and deploy pods immediately, sidecar injection does
not occur. The operator fails to add the maistra.io/member-of before the pods are created,
therefore the pods must be deleted and recreated for sidecar injection to occur.
MAISTRA-193 Unexpected console info messages are visible when health checking is enabled
for citadel.
MAISTRA-158 Applying multiple gateways referencing the same hostname will cause all
gateways to stop functioning.
MAISTRA-806 Evicted Istio Operator Pod causes mesh and CNI not to deploy.
If the istio-operator pod is evicted while deploying the control pane, delete the evicted istio-
operator pod.
KIALI-3262 In the Kiali console, when you click on Distributed Tracing in the navigation or on a
8
CHAPTER 1. SERVICE MESH RELEASE NOTES
KIALI-3262 In the Kiali console, when you click on Distributed Tracing in the navigation or on a
Traces tab, you are asked to accept the certificate, and then asked to provide your OpenShift
login credentials. This happens due to an issue with how the framework displays the Trace pages
in the Console. The Workaround is to open the URL for the Jaeger console in another browser
window and log in. Then you can view the embedded tracing pages in the Kiali console.
KIALI-3239 If a Kiali Operator pod has failed with a status of “Evicted” it blocks the Kiali
operator from deploying. The workaround is to delete the Evicted pod and redeploy the Kiali
operator.
KIALI-2206 When you are accessing the Kiali console for the first time, and there is no cached
browser data for Kiali, the “View in Grafana” link on the Metrics tab of the Kiali Service Details
page redirects to the wrong location. The only way you would encounter this issue is if you are
accessing Kiali for the first time.
KIALI-507 Kiali does not support Internet Explorer 11. This is because the underlying frameworks
do not support Internet Explorer. To access the Kiali console, use one of the two most recent
versions of the Chrome, Edge, Firefox or Safari browser.
OSSM-92 Cancelling unsaved changes on the VS/DR YAML edit page does not cancel the
changes.
MAISTRA-932 Added the requires metadata to add dependency relationship between Jaeger
operator and Elasticsearch operator. Ensures that when the Jaeger operator is installed, it
automatically deploys the Elasticsearch operator if it is not available.
MAISTRA-833 Pilot stopped delivering configuration after many namespace deletions and re-
creations.
MAISTRA-684 The default Jaeger version in the istio-operator is 1.12.0, which does not match
Jaeger version 1.13.1 that shipped in Red Hat OpenShift Service Mesh 0.12.TechPreview.
MAISTRA-622 In Maistra 0.12.0/TP12, permissive mode does not work. The user has the option
to use Plain text mode or Mutual TLS mode, but not permissive.
9
OpenShift Container Platform 4.3 Service Mesh
MAISTRA-572 Jaeger cannot be used with Kiali. In this release Jaeger is configured to use the
OAuth proxy, but is also only configured to work through a browser and does not allow service
access. Kiali cannot properly communicate with the Jaeger endpoint and it considers Jaeger to
be disabled. See also TRACING-591.
MAISTRA-348 OpenShift 4 Beta on AWS does not support ingress gateway traffic on ports
other than 80 or 443. If you configure your ingress gateway to handle TCP traffic with a port
number other than 80 or 443, you have to use the service hostname provided by the AWS load
balancer rather than the OpenShift router as a workaround.
KIALI-3070 This bug only affects custom dashboards, not the default dashboards. When you
select labels in metrics settings and refresh the page, your selections are retained in the menu
but your selections are not displayed on the charts.
10
CHAPTER 2. SERVICE MESH ARCHITECTURE
Based on the open source Istio project, Red Hat OpenShift Service Mesh adds a transparent layer on
existing distributed applications without requiring any changes to the service code. You add Red Hat
OpenShift Service Mesh support to services by deploying a special sidecar proxy to relevant services in
the mesh that intercepts all network communication between microservices. You configure and manage
the Service Mesh using the control plane features.
Red Hat OpenShift Service Mesh gives you an easy way to create a network of deployed services that
provide:
Discovery
Load balancing
Service-to-service authentication
Failure recovery
Metrics
Monitoring
Red Hat OpenShift Service Mesh also provides more complex operational functions including:
A/B testing
Canary releases
Rate limiting
Access control
End-to-end authentication
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.
11
OpenShift Container Platform 4.3 Service Mesh
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, and 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 OpenShift Container Platform.
Red Hat OpenShift Service Mesh 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.
Every project in the members list will have a RoleBinding for each service account associated with a
control plane deployment and each control plane deployment will only watch those member projects.
Each member project has a maistra.io/member-of label added to it, where the member-of value is the
project containing the control plane installation.
Red Hat OpenShift Service Mesh configures each member project to ensure network access between
itself, the control plane, and other member projects. The exact configuration differs depending on how
OpenShift software-defined networking (SDN) is configured. See About OpenShift SDN for additional
details.
If the OpenShift Container Platform cluster is configured to use the SDN plug-in:
NetworkPolicy: Red Hat OpenShift Service Mesh creates a NetworkPolicy resource in each
member project allowing ingress to all pods from the other members and the control plane. If
12
CHAPTER 2. SERVICE MESH ARCHITECTURE
you remove a member from Service Mesh, this NetworkPolicy resource is deleted from the
project.
NOTE
This also restricts ingress to only member projects. If ingress from non-member
projects is required, you need to create a NetworkPolicy to allow that traffic
through.
Multitenant: Red Hat OpenShift Service Mesh joins the NetNamespace for each member
project to the NetNamespace of the control plane project (the equivalent of running oc adm
pod-network join-projects --to control-plane-project member-project). If you remove a
member from the Service Mesh, its NetNamespace is isolated from the control plane (the
equivalent of running oc adm pod-network isolate-projects member-project).
Red Hat OpenShift Service Mesh does not automatically inject the sidecar to any pods, but requires you
to specify the sidecar.istio.io/inject annotation as illustrated in the Automatic sidecar injection section.
The upstream Istio community installation includes options to perform exact header matches, match
wildcards in headers, or check for a header containing a specific prefix or suffix.
Red Hat OpenShift Service Mesh extends the ability to match request headers by using a regular
expression. Specify a property key of request.regex.headers with a regular expression.
apiVersion: "rbac.istio.io/v1alpha1"
kind: ServiceRoleBinding
metadata:
name: httpbin-client-binding
namespace: httpbin
spec:
subjects:
- user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
properties:
request.headers[<header>]: "value"
Red Hat OpenShift Service Mesh matching request headers by using regular expressions
apiVersion: "rbac.istio.io/v1alpha1"
kind: ServiceRoleBinding
13
OpenShift Container Platform 4.3 Service Mesh
metadata:
name: httpbin-client-binding
namespace: httpbin
spec:
subjects:
- user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
properties:
request.regex.headers[<header>]: "<regular expression>"
2.1.7. OpenSSL
Red Hat OpenShift Service Mesh replaces BoringSSL with OpenSSL. OpenSSL is a software library that
contains an open source implementation of the Secure Sockets Layer (SSL) and Transport Layer
Security (TLS) protocols. The Red Hat OpenShift Service Mesh Proxy binary dynamically links the
OpenSSL libraries (libssl and libcrypto) from the underlying Red Hat Enterprise Linux operating system.
Next steps
Prepare to install Red Hat OpenShift Service Mesh in your OpenShift Container Platform
environment.
Kiali provides an interactive graph view of your namespace in real time that provides visibility into
features like circuit breakers, request rates, latency, and even graphs of traffic flows. Kiali offers insights
about components at different levels, from Applications to Services and Workloads, and can display the
interactions with contextual information and charts on the selected graph node or edge. Kiali also
provides the ability to validate your Istio configurations, such as gateways, destination rules, virtual
services, mesh policies, and more. Kiali provides detailed metrics, and a basic Grafana integration is
available for advanced queries. Distributed tracing is provided by integrating Jaeger into the Kiali
console.
Kiali is installed by default as part of the Red Hat OpenShift Service Mesh.
14
CHAPTER 2. SERVICE MESH ARCHITECTURE
Kiali application (back end) – This component runs in the container application platform and
communicates with the service mesh components, retrieves and processes data, and exposes
this data to the console. The Kiali application does not need storage. When deploying the
application to a cluster, configurations are set in ConfigMaps and secrets.
Kiali console (front end) – The Kiali console is a web application. The Kiali application serves the
Kiali console, which then queries the back end for data in order to present it to the user.
In addition, Kiali depends on external services and components provided by the container application
platform and Istio.
Red Hat Service Mesh (Istio) - Istio is a Kiali requirement. Istio is the component that provides
and controls the service mesh. Although Kiali and Istio can be installed separately, Kiali depends
on Istio and will not work if it is not present. Kiali needs to retrieve Istio data and configurations,
which are exposed through Prometheus and the cluster API.
Prometheus - A dedicated Prometheus instance is included as part of the Red Hat OpenShift
Service Mesh installation. When Istio telemetry is enabled, metrics data is stored in Prometheus.
Kiali uses this Prometheus data to determine the mesh topology, display metrics, calculate
health, show possible problems, and so on. Kiali communicates directly with Prometheus and
assumes the data schema used by Istio Telemetery. Prometheus is an Istio dependency and a
hard dependency for Kiali, and many of Kiali’s features will not work without Prometheus.
Cluster API - Kiali uses the API of the OpenShift Container Platform (cluster API) in order to
fetch and resolve service mesh configurations. Kiali queries the cluster API to retrieve, for
example, definitions for namespaces, services, deployments, pods, and other entities. Kiali also
makes queries to resolve relationships between the different cluster entities. The cluster API is
also queried to retrieve Istio configurations like virtual services, destination rules, route rules,
gateways, quotas, and so on.
Jaeger - Jaeger is optional, but is installed by default as part of the Red Hat OpenShift Service
Mesh installation. When you install Jaeger as part of the default Red Hat OpenShift Service
Mesh installation, the Kiali console includes a tab to display Jaeger’s tracing data. Note that
tracing data will not be available if you disable Istio’s distributed tracing feature. Also note that
user must have access to the namespace where the control plane is installed in order to view
Jaeger data.
Grafana - Grafana is optional, but is installed by default as part of the Red Hat OpenShift
Service Mesh installation. When available, the metrics pages of Kiali display links to direct the
user to the same metric in Grafana. Note that user must have access to the namespace where
the control plane is installed in order to view links to the Grafana dashboard and view Grafana
data.
Topology – Visualize how your applications, services, or workloads communicate via the Kiali
graph.
Metrics – Predefined metrics dashboards let you chart service mesh and application
performance for Go, Node.js. Quarkus, Spring Boot, Thorntail and Vert.x. You can also create
your own custom dashboards.
Tracing – Integration with Jaeger lets you follow the path of a request through various
15
OpenShift Container Platform 4.3 Service Mesh
Tracing – Integration with Jaeger lets you follow the path of a request through various
microservices that make up an application.
Validations – Perform advanced validations on the most common Istio objects (Destination
Rules, Service Entries, Virtual Services, and so on).
Configuration – Optional ability to create, update and delete Istio routing configuration using
wizards or directly in the YAML editor in the Kiali Console.
Distributed tracing is a technique that is used to tie the information about different units of work
together—usually executed in different processes or hosts—in order to understand a whole chain of
events in a distributed transaction. Distributed tracing lets developers visualize call flows in large service
oriented architectures. It can be invaluable in understanding serialization, parallelism, and sources of
latency.
Jaeger records the execution of individual requests across the whole stack of microservices, and
presents them as traces. A trace is a data/execution path through the system. An end-to-end trace is
comprised of one or more spans.
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.
Jaeger Client (Tracer, Reporter, instrumented application, client libraries)- Jaeger clients are
language specific implementations of the OpenTracing API. They can be used to instrument
applications for distributed tracing either manually or with a variety of existing open source
frameworks, such as Camel (Fuse), Spring Boot (RHOAR), MicroProfile (RHOAR/Thorntail),
Wildfly (EAP), and many more, that are already integrated with OpenTracing.
Jaeger Agent (Server Queue, Processor Workers) - The Jaeger agent is a network daemon
16
CHAPTER 2. SERVICE MESH ARCHITECTURE
Jaeger Agent (Server Queue, Processor Workers) - The Jaeger agent is a network daemon
that listens for spans sent over User Datagram Protocol (UDP), which it batches and sends to
the collector. The agent is meant to be placed on the same host as the instrumented
application. This is typically accomplished by having a sidecar in container environments like
Kubernetes.
Jaeger Collector (Queue, Workers) - Similar to the Agent, the Collector is able to receive
spans and place them in an internal queue for processing. This allows the collector to return
immediately to the client/agent instead of waiting for the span to make its way to the storage.
Storage (Data Store) - Collectors require a persistent storage backend. Jaeger has a pluggable
mechanism for span storage. Note that for this release, the only supported storage is
Elasticsearch.
Query (Query Service) - Query is a service that retrieves traces from storage.
Jaeger Console – Jaeger provides a user interface that lets you visualize your distributed
tracing data. On the Search page, you can find traces and explore details of the spans that
make up an individual trace.
Integration with Kiali – When properly configured, you can view Jaeger data from the Kiali
console.
High scalability – The Jaeger backend is designed to have no single points of failure and to scale
with the business needs.
Distributed Context Propagation – Lets you connect data from different components together
to create a complete end-to-end trace.
Backwards compatibility with Zipkin – Jaeger provides backwards compatibility with Zipkin by
accepting spans in Zipkin formats (Thrift or JSON v1/v2) over HTTP.
The current release of Red Hat OpenShift Service Mesh differs from the current upstream Istio
community release in the following ways:
The main difference between a multi-tenant installation and a cluster-wide installation is the scope of
17
OpenShift Container Platform 4.3 Service Mesh
The main difference between a multi-tenant installation and a cluster-wide installation is the scope of
privileges used by the control plane deployments, for example, Galley and Pilot. The components no
longer use cluster-scoped Role Based Access Control (RBAC) resource ClusterRoleBinding, but rely
on project-scoped RoleBinding.
Every project in the members list will have a RoleBinding for each service account associated with a
control plane deployment and each control plane deployment will only watch those member projects.
Each member project has a maistra.io/member-of label added to it, where the member-of value is the
project containing the control plane installation.
Red Hat OpenShift Service Mesh configures each member project to ensure network access between
itself, the control plane, and other member projects. The exact configuration differs depending on how
OpenShift software-defined networking (SDN) is configured. See About OpenShift SDN for additional
details.
If the OpenShift Container Platform cluster is configured to use the SDN plug-in:
NetworkPolicy: Red Hat OpenShift Service Mesh creates a NetworkPolicy resource in each
member project allowing ingress to all pods from the other members and the control plane. If
you remove a member from Service Mesh, this NetworkPolicy resource is deleted from the
project.
NOTE
This also restricts ingress to only member projects. If ingress from non-member
projects is required, you need to create a NetworkPolicy to allow that traffic
through.
Multitenant: Red Hat OpenShift Service Mesh joins the NetNamespace for each member
project to the NetNamespace of the control plane project (the equivalent of running oc adm
pod-network join-projects --to control-plane-project member-project). If you remove a
member from the Service Mesh, its NetNamespace is isolated from the control plane (the
equivalent of running oc adm pod-network isolate-projects member-project).
Red Hat OpenShift Service Mesh does not automatically inject the sidecar to any pods, but requires you
to specify the sidecar.istio.io/inject annotation as illustrated in the Automatic sidecar injection section.
The upstream Istio community installation includes options to perform exact header matches, match
wildcards in headers, or check for a header containing a specific prefix or suffix.
Red Hat OpenShift Service Mesh extends the ability to match request headers by using a regular
expression. Specify a property key of request.regex.headers with a regular expression.
18
CHAPTER 2. SERVICE MESH ARCHITECTURE
apiVersion: "rbac.istio.io/v1alpha1"
kind: ServiceRoleBinding
metadata:
name: httpbin-client-binding
namespace: httpbin
spec:
subjects:
- user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
properties:
request.headers[<header>]: "value"
Red Hat OpenShift Service Mesh matching request headers by using regular expressions
apiVersion: "rbac.istio.io/v1alpha1"
kind: ServiceRoleBinding
metadata:
name: httpbin-client-binding
namespace: httpbin
spec:
subjects:
- user: "cluster.local/ns/istio-system/sa/istio-ingressgateway-service-account"
properties:
request.regex.headers[<header>]: "<regular expression>"
2.4.5. OpenSSL
Red Hat OpenShift Service Mesh replaces BoringSSL with OpenSSL. OpenSSL is a software library that
contains an open source implementation of the Secure Sockets Layer (SSL) and Transport Layer
Security (TLS) protocols. The Red Hat OpenShift Service Mesh Proxy binary dynamically links the
OpenSSL libraries (libssl and libcrypto) from the underlying Red Hat Enterprise Linux operating system.
Users should not manually edit the ConfigMap or the Kiali custom resource files as those
19
OpenShift Container Platform 4.3 Service Mesh
Users should not manually edit the ConfigMap or the Kiali custom resource files as those
changes might be overwritten by the Service Mesh or Kiali operators. All configuration for Kiali
running on Red Hat OpenShift Service Mesh is done in the ServiceMeshControlPlane custom
resource file and there are limited configuration options. Updating the operator files should be
restricted to those users with cluster-admin privileges.
The name for the Zipkin port name has changed to jaeger-collector-zipkin (from http)
The community version of Istio provides a generic "tracing" route. Red Hat OpenShift Service
Mesh uses a "jaeger" route that is installed by the Jaeger operator and is already protected by
OAuth.
Red Hat OpenShift Service Mesh uses a sidecar for the Envoy proxy, and Jaeger also uses a
sidecar, for the Jaeger agent. These two sidecars are configured separately and should not be
confused with each other. The proxy sidecar creates spans related to the pod’s ingress and
egress traffic. The agent sidecar receives the spans emitted by the application and sends them
to the Jaeger Collector.
20
CHAPTER 3. SERVICE MESH INSTALLATION
Prerequisites
Possess an active OpenShift Container Platform subscription on your Red Hat account. If you
do not have a subscription, contact your sales representative for more information.
Install the version of the OpenShift Container Platform command line utility (the oc client tool)
that matches your OpenShift Container Platform version and add it to your path.
If you are using OpenShift Container Platform 4.3, see About the CLI.
NOTE
OpenShift Online and OpenShift Dedicated are not supported for Red Hat OpenShift
Service Mesh 1.0.9.
The deployment must be contained to a single OpenShift Container Platform cluster that is not
federated.
This release of Red Hat OpenShift Service Mesh is only available on OpenShift Container
Platform x86_64.
This release only supports configurations where all Service Mesh components are contained in
the OpenShift cluster in which it operates. It does not support management of microservices
that reside outside of the cluster, or in a multi-cluster scenario.
This release only supports configurations that do not integrate external services such as virtual
machines.
3.1.1.1. Supported configurations for Kiali on Red Hat OpenShift Service Mesh
The Kiali observability console is only supported on the two most recent releases of the Chrome,
21
OpenShift Container Platform 4.3 Service Mesh
The Kiali observability console is only supported on the two most recent releases of the Chrome,
Edge, Firefox, or Safari browsers.
WARNING
Please see configuring Elasticsearch for details on configuring the default Jaeger
parameters for Elasticsearch in a production environment.
Elasticsearch - Based on the open source Elasticsearch project that enables you to configure
and manage an Elasticsearch cluster for tracing and logging with Jaeger.
Jaeger - based on the open source Jaeger project, lets you perform tracing to monitor and
troubleshoot transactions in complex distributed systems.
Kiali - based on the open source Kiali project, provides observability for your service mesh. By
using Kiali you can view configurations, monitor traffic, and view and analyze traces in a single
console.
After you install the Elasticsearch, Jaeger, and Kiali Operators, then you install the Red Hat OpenShift
Service Mesh Operator. The Service Mesh Operator defines and monitors the
ServiceMeshControlPlane resources that manage the deployment, updating, and deletion of the
Service Mesh components.
Red Hat OpenShift Service Mesh - based on the open source Istio project, lets you connect,
secure, control, and observe the microservices that make up your applications.
Next steps
Install Red Hat OpenShift Service Mesh in your OpenShift Container Platform environment.
NOTE
22
CHAPTER 3. SERVICE MESH INSTALLATION
NOTE
Mixer’s policy enforcement is disabled by default. You must enable it to run policy tasks.
See Update Mixer policy enforcement for instructions on enabling Mixer policy
enforcement.
NOTE
Multi-tenant control plane installations are the default configuration starting with Red
Hat OpenShift Service Mesh 1.0.
NOTE
The Service Mesh documentation uses istio-system as the example project, but you may
deploy the service mesh to any project.
Prerequisites
Follow the Preparing to install Red Hat OpenShift Service Mesh process.
Starting with Red Hat OpenShift Service Mesh 1.0.9, you must install the Elasticsearch Operator, the
Jaeger Operator, and the Kiali Operator before the Red Hat OpenShift Service Mesh Operator can
install the control plane.
You must install the Elasticsearch Operator for the Red Hat OpenShift Service Mesh Operator to install
the control plane.
WARNING
Do not install Community versions of the Operators. Community Operators are not
supported.
Prerequisites
Procedure
23
OpenShift Container Platform 4.3 Service Mesh
3. Type Elasticsearch into the filter box to locate the Elasticsearch Operator.
5. Click Install.
6. On the Create Operator Subscription page, select All namespaces on the cluster (default).
This installs the Operator in the default openshift-operators project and makes the Operator
available to all projects in the cluster.
NOTE
9. Click Subscribe.
10. The Subscription Overview page displays the Elasticsearch Operator’s installation progress.
You must install the Jaeger Operator for the Red Hat OpenShift Service Mesh Operator to install the
control plane.
WARNING
Do not install Community versions of the Operators. Community Operators are not
supported.
Prerequisites
Procedure
3. Type Jaeger into the filter box to locate the Jaeger Operator.
4. Click the Jaeger Operator provided by Red Hat to display information about the Operator.
24
CHAPTER 3. SERVICE MESH INSTALLATION
5. Click Install.
6. On the Create Operator Subscription page, select All namespaces on the cluster (default).
This installs the Operator in the default openshift-operators project and makes the Operator
available to all projects in the cluster.
NOTE
9. Click Subscribe.
10. The Subscription Overview page displays the Jaeger Operator’s installation progress.
You must install the Kiali Operator for the Red Hat OpenShift Service Mesh Operator to install the
control plane.
WARNING
Do not install Community versions of the Operators. Community Operators are not
supported.
Prerequisites
Procedure
3. Type Kiali into the filter box to find the Kiali Operator.
4. Click the Kiali Operator provided by Red Hat to display information about the Operator.
5. Click Install.
6. On the Create Operator Subscription page, select All namespaces on the cluster (default).
This installs the Operator in the default openshift-operators project and makes the Operator
available to all projects in the cluster.
25
OpenShift Container Platform 4.3 Service Mesh
NOTE
9. Click Subscribe.
10. The Subscription Overview page displays the Kiali Operator’s installation progress.
Prerequisites
Procedure
3. Type Red Hat OpenShift Service Mesh into the filter box to find the Red Hat OpenShift
Service Mesh Operator.
4. Click the Red Hat OpenShift Service Mesh Operator to display information about the Operator.
5. On the Create Operator Subscription page, select All namespaces on the cluster (default).
This installs the Operator in the default openshift-operators project and makes the Operator
available to all projects in the cluster.
6. Click Install.
NOTE
9. Click Subscribe.
10. The Subscription Overview page displays the Red Hat OpenShift Service Mesh Operator’s
installation progress.
26
CHAPTER 3. SERVICE MESH INSTALLATION
3.2.1.5. Deploying the Red Hat OpenShift Service Mesh control plane
The ServiceMeshControlPlane resource defines the configuration to be used during installation. You
can deploy the default configuration provided by Red Hat or customize the ServiceMeshControlPlane
file to fit your business needs.
You can deploy the Service Mesh control plane by using the OpenShift Container Platform web console
or from the command line using the oc client tool.
Follow this procedure to deploy the Red Hat OpenShift Service Mesh control plane by using the web
console.
Prerequisites
Review the instructions for how to customize the Red Hat OpenShift Service Mesh installation.
Procedure
1. Log in to the OpenShift Container Platform web console as a user with the cluster-admin role.
d. Click Create.
4. If necessary, select istio-system from the Project menu. You may have to wait a few moments
for the Operators to be copied to the new project.
5. Click the Red Hat OpenShift Service Mesh Operator. Under Provided APIs, the Operator
provides links to create two resource types:
A ServiceMeshControlPlane resource
A ServiceMeshMemberRoll resource
7. On the Create Service Mesh Control Planepage, modify the YAML for the default
ServiceMeshControlPlane template as needed.
NOTE
27
OpenShift Container Platform 4.3 Service Mesh
NOTE
For additional information about customizing the control plane, see customizing
the Red Hat OpenShift Service Mesh installation. Note that for production use
you must change the default Jaeger template.
8. Click Create to create the control plane. The Operator creates Pods, services, and Service
Mesh control plane components based on your configuration parameters.
11. Click the Resources tab to see the Red Hat OpenShift Service Mesh control plane resources
the Operator created and configured.
Follow this procedure to deploy the Red Hat OpenShift Service Mesh control plane the command line.
Prerequisites
Review the instructions for how to customize the Red Hat OpenShift Service Mesh installation.
Access to the OpenShift Container Platform Command-line Interface (CLI), commonly known
as oc.
Procedure
1. Log in to the OpenShift Container Platform CLI as a user with the cluster-admin role.
$ oc login https://{HOSTNAME}:8443
$ oc new-project istio-system
5. Execute the following command to see the status of the control plane installation.
28
CHAPTER 3. SERVICE MESH INSTALLATION
The installation has finished successfully when the READY column is true.
NAME READY
basic-install True
6. Run the following command to watch the progress of the Pods during the installation process:
For a multitenant installation, Red Hat OpenShift Service Mesh supports multiple independent control
planes within the cluster. You can create reusable configurations with ServiceMeshControlPlane
templates. For more information, see Creating control plane templates .
3.2.1.6. Creating the Red Hat OpenShift Service Mesh member roll
The ServiceMeshMemberRoll lists the projects belonging to the control plane. Only projects listed in
the ServiceMeshMemberRoll are affected by the control plane. A project does not belong to a service
mesh until you add it to the member roll for a particular control plane deployment.
You must create a ServiceMeshMemberRoll resource named default in the same project as the
ServiceMeshControlPlane.
NOTE
The member projects are only updated if the Service Mesh control plane installation
succeeds.
Follow this procedure to add one or more projects to the Service Mesh member roll by using the web
console.
Prerequisites
29
OpenShift Container Platform 4.3 Service Mesh
Procedure
3. Click the Project menu and choose the project where your ServiceMeshControlPlane is
deployed from the list, for example istio-system.
6. Click Create New, and then select Create Istio Service Mesh Member Roll.
NOTE
It can take a short time for the Operator to finish copying the resources,
therefore you may need to refresh the screen to see the Create Istio Service
Mesh Member Roll button.
7. On the Create Service Mesh Member Rollpage, modify the YAML to add your projects as
members. You can add any number of projects, but a project can only belong to one
ServiceMeshMemberRoll resource.
Follow this procedure to add a project to the ServiceMeshMemberRoll from the command line.
Prerequisites
Access to the OpenShift Container Platform Command-line Interface (CLI) commonly known
as oc.
Procedure
$ oc login
30
CHAPTER 3. SERVICE MESH INSTALLATION
Example servicemeshmemberroll-default.yaml
apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
name: default
namespace: istio-system
spec:
members:
# a list of projects joined into the service mesh
- your-project-name
- another-project-name
3. Modify the default YAML to add your projects as members. You can add any number of
projects, but a project can only belong to one ServiceMeshMemberRoll resource.
Follow this procedure to modify an existing Service Mesh ServiceMeshMemberRoll resource using the
web console.
You can add any number of projects, but a project can only belong to one
ServiceMeshMemberRoll resource.
Prerequisites
Names of the projects you want to add or remove from the mesh.
Procedure
3. Click the Project menu and choose the project where your ServiceMeshControlPlane is
deployed from the list, for example istio-system.
31
OpenShift Container Platform 4.3 Service Mesh
8. Modify the YAML to add or remove projects as members. You can add any number of projects,
but a project can only belong to one ServiceMeshMemberRoll resource.
9. Click Save.
Follow this procedure to modify an existing Service Mesh member roll using the command line.
Prerequisites
Names of the projects you want to add or remove from the mesh.
Access to the OpenShift Container Platform Command-line Interface (CLI) commonly known
as oc.
Procedure
3. Modify the YAML to add or remove projects as members. You can add any number of projects,
but a project can only belong to one ServiceMeshMemberRoll resource.
Example servicemeshmemberroll-default.yaml
apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
name: default
namespace: istio-system
spec:
members:
# a list of projects joined into the service mesh
- your-project-name
- another-project-name
3.2.1.8. Deleting the Red Hat OpenShift Service Mesh member roll
32
CHAPTER 3. SERVICE MESH INSTALLATION
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:
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.
Next steps
Prerequisites
Completed the Preparing to install Red Hat OpenShift Service Mesh process.
NOTE
A custom resource allows you to extend the API in an Red Hat OpenShift Service Mesh project or
cluster. When you deploy Service Mesh it creates a default ServiceMeshControlPlane that you can
modify to change the project parameters.
The Service Mesh operator extends the API by adding the ServiceMeshControlPlane resource type,
which enables you to create ServiceMeshControlPlane objects within projects. By creating a
ServiceMeshControlPlane object, you instruct the Operator to install a Service Mesh control plane into
the project, configured with the parameters you set in the ServiceMeshControlPlane object.
This example ServiceMeshControlPlane definition contains all of the supported parameters and
33
OpenShift Container Platform 4.3 Service Mesh
This example ServiceMeshControlPlane definition contains all of the supported parameters and
deploys Red Hat OpenShift Service Mesh 1.0.9 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 (SaaS or On-Premises).
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
metadata:
name: full-install
spec:
istio:
global:
proxy:
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 128Mi
gateways:
istio-egressgateway:
autoscaleEnabled: false
istio-ingressgateway:
autoscaleEnabled: false
mixer:
policy:
autoscaleEnabled: false
telemetry:
autoscaleEnabled: false
resources:
requests:
cpu: 100m
memory: 1G
limits:
cpu: 500m
memory: 4G
pilot:
autoscaleEnabled: false
traceSampling: 100
kiali:
enabled: true
grafana:
34
CHAPTER 3. SERVICE MESH INSTALLATION
enabled: true
tracing:
enabled: true
jaeger:
template: all-in-one
The following examples illustrate use of the ServiceMeshControlPlane parameters and the tables
provide additional information about supported parameters.
IMPORTANT
The resources you configure for Red Hat OpenShift Service Mesh with these parameters,
including CPUs, memory, and the number of pods, are based on the configuration of your
OpenShift cluster. Configure these parameters based on the available resources in your
current cluster configuration.
Here is an example that illustrates the Istio global parameters for the ServiceMeshControlPlane and a
description of the available parameters with appropriate values.
NOTE
In order for the 3scale Istio Adapter to work, disablePolicyChecks must be false.
istio:
global:
tag: 1.0.0
hub: registry.redhat.io/openshift-service-mesh/
proxy:
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 128Mi
mtls:
enabled: false
disablePolicyChecks: true
policyCheckFailOpen: false
imagePullSecrets:
- MyPullSecret
35
OpenShift Container Platform 4.3 Service Mesh
36
CHAPTER 3. SERVICE MESH INSTALLATION
Here is an example that illustrates the Istio gateway parameters for the ServiceMeshControlPlane and
a description of the available parameters with appropriate values.
gateways:
istio-egressgateway:
autoscaleEnabled: false
autoscaleMin: 1
autoscaleMax: 5
istio-ingressgateway:
autoscaleEnabled: false
autoscaleMin: 1
autoscaleMax: 5
37
OpenShift Container Platform 4.3 Service Mesh
Here is an example that illustrates the Mixer parameters for the ServiceMeshControlPlane and a
description of the available parameters with appropriate values.
mixer:
enabled: true
policy:
38
CHAPTER 3. SERVICE MESH INSTALLATION
autoscaleEnabled: false
telemetry:
autoscaleEnabled: false
resources:
limits:
cpu: 500m
memory: 4G
requests:
cpu: 100m
memory: 1G
39
OpenShift Container Platform 4.3 Service Mesh
Here is an example that illustrates the Istio Pilot parameters for the ServiceMeshControlPlane and a
description of the available parameters with appropriate values.
pilot:
resources:
requests:
cpu: 100m
memory: 128Mi
autoscaleEnabled: false
traceSampling: 100
40
CHAPTER 3. SERVICE MESH INSTALLATION
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
spec:
kiali:
enabled: true
dashboard:
viewOnlyMode: false
ingress:
enabled: true
41
OpenShift Container Platform 4.3 Service Mesh
When you install Kiali and Grafana as part of Red Hat OpenShift Service Mesh the Operator configures
the following by default:
Kiali can automatically detect the Grafana URL. However if you have a custom Grafana installation that
is not easily auto-detectable by Kiali, you must update the URL value in the ServiceMeshControlPlane
resource.
spec:
kiali:
enabled: true
dashboard:
viewOnlyMode: false
grafanaURL: "https://grafana-istio-system.127.0.0.1.nip.io"
ingress:
enabled: true
When you install Kiali and Jaeger as part of Red Hat OpenShift Service Mesh the Operator configures
the following by default:
Kiali can automatically detect the Jaeger URL. However if you have a custom Jaeger installation that is
not easily auto-detectable by Kiali, you must update the URL value in the ServiceMeshControlPlane
resource.
spec:
kiali:
enabled: true
dashboard:
viewOnlyMode: false
jaegerURL: "http://jaeger-query-istio-system.127.0.0.1.nip.io"
ingress:
enabled: true
When the Service Mesh Operator creates the ServiceMeshControlPlane resource it also creates the
42
CHAPTER 3. SERVICE MESH INSTALLATION
When the Service Mesh Operator creates the ServiceMeshControlPlane resource it also creates the
Jaeger resource. The Jaeger Operator then uses this object when creating Jaeger instances.
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
spec:
istio:
tracing:
enabled: true
jaeger:
template: all-in-one
production-
elasticsearch
- For
production use.
NOTE
The default Jaeger deployment strategy uses the all-in-one template so that the installation can be
completed using minimal resources. However, because the all-in-one template uses in-memory storage,
it is only recommended for development, demo, or testing purposes and should NOT be used for
production environments.
If you are deploying Service Mesh and Jaeger in a production environment you must change the
43
OpenShift Container Platform 4.3 Service Mesh
If you are deploying Service Mesh and Jaeger in a production environment you must change the
template to the production-elasticsearch template, which uses Elasticsearch for Jaeger’s storage
needs.
Elasticsearch is a memory intensive application. The initial set of nodes specified in the default
OpenShift Container Platform installation may not be large enough to support the Elasticsearch cluster.
You should modify the default Elasticsearch configuration to match your use case and the resources
you have requested for your OpenShift Container Platform installation. You can adjust both the CPU
and memory limits for each component by modifying the resources block with valid CPU and memory
values. Additional nodes must be added to the cluster if you want to run with the recommended amount
(or more) of memory. Ensure that you do not exceed the resources requested for your OpenShift
Container Platform installation.
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
spec:
istio:
tracing:
enabled: true
ingress:
enabled: true
jaeger:
template: production-elasticsearch
elasticsearch:
nodeCount: 3
redundancyPolicy:
resources:
requests:
cpu: "1"
memory: "16Gi"
limits:
cpu: "1"
memory: "16Gi"
44
CHAPTER 3. SERVICE MESH INSTALLATION
* Each Elasticsearch node can operate with a lower memory setting though this is not
recommended for production deployments. For production use, you should have no
less than 16Gi allocated to each Pod by default, but preferably allocate as much as you
can, up to 64Gi per Pod.
Procedure
1. Log in to the OpenShift Container Platform web console as a user with the cluster-admin role.
45
OpenShift Container Platform 4.3 Service Mesh
5. Click the name of your control plane file, for example, basic-install.
7. Edit the Jaeger parameters, replacing the default all-in-one template with parameters for the
production-elasticsearch template, modified for your use case. Ensure that the indentation is
correct.
8. Click Save.
9. Click Reload. OpenShift Container Platform redeploys Jaeger and creates the Elasticsearch
resources based on the specified parameters.
For more information about configuring Elasticsearch with OpenShift Container Platform, see
Configuring Elasticsearch.
threeScale:
enabled: false
PARAM_THREESCALE_LISTEN_ADDR: 3333
PARAM_THREESCALE_LOG_LEVEL: info
PARAM_THREESCALE_LOG_JSON: true
PARAM_THREESCALE_LOG_GRPC: false
PARAM_THREESCALE_REPORT_METRICS: true
PARAM_THREESCALE_METRICS_PORT: 8080
PARAM_THREESCALE_CACHE_TTL_SECONDS: 300
PARAM_THREESCALE_CACHE_REFRESH_SECONDS: 180
PARAM_THREESCALE_CACHE_ENTRIES_MAX: 1000
PARAM_THREESCALE_CACHE_REFRESH_RETRIES: 1
PARAM_THREESCALE_ALLOW_INSECURE_CONN: false
PARAM_THREESCALE_CLIENT_TIMEOUT_SECONDS: 10
PARAM_THREESCALE_GRPC_CONN_MAX_SECONDS: 60
46
CHAPTER 3. SERVICE MESH INSTALLATION
PARAM_THREESCA Sets the port that the Valid port number 8080
LE_METRICS_PORT 3scale /metrics
endpoint can be
scrapped from
47
OpenShift Container Platform 4.3 Service Mesh
Next steps
If you choose to update manually, the Operator Lifecycle Manager (OLM) controls the installation,
upgrade, and role-based access control (RBAC) of Operators in a cluster. OLM runs by default in
OpenShift Container Platform. OLM uses CatalogSources, which use the Operator Registry API, to
query for available Operators as well as upgrades for installed Operators.
For more information about how OpenShift Container Platform handled upgrades, refer to the
Operator Lifecycle Manager documentation.
3.5.1. Removing the Red Hat OpenShift Service Mesh control plane
You can remove the Service Mesh control plane by using the OpenShift Container Platform web console
or the CLI.
Follow this procedure to remove the Red Hat OpenShift Service Mesh control plane by using the web
console.
Prerequisites
The Red Hat OpenShift Service Mesh control plane must be deployed.
Procedure
2. Click the Project menu and choose the istio-system project from the list.
48
CHAPTER 3. SERVICE MESH INSTALLATION
Follow this procedure to remove the Red Hat OpenShift Service Mesh control plane by using the CLI.
Prerequisites
The Red Hat OpenShift Service Mesh control plane must be deployed.
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc.
PROCEDURE
When you remove the ServiceMeshControlPlane, Service Mesh tells the Operator to
begin uninstalling everything it installed.
TIP
3. Replace <name_of_custom_resource> with the output from the previous command, and run
this command to remove the custom resource:
Follow this procedure to remove the Red Hat OpenShift Service Mesh Operator.
Prerequisites
49
OpenShift Container Platform 4.3 Service Mesh
Procedure
2. From the Operators → Installed Operators page, scroll or type a keyword into the Filter by
name to find the Red Hat OpenShift Service Mesh Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the
Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also
completely remove the Operator from the selected namespace check box if you want all
components related to the installation to be removed. This removes the CSV, which in turn
removes the Pods, Deployments, CRDs, and CRs associated with the Operator.
Prerequisites
Procedure
2. From the Operators → Installed Operators page, scroll or type a keyword into the Filter by
name to find the Jaeger Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the
Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also
completely remove the Operator from the selected namespace check box if you want all
components related to the installation to be removed. This removes the CSV, which in turn
removes the Pods, Deployments, CRDs, and CRs associated with the Operator.
Prerequisites
Procedure
50
CHAPTER 3. SERVICE MESH INSTALLATION
2. From the Operators → Installed Operators page, scroll or type a keyword into the Filter by
name to find the Kiali Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the
Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also
completely remove the Operator from the selected namespace check box if you want all
components related to the installation to be removed. This removes the CSV, which in turn
removes the Pods, Deployments, CRDs, and CRs associated with the Operator.
Prerequisites
Procedure
2. From the Operators → Installed Operators page, scroll or type a keyword into the Filter by
name to find the Elasticsearch Operator. Then, click on it.
3. On the right-hand side of the Operator Details page, select Uninstall Operator from the
Actions drop-down menu.
4. When prompted by the Remove Operator Subscription window, optionally select the Also
completely remove the Operator from the selected namespace check box if you want all
components related to the installation to be removed. This removes the CSV, which in turn
removes the Pods, Deployments, CRDs, and CRs associated with the Operator.
Follow this procedure to manually remove resources left behind after removing the Red Hat OpenShift
Service Mesh Operator by using the OperatorHub interface.
Prerequisites
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc.
Procedure
2. Run the following commands to clean up resources after uninstalling the Operators:
NOTE
51
OpenShift Container Platform 4.3 Service Mesh
NOTE
Replace <operator-project> with the name of the project where the Red Hat
OpenShift Service Mesh Operator was installed. This is typically openshift-
operators.
$ oc delete validatingwebhookconfiguration/<operator-project>.servicemesh-
resources.maistra.io
$ oc delete -n <operator-project> daemonset/istio-node
$ oc delete clusterrole/istio-admin clusterrole/istio-cni clusterrolebinding/istio-cni
$ oc get crds -o name | grep '.*\.istio\.io' | xargs -r -n 1 oc delete
$ oc get crds -o name | grep '.*\.maistra\.io' | xargs -r -n 1 oc delete
52
CHAPTER 4. DAY TWO
Prerequisites
Review Comparing Red Hat OpenShift Service Mesh and upstream Istio community installations
When you configure control plane templates, which follow the same syntax as the
ServiceMeshControlPlane, users inherit settings in a hierarchical fashion. The Operator is delivered
with a default template with default settings for Red Hat OpenShift Service Mesh. To add custom
templates you must create a ConfigMap named smcp-templates in the openshift-operators project
and mount the ConfigMap in the Operator container at /usr/local/share/istio-operator/templates.
Prerequisites
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc.
Procedure
2. From the CLI, run this command to create the ConfigMap named smcp-templates in the
openshift-operators project and replace <templates-directory> with the location of the
ServiceMeshControlPlane files on your local disk:
53
OpenShift Container Platform 4.3 Service Mesh
4. Edit the Operator cluster service version to instruct the Operator to use the smcp-templates
ConfigMap.
deployments:
- name: istio-operator
spec:
template:
spec:
containers:
volumeMounts:
- name: discovery-cache
mountPath: /home/istio-operator/.kube/cache/discovery
- name: smcp-templates
mountPath: /usr/local/share/istio-operator/templates/
volumes:
- name: discovery-cache
emptyDir:
medium: Memory
- name: smcp-templates
configMap:
name: smcp-templates
...
7. You can now use the template parameter in the ServiceMeshControlPlane to specify a
template.
apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
metadata:
name: minimal-install
spec:
template: default
NOTE
54
CHAPTER 4. DAY TWO
NOTE
The upstream version of Istio injects the sidecar by default if you have labeled the project.
Red Hat OpenShift Service Mesh requires you to opt in to having the sidecar
automatically injected to a deployment, so you are not required to label the project. This
avoids injecting a sidecar if it is not wanted (for example, in build or deploy pods).
The webhook checks the configuration of pods deploying into all projects to see if they
are opting in to injection with the appropriate annotation.
When deploying an application into the Red Hat OpenShift Service Mesh 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.
Procedure
2. Add sidecar.istio.io/inject to the configuration YAML with a value of "true" as illustrated here:
apiVersion: apps/v1
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
In previous versions of Red Hat OpenShift Service Mesh, Mixer’s policy enforcement was enabled by
55
OpenShift Container Platform 4.3 Service Mesh
In previous versions of Red Hat OpenShift Service Mesh, Mixer’s policy enforcement was enabled by
default. Mixer policy enforcement is now disabled by default. You must enable it before running policy
tasks.
Prerequisites
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc.
Procedure
2. Run this command to check the current Mixer policy enforcement status:
4. Locate disablePolicyChecks: true within the ConfigMap and change the value to false.
Next steps
Prerequisites
When using Elasticsearch storage, by default a job is created to clean old traces from it. To configure
the options for this job, you edit the Jaeger custom resource (CR), to customize it for your use case. The
relevant options are listed below.
apiVersion: jaegertracing.io/v1
kind: Jaeger
56
CHAPTER 4. DAY TWO
spec:
strategy: production
storage:
type: elasticsearch
esIndexCleaner:
enabled: false
numberOfDays: 7
schedule: "55 23 * * *"
WARNING
The Bookinfo example application allows you to test your Red Hat OpenShift
Service Mesh 1.0.9 installation on OpenShift Container Platform.
Red Hat does not provide support for the Bookinfo application.
The productpage microservice calls the details and reviews microservices to populate the
page.
The reviews microservice contains book reviews. It also calls the ratings microservice.
The ratings microservice contains book ranking information that accompanies a book review.
57
OpenShift Container Platform 4.3 Service Mesh
Version v2 calls the ratings Service and displays each rating as one to five black stars.
Version v3 calls the ratings Service and displays each rating as one to five red stars.
Prerequisites:
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc.
NOTE
Red Hat OpenShift Service Mesh implements auto-injection differently than the
upstream Istio project, therefore this procedure uses a version of the bookinfo.yaml file
annotated to enable automatic injection of the Istio sidecar for Red Hat OpenShift
Service Mesh.
Procedure
1. Log in to the OpenShift Container Platform web console as a user with cluster-admin rights.
4. Enter bookinfo as the Project Name, enter a Display Name, and enter a Description, then click
Create.
Alternatively, you can run this command from the CLI to create the bookinfo project.
$ oc new-project bookinfo
6. Click the Project menu and use the control plane namespace. In this example, use istio-system.
a. If you have already created a Istio Service Mesh Member Roll, click the name, then click the
YAML tab to open the YAML editor.
b. If you have not created a Istio Service Mesh Member Roll, click Create Service Mesh
Member Roll.
NOTE
58
CHAPTER 4. DAY TWO
NOTE
You need cluster-admin rights to edit the Istio Service Mesh Member Roll.
9. Edit the default Service Mesh Member Roll YAML and add bookinfo to the members list.
apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
name: default
spec:
members:
- bookinfo
Alternatively, you can run this command from the CLI to add the bookinfo project to the
ServiceMeshMemberRoll. Replace <control plane project> with the name of your control
plane project.
$ oc -n <control plane project> patch --type='json' smmr default -p '[{"op": "add", "path":
"/spec/members", "value":["'"bookinfo"'"]}]'
10. Click Create to save the updated Service Mesh Member Roll.
11. From the CLI, deploy the Bookinfo application in the `bookinfo` project by applying the
bookinfo.yaml file:
NOTE
Procedure
59
OpenShift Container Platform 4.3 Service Mesh
Prerequisites
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc.
Procedure
You can also verify that all pods are ready with this command:
Prerequisites
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc.
Procedure
60
CHAPTER 4. DAY TWO
4. Type bookinfo in the confirmation dialog box, and then click Delete.
Alternatively, you can run this command from the CLI to create the bookinfo project.
4.3.5.2. Remove the Bookinfo project from the Service Mesh member roll
Procedure
3. Click the Project menu and choose openshift-operators from the list.
4. Click the Istio Service Mesh Member Rolllink under Provided APIS for the Red Hat
OpenShift Service Mesh Operator.
5. Click the ServiceMeshMemberRoll menu and select Edit Service Mesh Member Roll.
6. Edit the default Service Mesh Member Roll YAML and remove bookinfo from the members list.
Alternatively, you can run this command from the CLI to remove the bookinfo project from
the ServiceMeshMemberRoll. Replace <control plane project> with the name of your
control plane project.
This tutorial uses Service Mesh and the Bookinfo tutorial to demonstrate how you can use the Kiali
console to view the topography and health of your service mesh.
NOTE
61
OpenShift Container Platform 4.3 Service Mesh
NOTE
The Bookinfo example application allows you to test your Red Hat OpenShift Service
Mesh 1.0.9 installation on OpenShift Container Platform.
Red Hat does not provide support for the Bookinfo application.
Prerequisites
1. In the OpenShift Container Platform console, navigate to Networking → Routes and search for
the Kiali route.
3. Use the left navigation or click one of the Namespace icons to view your Applications,
Workloads, or Services.
62
CHAPTER 4. DAY TWO
1. Run this command from the CLI to obtain the route and Kiali URL:
$ oc get routes
2. Launch a browser and navigate to https://<KIALI_URL> (in the CLI output example, this is kiali-
openshift-operators.127.0.0.1.nip.io). You should see the Kiali console login screen.
3. Log in to the Kiali console using the user name and password that you use when logging in to the
OpenShift Container Platform console.
Procedure
63
OpenShift Container Platform 4.3 Service Mesh
2. If necessary, select bookinfo from the Namespace menu. The graph displays the applications in
the Bookinfo application.
3. Click the question mark (?) under the Namespace menu to take the Graph Help Tour.
5. Click Legend in the lower left corner. Kiali displays the graph legend.
7. Hover over the productpage Node. Note how the graph highlights only the incoming and
outgoing traffic from the Node.
8. Click the productpage Node. Note how the details on the right side of the page change to
display the productpage details.
Procedure
2. If necessary, select bookinfo from the Namespace menu. The page displays the applications in
the selected Namespace and their health.
4. Click the reviews Service to view the details for that application.
5. On the Applications Details page you can view more detailed health information, and drill down
for further details about the three versions of the reviews Service.
6. From the Application Details page you can also click tabs to view Traffic and Inbound and
64
CHAPTER 4. DAY TWO
6. From the Application Details page you can also click tabs to view Traffic and Inbound and
Outbound Metrics for the application.
Procedure
2. If necessary, select bookinfo from the Namespace menu. The page displays the Workloads in
the selected Namespace, their health, and labels.
3. Click the reviews-v1 Workload to view the details for that Workload.
4. On the Workload Details page you can view an overview of Pods and Services associated with
the Workload.
5. From the Workload Details page you can also click tabs to view Traffic, Logs, and Inbound and
Outbound Metrics for the Workload.
Procedure
2. If necessary, select bookinfo from the Namespace menu. The page displays a listing of all the
Services that are running in the selected Namespace and additional information about them,
such as health status.
3. Hover over the health icon for any of the Services to view health information about the Service.
A Service is considered healthy when it is online and responding to requests without errors.
4. Click the Reviews Service to view its details. Note that there are three different versions of this
Service.
65
OpenShift Container Platform 4.3 Service Mesh
5. On the Services Details page you can view an overview of Workloads, virtual Services, and
destination rules associated with the Service.
6. From the Services Details page you can also click tabs to view Traffic, Inbound Metrics, and
Traces for the Service.
7. Click the Actions menu. From here you can perform the following actions:
Suspend Traffic
8. Click the name of one of the Services to view additional details about that specific version of
the Service.
Procedure
2. If necessary, select bookinfo from the Namespace menu. The page displays a listing of
configurations running in the selected Namespace and validation status.
66
CHAPTER 4. DAY TWO
3. Click one of the configurations to view additional information about the configuration file.
This tutorial uses Service Mesh and the bookinfo tutorial to demonstrate how you can use Jeager to
perform distributed tracing.
NOTE
The Bookinfo example application allows you to test your Red Hat OpenShift Service
Mesh 1.0.9 installation on OpenShift Container Platform.
Red Hat does not provide support for the Bookinfo application.
Prerequisites:
67
OpenShift Container Platform 4.3 Service Mesh
Prerequisites:
Procedure
1. After you have deployed the Bookinfo application you will need to generate calls to the Bookinfo
application so that you have some trace data to analyze. Access
http://<GATEWAY_URL>/productpage and refresh the page a few times to generate some
trace data.
4. If necessary, log in using the same user name and password as you use to access the OpenShift
Container Platform console.
5. In the left pane of the Jaeger dashboard, from the Service menu, select "productpage" and click
the Find Traces button at the bottom of the pane. A list of traces is displayed, as shown in the
following image:
6. Click one of the traces in the list to open a detailed view of that trace. If you click on the top
(most recent) trace, you see the details that correspond to the latest refresh of the
`/productpage.
68
CHAPTER 4. DAY TWO
The trace in the previous figure consists of a few nested spans, each corresponding to a
Bookinfo Service call, all performed in response to a `/productpage request. Overall processing
time was 2.62s, with the details Service taking 3.56ms, the reviews Service taking 2.6s, and the
ratings Service taking 5.32ms. Each of the calls to remote Services is represented by a client-
side and server-side span. For example, the details client-side span is labeled productpage
details.myproject.svc.cluster.local:9080. The span nested underneath it, labeled details
details.myproject.svc.cluster.local:9080, corresponds to the server-side processing of the
request. The trace also shows calls to istio-policy, which reflect authorization checks made by
Istio.
69
OpenShift Container Platform 4.3 Service Mesh
5.1.1. Integrate the 3scale adapter with Red Hat OpenShift Service Mesh
You can use these examples to configure requests to your services using the 3scale Istio Adapter.
Prerequisites:
Ensure Mixer policy enforcement is enabled. Update Mixer policy enforcement section provides
instructions to check the current Mixer policy enforcement status and enable policy
enforcement.
NOTE
To configure the 3scale Istio Adapter, refer to Red Hat OpenShift Service Mesh custom
resources for instructions on adding adapter parameters to the custom resource file.
NOTE
Pay particular attention to the kind: handler resource. You must update this with your
3scale credentials and the service ID of the API you want to manage.
apiVersion: "config.istio.io/v1alpha2"
kind: handler
metadata:
name: threescale
spec:
adapter: threescale
params:
service_id: "<SERVICE_ID>"
system_url: "https://<organization>-admin.3scale.net/"
access_token: "<ACCESS_TOKEN>"
connection:
address: "threescale-istio-adapter:3333"
Optionally, you can provide a backend_url field within the params section to override the URL provided
70
CHAPTER 5. 3SCALE ADAPTER
Optionally, you can provide a backend_url field within the params section to override the URL provided
by the 3scale configuration. This may be useful if the adapter runs on the same cluster as the 3scale on-
premise instance, and you wish to leverage the internal cluster DNS.
1. Modify the rule configuration with your 3scale configuration to dispatch the rule to the
threescale handler.
apiVersion: "config.istio.io/v1alpha2"
kind: rule
metadata:
name: threescale
spec:
match: destination.labels["service-mesh.3scale.net"] == "true"
actions:
- handler: threescale.handler
instances:
- threescale-authorization.instance
The adapter includes a tool that allows you to generate the handler, instance, and rule custom
resources.
71
OpenShift Container Platform 4.3 Service Mesh
This example generates templates allowing the token, URL pair to be shared by multiple services
as a single handler:
This example generates the templates with the service ID embedded in the handler:
1. Run this command to generate manifests from a deployed adapter in the istio-system
namespace:
2. This will produce sample output to the terminal. Edit these samples if required and create the
objects using the oc create command.
3. When the request reaches the adapter, the adapter needs to know how the service maps to an
API on 3scale. You can provide this information in two ways:
NOTE
72
CHAPTER 5. 3SCALE ADAPTER
NOTE
You only need to update the service ID provided in this example if it is not already
embedded in the handler. The setting in the handler takes precedence.
$ export CREDENTIALS_NAME="replace-me"
export SERVICE_ID="replace-me"
export DEPLOYMENT="replace-me"
patch="$(oc get deployment "${DEPLOYMENT}"
patch="$(oc get deployment "${DEPLOYMENT}" --template='{"spec":{"template":{"metadata":
{"labels":{ {{ range $k,$v := .spec.template.metadata.labels }}"{{ $k }}":"{{ $v }}",{{ end
}}"service-mesh.3scale.net/service-id":"'"${SERVICE_ID}"'","service-
mesh.3scale.net/credentials":"'"${CREDENTIALS_NAME}"'"}}}}}' )"
oc patch deployment "${DEPLOYMENT}" --patch ''"${patch}"''
Follow these steps to drive traffic for your service through the 3scale adapter.
Prerequisites
Procedure
2. Add the above label to PodTemplateSpec on the Deployment of the target workload to
integrate a service. the value, threescale, refers to the name of the generated handler. This
handler stores the access token required to call 3scale.
NOTE
For 3scale SaaS customers, Red Hat OpenShift Service Mesh is enabled as part of the
Early Access program.
Procedure
2. At the top of the Integration page click on edit integration settings in the top right corner.
73
OpenShift Container Platform 4.3 Service Mesh
By using the refreshing process, cached values whose hosts become unreachable will be retried before
eventually being purged when past their expiry.
Standard API Keys: single randomized strings or hashes acting as an identifier and a secret
token.
Application identifier and key pairs: immutable identifier and mutable secret key strings.
OpenID authentication method: client ID string parsed from the JSON Web Token.
Modify the instance custom resource, as illustrated in the following authentication method examples, to
configure authentication behavior. You can accept the authentication credentials from:
Request headers
Request parameters
NOTE
When specifying values from headers, they must be lower case. For example, if you want
to send a header as User-Key, this must be referenced in the configuration as
request.headers["user-key"].
Service Mesh looks for the API key in query parameters and request headers as specified in the user
option in the subject custom resource parameter. It checks the values in the order given in the custom
resource file. You can restrict the search for the API key to either query parameters or request headers
by omitting the unwanted option.
In this example, Service Mesh looks for the API key in the user_key query parameter. If the API key is
not in the query parameter, Service Mesh then checks the user-key header.
apiVersion: "config.istio.io/v1alpha2"
kind: instance
74
CHAPTER 5. 3SCALE ADAPTER
metadata:
name: threescale-authorization
namespace: istio-system
spec:
template: authorization
params:
subject:
user: request.query_params["user_key"] | request.headers["user-key"] | ""
action:
path: request.url_path
method: request.method | "get"
If you want the adapter to examine a different query parameter or request header, change the name as
appropriate. For example, to check for the API key in a query parameter named “key”, change
request.query_params["user_key"] to request.query_params["key"].
Service Mesh looks for the application ID and application key in query parameters and request headers,
as specified in the properties option in the subject custom resource parameter. The application key is
optional. It checks the values in the order given in the custom resource file. You can restrict the search
for the credentials to either query parameters or request headers by not including the unwanted option.
In this example, Service Mesh looks for the application ID and application key in the query parameters
first, moving on to the request headers if needed.
apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
name: threescale-authorization
namespace: istio-system
spec:
template: authorization
params:
subject:
app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
action:
path: request.url_path
method: request.method | "get"
If you want the adapter to examine a different query parameter or request header, change the name as
appropriate. For example, to check for the application ID in a query parameter named identification,
change request.query_params["app_id"] to request.query_params["identification"].
To use the OpenID Connect (OIDC) authentication method , use the properties value on the subject
field to set client_id, and optionally app_key.
You can manipulate this object using the methods described previously. In the example configuration
shown below, the client identifier (application ID) is parsed from the JSON Web Token (JWT) under the
label azp. You can modify this as needed.
75
OpenShift Container Platform 4.3 Service Mesh
apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
name: threescale-authorization
spec:
template: threescale-authorization
params:
Subject:
properties:
app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
client_id: request.auth.claims["azp"] | ""
action:
path: request.url_path
method: request.method | "get"
service: destination.labels["service-mesh.3scale.net/service-id"] | ""
For this integration to work correctly, OIDC must still be done in 3scale for the client to be created in the
identity provider (IdP). You should create end-user authentication for the service you want to protect in
the same namespace as that service. The JWT is passed in the Authorization header of the request.
In the sample Policy defined below, replace issuer and jwksUri as appropriate.
apiVersion: authentication.istio.io/v1alpha1
kind: Policy
metadata:
name: jwt-example
namespace: bookinfo
spec:
origins:
- jwt:
issuer: >-
http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak
jwksUri: >-
http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-
connect/certs
principalBinding: USE_ORIGIN
targets:
- name: productpage
You can choose to not enforce a particular authentication method and accept any valid credentials for
either method. If both an API key and an application ID/application key pair are provided, Service Mesh
uses the API key.
In this example, Service Mesh checks for an API key in the query parameters, then the request headers. If
there is no API key, it then checks for an application ID and key in the query parameters, then the request
headers.
76
CHAPTER 5. 3SCALE ADAPTER
apiVersion: "config.istio.io/v1alpha2"
kind: instance
metadata:
name: threescale-authorization
spec:
template: authorization
params:
subject:
user: request.query_params["user_key"] | request.headers["user-key"] |
properties:
app_id: request.query_params["app_id"] | request.headers["app-id"] | ""
app_key: request.query_params["app_key"] | request.headers["app-key"] | ""
client_id: request.auth.claims["azp"] | ""
action:
path: request.url_path
method: request.method | "get"
service: destination.labels["service-mesh.3scale.net/service-id"] | ""
77