Installing a control plane

Creating a Maistra Control Plane

Maistra supports the deployment of multiple Istio control planes using ServiceMeshMemberRoll and ServiceMeshControlPlane resources. The ServiceMeshMemberRoll lists the projects belonging to the control plane while the ServiceMeshControlPlane lists the configuration to use during installation. ServiceMeshControlPlane can be shortened to smcp and ServiceMeshMemberRoll can be shortened to smmr.

ServiceMeshMemberRoll

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

apiVersion: maistra.io/v1
kind: ServiceMeshMemberRoll
metadata:
  name: default
spec:
  members:
  # a list of projects that should be joined into the service mesh
  # for example, to add the bookinfo project
  - bookinfo

ServiceMeshControlPlane

In order to deploy the Istio Control Plane, create a ServiceMeshControlPlane such as the one in the following example. The example below uses istio-system as the control plane project. For more information on the parameters and their configuration please see the custom installation documentation.

apiVersion: maistra.io/v1
kind: ServiceMeshControlPlane
metadata:
  name: minimal-install
spec:
  istio:
    global:
      proxy:
        # constrain resources for use in smaller environments
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 128Mi

    gateways:
      istio-egressgateway:
        # disable autoscaling for use in smaller environments
        autoscaleEnabled: false
      istio-ingressgateway:
        # disable autoscaling for use in smaller environments
        autoscaleEnabled: false

    mixer:
      policy:
        # disable autoscaling for use in smaller environments
        autoscaleEnabled: false

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

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

    kiali:
      # to disable kiali
      enabled: false

      # create a secret for accessing kiali dashboard with the following credentials
      # dashboard:
      #   user: admin
      #   passphrase: admin

    # disable grafana
    grafana:
      enabled: false

    # to disable tracing (i.e. jaeger)
    tracing:
      enabled: false
      jaeger:
        tag: 1.13.1
        # simple, all-in-one strategy
        template: all-in-one
        # production strategy, utilizing elasticsearch
        #template: production-elasticsearch
        # if required. only one instance may use agentStrategy=DaemonSet
        #agentStrategy: DaemonSet

Once you have modified the ServiceMeshControlPlane 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>

Deploying a Maistra Control Plane using Catalog Web UI

Openshift web console can be used to create control plane and member roll custom resources. Please reference documentation on creating applications from installed operators for more details.

To create a control plane, open the OpenShift web console in a Web browser and create a new project. This example uses a project called istio-system.

  • Navigate to CatalogsInstalled Operators.

  • Click Copied and click the Maistra operator to view more actions.

  • Under Provided APIs, you will see that the Operator creates two resource types:

    • An Istio Service Mesh Control Plane

    • An Istio Service Mesh Member Roll

  • In the Istio Service Mesh Control Plane box:

    • Click Create New. This screen allows you to modify the minimal template of a ServiceMeshControlPlane object, such as the cluster size.

    • Click Create to finalize.

  • Create a ServiceMeshMemberRoll by choosing the Istio Service Mesh Member Roll box and repeating these actions.

Verifying Installation

Policy enforcement is disabled by default. Instructions to enable it are here

Execute the following command to see the status of the installation. The installation has finished successfully when the READY column is true.

$ oc get smcp -n <controlplane-namespace>
NAME           READY
basic-install   True

Executing oc get pods -n <controlplane-namespace> should yield 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                   0/1     Running            0          22h
prometheus-6dff867c97-gr2n5              2/2     Running            0          28h

Removing a Control Plane

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

The following steps will remove Istio from an existing installation. It can be executed by any user in the maistra-admin ClusterRoleBinding for the control plane project.

To get the name of the installed ServiceMeshControlPlane, 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 a Control Plane using Catalog Web UI

To remove a control plane, open the OpenShift web console in a Web browser and:

  • Navigate to CatalogInstalled Operators.

  • Choose the istio-system from the Project menu.

  • Click the menu on the ServiceMeshMemberRoll row.

  • Click DetailsDelete Service Mesh Member Roll.

  • Click the menu on the ServiceMeshControlPlane row.

  • Click DetailsDelete Service Mesh Control Plane.

Upgrading a control plane

If you installed the Maistra operator using the Automatic Approval Strategy, then the operator and control plane will update automatically. If not, then you will have to manually upgrade each of the operators. In either case, the application sidecars must be updated separately from the control plane.

If your deployment is using using automatic injection, then the application only needs to be restarted in order to update the pod. Execute the following to update the deployment and trigger an update for all pods that are part of the deployment:

$ oc patch deployment/<deployment> -p '{"spec":{"template":{"metadata":{"annotations":{"kubectl.kubernetes.io/restartedAt": "'`date -Iseconds`'"}}}}}'

If your deployment uses manual injection, you must manually update the sidecars by modifying the sidecar container image specified in the deployment or pod.