Installing on OKD/OCP

Istio Installation Guide

This guide provides instructions for installing Maistra into an existing OpenShift Container Platform (OCP) or Origin (OKD) cluster and for creating a standalone, all-in-one origin cluster with Istio

Supported Configurations

To use this on an OCP 3.11 cluster, the Red Hat registry must be configured.

Preparing the Installation

Before Istio can be installed into an existing installation it is necessary to make a number of changes to the master configuration and each of the schedulable nodes. These changes will enable features required within Istio and also ensure Elasticsearch will function correctly.

The master/node updates discussed below are no longer necessary in OCP/OKD 4.1

Updating the Master

If manual sidecar injection (i.e. kube-inject) is used this section may be skipped.

To enable the automatic injection of the Istio sidecar we first need to modify the master configuration on each master to include support for webhooks and signing of Certificate Signing Requests (CSRs). Then each individual Deployment requiring automatic injection needs to be modified.

First, make the following changes on each master within your installation.

  • Change to the directory containing the master configuration file (e.g. /etc/origin/master/master-config.yaml)

  • Create a file named master-config.patch with the following contents

        kubeConfigFile: /dev/null
        kind: WebhookAdmission
        kubeConfigFile: /dev/null
        kind: WebhookAdmission
  • Within the same directory issue the following commands:

cp -p master-config.yaml master-config.yaml.prepatch
oc ex config patch master-config.yaml.prepatch -p "$(cat master-config.patch)" > master-config.yaml
master-restart api
master-restart controllers

Updating the Nodes

In order to run the Elasticsearch application it is necessary to make a change to the kernel configuration on each node, this change will be handled through the sysctl service.

Make the following changes on each node within your installation

  • Create a file named /etc/sysctl.d/99-elasticsearch.conf with the following contents: vm.max_map_count = 262144

  • Execute the following command:

sysctl vm.max_map_count=262144

Installing Maistra

Installing the Istio Operator

The Maistra installation process introduces a Kubernetes operator to manage the installation of the Istio control plane within the istio-system namespace. This operator defines and monitors a custom resource related to the deployment, update and deletion of the Istio control plane.

The following steps will install the Maistra operator into an existing installation, these can be executed from any host with access to the cluster. Please ensure you are logged in as a cluster admin before executing the following

oc new-project istio-operator
oc apply -n istio-operator -f

Verifying Installation

The above instructions will create a new deployment within the istio-operator project, executing the operator responsible for managing the state of the Istio control plane through the custom resource.

To verify the operator is installed correctly, wait for the operator to reach the running state

oc get pods -n istio-operator -l name=istio-operator

NAME                              READY     STATUS    RESTARTS   AGE
istio-operator-5cd6bcf645-fvb57   1/1       Running   0          1h

Deploying the Istio Control Plane

Maistra supports both multi-tenant installations and single-tenant installations. In a single-tenant installation, a single control plane is used for the entire cluster. In a multi-tenant installation, multiple control planes can be deployed in a cluster, with each control plane allowing access to only namespaces listed in a ServiceMeshMemberRoll resource belonging to that controlplane.

Multi-tenant control plane installations cannot be used in conjunction with a cluster-wide control plane installation, i.e. all installations must be mult-tenant or a single, cluster-wide installation must be used.

The proxy-init image must be changed to maistra/proxy-init-centos7 if running on a RHEL 7 host. More details can be found in the custom installation documentation

Maistra supports a shorthand of smcp for ServiceMeshControlPlane and smmr for ServiceMeshMemberRoll.

Single-Tenant Installation

In order to deploy the Istio Control Plane, we need to create a custom resource such as the one in the following example. This custom resource must be created in the istio-system namespace. For more information on the parameters and their configuration please see the custom installation documentation.

kind: ServiceMeshControlPlane
  name: basic-install
  # NOTE, if you remove all children from an element, you should remove the
  # element too.  An empty element is interpreted as null and will override all
  # default values (i.e. no values will be specified for that element, not even
  # the defaults baked into the chart values.yaml).
      multitenant: false
        # constrain resources for use in smaller environments
            cpu: 100m
            memory: 128Mi
            cpu: 500m
            memory: 128Mi

        # disable autoscaling for use in smaller environments
        autoscaleEnabled: false
        # disable autoscaling for use in smaller environments
        autoscaleEnabled: false
        # set to true to enable IOR
        ior_enabled: false

        # disable autoscaling for use in smaller environments
        autoscaleEnabled: false

        # disable autoscaling for use in smaller environments
        autoscaleEnabled: false
        # constrain resources for use in smaller environments
            cpu: 100m
            memory: 1G
            cpu: 500m
            memory: 4G

      # disable autoscaling for use in smaller environments
      autoscaleEnabled: false
      # increase random sampling rate for development/testing
      traceSampling: 100.0

      # change to false to disable kiali
      enabled: true

      # to use oauth, remove the following 'dashboard' section
      # create a secret for accessing kiali dashboard with the following credentials
        user: admin
        passphrase: admin

      # change to false to disable tracing (i.e. jaeger)
      enabled: true
    enabled: false

Once you have modified the custom resource to suit your installation you can deploy the resource using the following command, substituting istio-system if appropriate.

oc new-project istio-system
oc create -n istio-system -f <name of file>

Multi-Tenant Installation

To enable multitenancy, set the multitenant: false field in the control plane example to true, create a namespace to contain the control plane, and create the custom resource in that namespace.


The ServiceMeshMemberRoll resource configures which namespaces belong to a control plane. Only namespaces listed in the ServiceMeshMemberRoll will be affected by the control plane. Any number of namespaces can be added, but a namespace may not exist in more than one control plane. This resource must be created in the same namespace as the ServicemeshControlPlane resource and must be named default. An example resource can be seen below:

kind: ServiceMeshMemberRoll
  name: default
  # a list of namespaces that should be joined into the service mesh
  # for example, to add the bookinfo namespace
  - bookinfo

The control plane processes the ServiceMeshMemberRoll when: the ServiceMeshMemberRoll is created, updated, or deleted, the ServicemeshControlPlane in the same namespace is created or updated, or a namespace in the ServiceMeshMemberRoll is created or deleted.

Uninstalling Maistra

Removing the Control Plane

Subsitute the proper namespace below if the controlplane was created in a namespace other than istio-system.

The following steps will remove Istio from an existing installation. It can be executed by any user with access to delete the CustomResource.

To get the name of the installed custom resource, type:

oc get servicemeshcontrolplanes -n istio-system

This resource can now be deleted as follows:

oc delete smcp -n istio-system <name_of_cr>
oc delete project istio-system

The removal of the CustomResource will tell the Istio operator to begin uninstalling everything it installed.

Removing the Operator

In order to cleanly remove the operator execute the following:

oc delete -n istio-operator -f

The istio-operator project can now be removed.

oc delete project istio-operator

Upgrading from a Pre-Existing Installation

To upgrade Istio, please remove the custom resource and then create a new custom resource. The operator will upgrade appropriately.

To upgrade the operator, please first remove the operator and then reinstall it. Note that Istio must be removed before the operator.

If the operator was removed before the custom resource, you can uninstall the control plane manually. Using the instructions below

oc delete csr istio-sidecar-injector.istio-system
oc get crd  | grep istio | awk '{print $1}' | xargs oc delete crd
oc get mutatingwebhookconfigurations  | grep istio | awk '{print $1}' | xargs oc delete mutatingwebhookconfigurations
oc get validatingwebhookconfiguration  | grep istio | awk '{print $1}' | xargs oc delete validatingwebhookconfiguration
oc get clusterroles  | grep istio | awk '{print $1}' | xargs oc delete clusterroles
oc get clusterrolebindings  | grep istio | awk '{print $1}' | xargs oc delete clusterrolebindings