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.

ServiceMeshControlPlane

To deploy the Istio Control Plane, create a ServiceMeshControlPlane such as the one in the following example. The example uses istio-system as the control plane project. For more information about the parameters and their configuration, see the installation options.

apiVersion: maistra.io/v2
kind: ServiceMeshControlPlane
metadata:
  name: basic
spec:
  proxy:
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 128Mi
  tracing:
    type: Jaeger
  gateways:
    ingress: # istio-ingressgateway
      service:
        type: ClusterIP
        ports:
        - name: status-port
          port: 15020
        - name: http2
          port: 80
          targetPort: 8080
        - name: https
          port: 443
          targetPort: 8443
      meshExpansionPorts: []
    egress: # istio-egressgateway
      service:
        type: ClusterIP
        ports:
        - name: status-port
          port: 15020
        - name: http2
          port: 80
          targetPort: 8080
        - name: https
          port: 443
          targetPort: 8443
    additionalIngress:
      some-other-ingress-gateway: {}
    additionalEgress:
      some-other-egress-gateway: {}

  policy:
    type: Istiod # or Mixer
    mixer: # only applies if policy.type: Mixer
      enableChecks: false
      failOpen: false

  telemetry:
    type: Istiod # or Mixer
    mixer: # only applies if telemetry.type: Mixer, for v1 telemetry
      sessionAffinity: false
      batching:
        maxEntries: 100
        maxTime: 1s
      adapters:
        kubernetesenv: true
        stdio:
          enabled: true
          outputAsJSON: true
  addons:
    grafana:
      enabled: true
      install:
        config:
          env: {}
          envSecrets: {}
        persistence:
          storageClassName: ""
          accessMode: ReadWriteOnce
          capacity: 5Gi
        service:
          ingress:
            contextPath: /grafana
            tls:
              termination: reencrypt
    kiali:
      name: kiali
      enabled: true
      install: # install kiali CR if not present
        dashboard:
          viewOnly: false
          enableGrafana: true
          enableTracing: true
          enablePrometheus: true
      service:
        ingress:
          contextPath: /kiali
    jaeger:
      name: jaeger
      install:
        storage:
          type: Memory # or Elasticsearch
          memory:
            maxTraces: 100000
          elasticsearch:
            nodeCount: 3
            storage: {}
            redundancyPolicy: SingleRedundancy
            indexCleaner: {}
        ingress: {} # jaeger ingress configuration
  runtime:
    components:
      pilot:
        deployment:
          replicas: 2
        pod:
          affinity: {}
        container:
          resources:
          limits: {}
          requirements: {}
      grafana:
        deployment: {}
        pod: {}
      kiali:
        deployment: {}
        pod: {}

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.

Due to a bug in some versions of the OpenShift Management Console, a blank screen may appear when you click on "Create ServiceMeshControlPlane". To work around this problem, create the ServiceMeshControlPlane object with the oc apply command.

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

Substitute 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 with the web console

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 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 automatic injection, then the application only needs to be restarted 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.