$ oc login https://{HOSTNAME}:6443
Installing the Service Mesh involves installing the Elasticsearch, Jaeger, Kiali and Service Mesh Operators, creating and managing a ServiceMeshControlPlane
resource to deploy the control plane, and creating a ServiceMeshMemberRoll
resource to specify the namespaces associated with the Service Mesh.
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. |
Multi-tenant control plane installations are the default configuration starting with Red Hat OpenShift Service Mesh 1.0. |
The Service Mesh documentation uses |
Follow the Preparing to install Red Hat OpenShift Service Mesh process.
An account with the cluster-admin
role.
The Service Mesh installation process uses the OperatorHub to install the ServiceMeshControlPlane
custom resource definition within the openshift-operators
project. The Red Hat OpenShift Service Mesh defines and monitors the ServiceMeshControlPlane
related to the deployment, update, and deletion of the control plane.
Starting with Red Hat OpenShift Service Mesh 1.1.10, 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.
The default Jaeger deployment uses in-memory storage because it is designed to be installed quickly for those evaluating Jaeger, giving demonstrations, or using Jaeger in a test environment. If you plan to use Jaeger in production, you must install a persistent storage option, in this case, Elasticsearch.
Access to the OpenShift Container Platform web console.
An account with the cluster-admin
role.
Do not install Community versions of the Operators. Community Operators are not supported. |
If you have already installed the Elasticsearch Operator as part of OpenShift cluster logging, you do not need to install the Elasticsearch Operator again. The Jaeger Operator will create the Elasticsearch instance using the installed Elasticsearch Operator. |
Log in to the OpenShift Container Platform web console as a user with the cluster-admin
role.
Navigate to Operators → OperatorHub.
Type Elasticsearch into the filter box to locate the Elasticsearch Operator.
Click the Elasticsearch Operator provided by Red Hat to display information about the Operator.
Click Install.
On the Create Operator Subscription page, select the A specific namespace on the cluster option and then select openshift-operators-redhat from the menu.
Select the Update Channel that matches your OpenShift Container Platform installation. For example, if you are installing on OpenShift Container Platform version 4.5, select the 4.5 update channel.
Select the Automatic Approval Strategy.
The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. |
Click Subscribe.
On the Installed Operators page, select the openshift-operators-redhat
project. Wait until you see that the Elasticsearch Operator shows a status of "InstallSucceeded" before continuing.
To install Jaeger you use the OperatorHub to install the Jaeger Operator.
By default the Operator is installed in the openshift-operators
project.
Access to the OpenShift Container Platform web console.
An account with the cluster-admin
role.
If you require persistent storage, you must also install the Elasticsearch Operator before installing the Jaeger Operator.
Do not install Community versions of the Operators. Community Operators are not supported. |
Log in to the OpenShift Container Platform web console as a user with the cluster-admin
role.
Navigate to Operators → OperatorHub.
Type Jaeger into the filter to locate the Jaeger Operator.
Click the Jaeger Operator provided by Red Hat to display information about the Operator.
Click Install.
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.
Select the stable Update Channel. This will automatically update Jaeger as new versions are released. If you select a maintenance channel, for example, 1.17-stable, you will receive bug fixes and security patches for the length of the support cycle for that version.
Select an Approval Strategy. You can select Automatic or Manual updates. If you choose Automatic updates for an installed Operator, when a new version of that Operator is available, the Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention. If you select Manual updates, when a newer version of an Operator is available, the OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version.
The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. |
Click Subscribe.
On the Subscription Overview page, select the openshift-operators
project. Wait until you see that the Jaeger Operator shows a status of "InstallSucceeded" before continuing.
You must install the Kiali Operator for the Red Hat OpenShift Service Mesh Operator to install the control plane.
Do not install Community versions of the Operators. Community Operators are not supported. |
Access to the OpenShift Container Platform web console.
Log in to the OpenShift Container Platform web console.
Navigate to Operators → OperatorHub.
Type Kiali into the filter box to find the Kiali Operator.
Click the Kiali Operator provided by Red Hat to display information about the Operator.
Click Install.
On the Install Operator 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.
Select the stable Update Channel.
Select the Automatic Approval Strategy.
The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. |
Click Install.
The Installed Operators page displays the Kiali Operator’s installation progress.
Access to the OpenShift Container Platform web console.
The Elasticsearch Operator must be installed.
The Jaeger Operator must be installed.
The Kiali Operator must be installed.
Log in to the OpenShift Container Platform web console.
Navigate to Operators → OperatorHub.
Type Red Hat OpenShift Service Mesh into the filter box to find the Red Hat OpenShift Service Mesh Operator.
Click the Red Hat OpenShift Service Mesh Operator to display information about the Operator.
On the Install Operator 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.
Click Install.
Select the stable Update Channel.
Select the Automatic Approval Strategy.
The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. |
Click Install.
The Installed Operators page displays the Red Hat OpenShift Service Mesh Operator’s installation progress.
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.
The Red Hat OpenShift Service Mesh Operator must be installed.
Review the instructions for how to customize the Red Hat OpenShift Service Mesh installation.
An account with the cluster-admin
role.
Log in to the OpenShift Container Platform web console as a user with the cluster-admin
role.
Create a project named istio-system
.
Navigate to Home → Projects.
Click Create Project.
Enter istio-system
in the Name field.
Click Create.
Navigate to Operators → Installed Operators.
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.
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
Under Istio Service Mesh Control Plane click Create ServiceMeshControlPlane.
On the Create Service Mesh Control Plane page, modify the YAML for the default ServiceMeshControlPlane
template as needed.
For additional information about customizing the control plane, see customizing the Red Hat OpenShift Service Mesh installation. For production, you must change the default Jaeger template. |
Click Create to create the control plane. The Operator creates Pods, services, and Service Mesh control plane components based on your configuration parameters.
Click the Istio Service Mesh Control Plane tab.
Click the name of the new control plane.
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.
The Red Hat OpenShift Service Mesh Operator must be installed.
Review the instructions for how to customize the Red Hat OpenShift Service Mesh installation.
An account with the cluster-admin
role.
Access to the OpenShift CLI (oc
).
Log in to the OpenShift Container Platform CLI as a user with the cluster-admin
role.
$ oc login https://{HOSTNAME}:6443
Create a project named istio-system
.
$ oc new-project istio-system
Create a ServiceMeshControlPlane
file named istio-installation.yaml
using the example found in "Customize the Red Hat OpenShift Service Mesh installation". You can customize the values as needed to match your use case. For production deployments you must change the default Jaeger template.
Run the following command to deploy the control plane:
$ oc create -n istio-system -f istio-installation.yaml
Execute the following command to see the status of the control plane installation.
$ oc get smcp -n istio-system
The installation has finished successfully when the READY column is true.
NAME READY basic-install True
Run the following command to watch the progress of the Pods during the installation process:
$ oc get pods -n istio-system -w
You should see output similar to the following:
NAME READY STATUS RESTARTS AGE
grafana-7bf5764d9d-2b2f6 2/2 Running 0 28h
istio-citadel-576b9c5bbd-z84z4 1/1 Running 0 28h
istio-egressgateway-5476bc4656-r4zdv 1/1 Running 0 28h
istio-galley-7d57b47bb7-lqdxv 1/1 Running 0 28h
istio-ingressgateway-dbb8f7f46-ct6n5 1/1 Running 0 28h
istio-pilot-546bf69578-ccg5x 2/2 Running 0 28h
istio-policy-77fd498655-7pvjw 2/2 Running 0 28h
istio-sidecar-injector-df45bd899-ctxdt 1/1 Running 0 28h
istio-telemetry-66f697d6d5-cj28l 2/2 Running 0 28h
jaeger-896945cbc-7lqrr 2/2 Running 0 11h
kiali-78d9c5b87c-snjzh 1/1 Running 0 22h
prometheus-6dff867c97-gr2n5 2/2 Running 0 28h
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.
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
.
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.
An installed, verified Red Hat OpenShift Service Mesh Operator.
Location of the installed ServiceMeshControlPlane
.
List of existing projects to add to the service mesh.
If you don’t already have projects for your mesh, or you are starting from scratch, create a project. It must be different from istio-system
.
Navigate to Home → Projects.
Enter a name in the Name field.
Click Create.
Log in to the OpenShift Container Platform web console.
Navigate to Operators → Installed Operators.
Click the Project menu and choose the project where your ServiceMeshControlPlane
is deployed from the list, for example istio-system
.
Click the Red Hat OpenShift Service Mesh Operator.
Click the All Instances tab.
Click Create New, and then select Create Istio Service Mesh Member Roll.
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. |
On the Create Service Mesh Member Roll page, 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.
Click Create to save the Service Mesh Member Roll.
Follow this procedure to add a project to the ServiceMeshMemberRoll
from the command line.
An installed, verified Red Hat OpenShift Service Mesh Operator.
Location of the installed ServiceMeshControlPlane
.
List of projects to add to the service mesh.
Access to the OpenShift CLI (oc
).
Log in to the OpenShift Container Platform CLI.
$ oc login
Create a ServiceMeshMemberRoll
resource in the same project as the ServiceMeshControlPlane
resource, in our example that is istio-system
. The resource must be named default
.
$ oc create -n istio-system -f 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
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.
ServiceMeshMember
resources can be created by service mesh users who don’t have privileges to add members to the ServiceMeshMemberRoll
directly. While project administrators are automatically given permission to create the ServiceMeshMember
resource in their project, they cannot point it to any ServiceMeshControlPlane
until the service mesh administrator explicitly grants access to the service mesh. Administrators can grant users permissions to access the mesh by granting them the mesh-user
user role, for example:
$ oc policy add-role-to-user -n <control-plane-namespace> --role-namespace <control-plane-namespace> mesh-user <user-name>.
Administrators can modify the mesh user
role binding in the control plane project to specify the users and groups that are granted access. The ServiceMeshMember
adds the project to the ServiceMeshMemberRoll
within the control plane project it references.
apiVersion: maistra.io/v1 kind: ServiceMeshMember metadata: name: default spec: controlPlaneRef: namespace: control-plane-namespace name: minimal-install
The mesh-users role binding is created automatically after the administrator creates the ServiceMeshControlPlane
resource. An administrator can use the following command to add a role to a user.
$ oc policy add-role-to-user
The administrator can also create the mesh-user
role binding before the administrator creates the ServiceMeshControlPlane
resource. For example, the administrator can create it in the same oc apply
operation as the ServiceMeshControlPlane
resource.
This example adds a role binding for alice
:
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: namespace: control-plane-namespace name: mesh-users roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: mesh-user subjects: - apiGroup: rbac.authorization.k8s.io kind: User name: alice
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.
The ServiceMeshMemberRoll
resource is deleted when its corresponding ServiceMeshControlPlane
resource is deleted.
An installed, verified Red Hat OpenShift Service Mesh Operator.
An existing ServiceMeshMemberRoll
resource.
Name of the project with the ServiceMeshMemberRoll
resource.
Names of the projects you want to add or remove from the mesh.
Log in to the OpenShift Container Platform web console.
Navigate to Operators → Installed Operators.
Click the Project menu and choose the project where your ServiceMeshControlPlane
is deployed from the list, for example istio-system
.
Click the Red Hat OpenShift Service Mesh Operator.
Click the Istio Service Mesh Member Roll tab.
Click the default
link.
Click the YAML tab.
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.
Click Save.
Click Reload.
Follow this procedure to modify an existing Service Mesh member roll using the command line.
An installed, verified Red Hat OpenShift Service Mesh Operator.
An existing ServiceMeshMemberRoll
resource.
Name of the project with the ServiceMeshMemberRoll
resource.
Names of the projects you want to add or remove from the mesh.
Access to the OpenShift CLI (oc
).
Log in to the OpenShift Container Platform CLI.
Edit the ServiceMeshMemberRoll
resource.
$ oc edit smmr -n <controlplane-namespace>
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.
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
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.
If you selected the Automatic Approval Strategy when you were installing your Operators, then the Operators update the control plane automatically, but not your applications. Existing applications continue to be part of the mesh and function accordingly. The application administrator must restart applications to upgrade the sidecar.
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:
$ oc patch deployment/<deployment> -p '{"spec":{"template":{"metadata":{"annotations":{"kubectl.kubernetes.io/restartedAt": "'`date -Iseconds`'"}}}}}'
If your deployment does not use automatic sidecar injection, you must manually update the sidecars by modifying the sidecar container image specified in the deployment or pod.
This process allows you to remove Red Hat OpenShift Service Mesh from an existing OpenShift Container Platform instance. Remove the control plane before removing the operators.
The ServiceMeshMemberRoll
resource is automatically deleted when you delete the ServiceMeshControlPlane
resource it is associated with.
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.
The Red Hat OpenShift Service Mesh control plane must be deployed.
Log in to the OpenShift Container Platform web console.
Click the Project menu and choose the istio-system
project from the list.
Navigate to Operators → Installed Operators.
Click on Service Mesh Control Plane under Provided APIs.
Click the ServiceMeshControlPlane
menu .
Click Delete Service Mesh Control Plane.
Click Delete on the confirmation dialog window to remove the ServiceMeshControlPlane
.
Follow this procedure to remove the Red Hat OpenShift Service Mesh control plane by using the CLI.
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 |
You can use the shortened |
Log in to the OpenShift Container Platform CLI.
Run this command to retrieve the name of the installed ServiceMeshControlPlane
:
$ oc get servicemeshcontrolplanes -n istio-system
Replace <name_of_custom_resource>
with the output from the previous command, and run this command to remove the custom resource:
$ oc delete servicemeshcontrolplanes -n istio-system <name_of_custom_resource>
You must remove the Operators to successfully remove Red Hat OpenShift Service Mesh. Once you remove the Red Hat OpenShift Service Mesh Operator, you must remove the Jaeger Operator, Kiali Operator, and the Elasticsearch Operator.
Follow this procedure to remove the Red Hat OpenShift Service Mesh Operator.
Access to the OpenShift Container Platform web console.
The Red Hat OpenShift Service Mesh Operator must be installed.
Log in to the OpenShift Container Platform web console.
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.
On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
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 remove the Jaeger Operator.
Access to the OpenShift Container Platform web console.
The Jaeger Operator must be installed.
Log in to the OpenShift Container Platform web console.
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.
On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
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 remove the Kiali Operator.
Access to the OpenShift Container Platform web console.
The Kiali Operator must be installed.
Log in to the OpenShift Container Platform web console.
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.
On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
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 remove the Elasticsearch Operator.
Access to the OpenShift Container Platform web console.
The Elasticsearch Operator must be installed.
Log in to the OpenShift Container Platform web console.
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.
On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
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.
An account with cluster administration access.
Access to the OpenShift Container Platform Command-line Interface (CLI) also known as oc
.
Log in to the OpenShift Container Platform CLI as a cluster administrator.
Run the following commands to clean up resources after uninstalling the Operators:
Replace |
$ oc delete validatingwebhookconfiguration/<operator-project>.servicemesh-resources.maistra.io
$ oc delete mutatingwebhookconfigurations/<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
$ oc get crds -o name | grep '.*\.kiali\.io' | xargs -r -n 1 oc delete
Prepare to deploy applications on Red Hat OpenShift Service Mesh.