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

The installation instructions for Maistra have changed significantly since Maistra 0.9. The instructions for Maistra 0.9 are here.

Supported Configurations

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.0

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

admissionConfig:
  pluginConfig:
    MutatingAdmissionWebhook:
      configuration:
        apiVersion: apiserver.config.k8s.io/v1alpha1
        kubeConfigFile: /dev/null
        kind: WebhookAdmission
    ValidatingAdmissionWebhook:
      configuration:
        apiVersion: apiserver.config.k8s.io/v1alpha1
        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 new-project istio-system
oc apply -n istio-operator -f https://raw.githubusercontent.com/Maistra/istio-operator/maistra-0.10/deploy/maistra-operator.yaml

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

The installation yaml has changed significantly in Maistra 0.10. See here for older examples.

In order to deploy the Istio Control Plane we need to create a custom resource such as the one in the following example which demonstrates the configuration options supported by the operator. The 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.

apiVersion: istio.openshift.com/v1alpha3
kind: ControlPlane
metadata:
  name: basic-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
        ior_enabled: false

    mixer:
      policy:
        autoscaleEnabled: false

      telemetry:
        autoscaleEnabled: false
        resources:
          requests:
            cpu: 100m
            memory: 1G
          limits:
            cpu: 500m
            memory: 4G

    pilot:
      autoscaleEnabled: false
      traceSampling: 100.0

    kiali:
     dashboard:
        user: admin
        passphrase: admin

Once you have modified the custom resource to suit your installation you can deploy the resource using the following command

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

Verifying the Istio Control Plane

The update and release of Maistra 0.9 introduced a significant change in behaviour related to policy enforcement via Mixer. In older versions of the product, Mixer’s policy enforcement was enabled by default. However, from release 0.9 onward, the policy enforcement is now disabled. Instructions to enable it are here

Execute the following command to see the status of the installation. In the example below, we assume that the controlplane is named basic-install. If the name is different, replace basic-install with the proper value.

oc get controlplane/basic-install -n istio-system --template='{{range .status.conditions}}{{printf "%s=%s, reason=%s, message=%s\n\n" .type .status .reason .message}}{{end}}'

When installation is complete, the output should be similar to the following:

Installed=True, reason=InstallSuccessful, message=%!s(<nil>)

Executing oc get pods -n istio-system should yield output similar to the following:

NAME                                          READY     STATUS      RESTARTS   AGE
3scale-istio-adapter-7df4db48cf-sc98s         1/1       Running     0          13s
elasticsearch-0                               1/1       Running     0          29s
grafana-c7f5cc6b6-vg6db                       1/1       Running     0          33s
istio-citadel-d6d6bb7bb-jgfwt                 1/1       Running     0          1m
istio-egressgateway-69448cf7dc-b2qj5          1/1       Running     0          1m
istio-galley-f49696978-q949d                  1/1       Running     0          1m
istio-ingressgateway-7759647fb6-pfpd5         1/1       Running     0          1m
istio-pilot-7595bfd696-plffk                  2/2       Running     0          1m
istio-policy-779454b878-xg7nq                 2/2       Running     2          1m
istio-sidecar-injector-6655b6ffdb-rn69r       1/1       Running     0          1m
istio-telemetry-dd9595888-8xjz2               2/2       Running     2          1m
jaeger-agent-gmk72                            1/1       Running     0          25s
jaeger-collector-7f644df9f5-dbzcv             1/1       Running     1          25s
jaeger-query-6f47bf4777-h4wmh                 1/1       Running     1          25s
kiali-7cc48b6cbb-74gcf                        1/1       Running     0          17s
prometheus-5f9fd67f8-r6b86                    1/1       Running     0          1m

If you have also chosen to install the Fabric8 launcher you should monitor the containers within the devex project until the following state has been reached:

NAME                          READY     STATUS    RESTARTS   AGE
configmapcontroller-1-8rr6w   1/1       Running   0          1m
launcher-backend-2-2wg86      1/1       Running   0          1m
launcher-frontend-2-jxjsd     1/1       Running   0          1m

Uninstalling Maistra

Removing the Control Plane

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, do:

oc get controlplanes -n istio-system

This resource can now be deleted as follows:

oc delete -n istio-system -f <name_of_cr>

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 https://raw.githubusercontent.com/Maistra/istio-operator/maistra-0.10/deploy/maistra-operator.yaml

The istio-operator and istio-system projects can now be removed.

oc delete project istio-system
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 project istio-system
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