Navigation :

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

Install the following CLI tools.
- istioctl, the Istio command line tool. The resources in the guide use Istio version 1.13.7. 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.
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.
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
```
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. Note: Do not use context names with underscores. The context name is used as a SAN specification in the generated that connects workload clusters to the management cluster, and underscores in SAN are not FQDN compliant. You can rename a context by running kubectl config rename-context "<oldcontext>" <newcontext>.
```
export MGMT_CONTEXT=<management-cluster-context>
export REMOTE_CONTEXT1=<remote-cluster-1-context>
export REMOTE_CONTEXT2=<remote-cluster-2-context>
```
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.

Set the Gloo Mesh Enterprise version to install. This guide installs Gloo Mesh Enterprise 2.0.19, which is not compatible with previous 1.x releases and custom resources such as VirtualMesh or TrafficPolicy.
```
export GLOO_MESH_VERSION=2.0.19
```

Create the gloo-mesh project.

oc new-project gloo-mesh --context $MGMT_CONTEXT

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

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.

To install the Gloo Mesh management components on a workload cluster that you also plan to register with Gloo Mesh, include the --set glooMeshMgmtServer.mgmtClusterName=<name> flag and set the value to the same name that you plan to use for this cluster during cluster registration.

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

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.

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
```

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.

cluster-1
cluster-2


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

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.

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.7-solo
```
Set the Istio image repo.
- Istio 1.12 and later: Specify a Gloo Mesh Istio repo key that you can get by logging in to the Support Center and reviewing the Istio images built by Solo.io support article. For more information, see Get the Gloo Mesh Istio version that you want to use.
- Istio 1.11 or earlier: Specify gcr.io/istio-enterprise.
```
export REPO=<repo-key>
```

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

Use the commands in both tabs to install Istio in each workload cluster.

cluster-1
cluster-2


CLUSTER_NAME=$REMOTE_CLUSTER1
curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/getting-started/2.0/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/gloo-mesh/getting-started/2.0/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

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

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.

Talk to an expert to get advice or build out a proof of concept.
Join the #gloo-mesh channel in the Solo.io community slack.
Try out one of the Gloo Mesh workshops.

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:

Self-signed certificates were used.
Prometheus was installed, but the security context for the default Prometheus instance was set to false due to a Helm bug where null values do not overwrite non-null subchart values. Although you see a Helm warning due to this setting, the rendered YAML file is still valid. Alternatively, you can configure a custom Prometheus instance.

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.