Quick start Gloo Mesh on OpenShift

Quickly get started with Gloo Mesh Enterprise by deploying a demo environment to your OpenShift clusters.

With this guide, you can use a managed OpenShift environment, such as clusters in Google Kubernetes Engine (GKE) or Amazon Elastic Kubernetes Service (EKS), to install Gloo Mesh Enterprise in a management cluster, register workload clusters, and install Istio service meshes in workload clusters.

The following figure depicts the multi-mesh architecture created by this quick-start guide.

Figure of a three-cluster Gloo Mesh quick-start architecture.

Before you begin

  1. Install the following CLI tools.

    • istioctl, the Istio command line tool. The resources in the guide use Istio version 1.13.5. To check your installed version, run istioctl version.
    • helm, the Kubernetes package manager.
    • oc, the OpenShift command line tool. Download the oc version that is the same minor version of the OpenShift clusters you plan to use with Gloo Mesh.
    • meshctl, the Gloo Mesh command line tool for bootstrapping Gloo Mesh, registering clusters, describing configured resources, and more.
  2. Create three Kubernetes clusters. In this guide, the cluster names mgmt-cluster, cluster-1, and cluster-2 are used. The mgmt-cluster serves as the management cluster, and cluster-1 and cluster-2 serve as the workload clusters in this setup. Note: To test access to the Istio ingress gateway in this and later guides, ensure that your cluster setup enables you to externally access LoadBalancer services on the workload clusters.

  3. Set the names of your clusters from your infrastructure provider. If your clusters have different names, specify those names instead.

    export MGMT_CLUSTER=mgmt-cluster
    export REMOTE_CLUSTER1=cluster-1
    export REMOTE_CLUSTER2=cluster-2
    
  4. Save the kubeconfig contexts for your clusters. Run kubectl config get-contexts, look for your cluster in the CLUSTER column, and get the context name in the NAME column.
    export MGMT_CONTEXT=<management-cluster-context>
    export REMOTE_CONTEXT1=<remote-cluster-1-context>
    export REMOTE_CONTEXT2=<remote-cluster-2-context>
    
  5. Add your Gloo Mesh Enterprise license that you got from your Solo account representative. If you do not have a key yet, you can get a trial license by contacting an account representative.

    export GLOO_MESH_LICENSE_KEY=<license_key>
    

Step 1: Install Gloo Mesh Enterprise in the management cluster

Install the Gloo Mesh Enterprise management components into your management cluster.

When you create service mesh configurations, the management components translate your Gloo Mesh configurations into Istio resources that are implemented across clusters and service meshes. The management plane also aggregates all of the discovered Istio service mesh components into simplified, internal Gloo Mesh custom resources.

  1. Set the Gloo Mesh Enterprise version to install. This guide installs Gloo Mesh Enterprise 2.1.0-beta8, which is not compatible with previous 1.x releases and custom resources such as VirtualMesh or TrafficPolicy.

    export GLOO_MESH_VERSION=2.1.0-beta8
    
  2. Create the gloo-mesh project.

    oc new-project gloo-mesh --context $MGMT_CONTEXT
    
  3. Add and update the gloo-mesh-enterprise Helm repository.

    helm repo add gloo-mesh-enterprise https://storage.googleapis.com/gloo-mesh-enterprise/gloo-mesh-enterprise
    helm repo update
    
  4. Install Gloo Mesh Enterprise in your management cluster.

    helm install gloo-mesh-enterprise gloo-mesh-enterprise/gloo-mesh-enterprise --kube-context $MGMT_CONTEXT -n gloo-mesh \
    --version $GLOO_MESH_VERSION \
    --set licenseKey=$GLOO_MESH_LICENSE_KEY \
    --set glooMeshMgmtServer.prometheus.server.securityContext=false \
    --set glooMeshMgmtServer.floatingUserId=true \
    --set glooMeshUi.floatingUserId=true \
    --set glooMeshRedis.floatingUserId=true
    
    By default, self-signed certificates are used to secure communication between the management and data planes. If you prefer to set up Gloo Mesh without secure communication for quick demonstrations, include the --set insecure=true flag.
  5. Verify that the management components have a status of Running.

    oc get pods -n gloo-mesh --context $MGMT_CONTEXT
    

    Example output:

    NAME                                     READY   STATUS    RESTARTS   AGE
    gloo-mesh-mgmt-server-778d45c7b5-5d9nh   1/1     Running   0          41s
    gloo-mesh-redis-844dc4f9-jnb4j           1/1     Running   0          41s
    gloo-mesh-ui-749dc7875c-4z77k            3/3     Running   0          41s
    prometheus-server-86854b778-r6r52        2/2     Running   0          41s
    

Step 2: Register workload clusters

Register your workload clusters with the Gloo Mesh management plane.

The Gloo Mesh agent that runs on each registered workload cluster discovers Gloo Mesh and Kubernetes resources, such as deployments and services, and sends snapshots of them to the management server for translation into Istio resources.

  1. Create a Helm values file to ensure that the gloo-mesh-agent Helm chart uses floatingUserId. This setting is needed for proper UI functionality in OpenShift.

    cat > /tmp/gloo-mesh-agent-values.yaml << EOF
    glooMeshAgent:
      floatingUserId: true
    EOF
    
  2. Use the commands in both tabs to register both workload clusters with the management server. If you installed the management components insecurely, include the --relay-server-insecure=true flag in this command.

    
    meshctl cluster register \
      --kubecontext=$MGMT_CONTEXT \
      --remote-context=$REMOTE_CONTEXT1 \
      --version $GLOO_MESH_VERSION \
      --gloo-mesh-agent-chart-values /tmp/gloo-mesh-agent-values.yaml \
      $REMOTE_CLUSTER1
    
    
    meshctl cluster register \
      --kubecontext=$MGMT_CONTEXT \
      --remote-context=$REMOTE_CONTEXT2 \
      --version $GLOO_MESH_VERSION \
      --gloo-mesh-agent-chart-values /tmp/gloo-mesh-agent-values.yaml \
      $REMOTE_CLUSTER2
    

  3. Verify that each workload cluster is successfully registered with the Gloo Mesh management server.

    meshctl cluster list --kubecontext $MGMT_CONTEXT
    

Step 3: Install Istio in the workload clusters

Install an Istio service mesh into both workload clusters so that Gloo Mesh can discover and configure Istio workloads running in these registered clusters.

  1. Set the Istio version. The latest version is used as an example. Additionally, append the solo tag to use Gloo Mesh Istio, a hardened Istio enterprise image. If you downloaded a different version, make sure to specify that version instead.

    export ISTIO_IMAGE=1.13.5-solo
    
  2. Set the Istio image repo.

    export REPO=<repo-key>
    
  3. Elevate the permissions of the istio-system and istio-operator service accounts that will be created in cluster-1 and cluster-2. These permissions allow the Istio sidecars to make use of a user ID that is normally restricted by OpenShift.

    oc --context $REMOTE_CONTEXT1 adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system
    oc --context $REMOTE_CONTEXT1 adm policy add-scc-to-group anyuid system:serviceaccounts:istio-operator
    oc --context $REMOTE_CONTEXT2 adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system
    oc --context $REMOTE_CONTEXT2 adm policy add-scc-to-group anyuid system:serviceaccounts:istio-operator
    
  4. Use the commands in both tabs to install Istio in each workload cluster.

    
    CLUSTER_NAME=$REMOTE_CLUSTER1
    curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/getting-started/2.1/demo-istio-openshift.yaml > demo-istio-openshift-1.yaml
    envsubst < demo-istio-openshift-1.yaml > demo-istio-openshift-1-env.yaml
    istioctl install -y --context $REMOTE_CONTEXT1 -f demo-istio-openshift-1-env.yaml
    
    
    CLUSTER_NAME=$REMOTE_CLUSTER2
    curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/getting-started/2.1/demo-istio-openshift.yaml > demo-istio-openshift-2.yaml
    envsubst < demo-istio-openshift-2.yaml > demo-istio-openshift-2-env.yaml
    istioctl install -y --context $REMOTE_CONTEXT2 -f demo-istio-openshift-2-env.yaml
    

  5. Expose the istio-ingressgateway load balancer on each cluster by using an OpenShift route.

    oc --context $REMOTE_CONTEXT1 -n istio-system expose svc/istio-ingressgateway --port=http2
    oc --context $REMOTE_CONTEXT2 -n istio-system expose svc/istio-ingressgateway --port=http2
    
  6. Verify that Gloo Mesh successfully discovered the Istio service meshes in each workload cluster. Gloo Mesh creates internal mesh resources to represent the state of the Istio service mesh in each cluster.

    oc get mesh -n gloo-mesh --context $REMOTE_CONTEXT1
    oc get mesh -n gloo-mesh --context $REMOTE_CONTEXT2
    

Now that Gloo Mesh management plane is installed, the workload clusters are registered, and the Istio meshes in the workload clusters are discovered by Gloo Mesh, your Gloo Mesh Enterprise setup is complete! Next you can keep going with more Gloo Mesh guides, or take a moment to understand what happened.

Step 4: Launch the Gloo Mesh UI

The Gloo Mesh UI provides a single pane of glass through which you can observe the status of your service meshes, workloads, and services that run across all of your clusters. You can also view the policies that configure the behavior of your network.

To access the Gloo Mesh UI:

meshctl dashboard --kubecontext $MGMT_CONTEXT

The Overview page presents an at-a-glance look at the health of workspaces and clusters that make up your Gloo Mesh setup. In the Clusters pane, you can review the workload clusters that are currently connected to your Gloo Mesh setup. Note that because you haven't created any workspaces yet to run your workloads in, the Workspaces pane is empty. Check out the next steps to create workspaces and deploy workloads.

To learn more about what you can do with the UI, see the Gloo Mesh UI guides.

Next steps

Up next: Multitenancy, federation, and isolation. To see how Gloo Mesh Enterprise helps you create a secure, multi-cluster service mesh, continue with the next section to configure Gloo Mesh for a multicluster use case.

You can also check out some of the following resources to learn more about Gloo Mesh or try other Gloo Mesh features.

Understanding what happened

Find out more information about the Gloo Mesh environment that you set up in this guide.

Gloo Mesh installation: This quick start guide used helm to install a minimum deployment of Gloo Mesh Enterprise for testing purposes, and some optional components were not installed. For example:

To learn more about these installation options, including advanced configuration options available in the Gloo Mesh Enterprise Helm chart, see the Setup guide.

Relay architecture: When you installed Gloo Mesh Enterprise in the management cluster, a deployment named gloo-mesh-mgmt-server was created to run the relay server. When you registered the workload clusters to be managed by Gloo Mesh Enterprise, a deployment named gloo-mesh-agent was created on each workload cluster to run a relay agent. All communication is outbound from the relay agents on the workload clusters to the relay server on the management cluster. For more information about relay server-agent communication, see the relay architecture page. Additionally, default, self-signed certificates were used to secure communication between the management and data planes. For more information about the certificate architecture, see Default Gloo Mesh-managed certificates.

Workload cluster registration: Cluster registration creates a KubernetesCluster custom resource on the management cluster to represent the workload cluster and store relevant data, such as the workload cluster's local domain (“cluster.local”). To learn more about cluster registration and how to register clusters with Helm rather than meshctl, review the cluster registration guide.

Istio installation: The Istio installation profiles in this getting started guide were provided for their simplicity. For example, you installed the istio-ingressgateway for ingress (north-south) traffic and istio-eastwestgateway for cross-cluster (east-west) traffic in the same namespace as the Istio control plane. However, Gloo Mesh can discover and manage Istio deployments regardless of their installation options. For more information, see the Gloo Mesh Istio setup guides and the Istio documentation for OpenShift installation.