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.
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
helm, the Kubernetes package manager.
oc, the OpenShift command line tool. Download the
ocversion 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
cluster-2are used. The
mgmt-clusterserves as the management cluster, and
cluster-2serve 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
CLUSTERcolumn, and get the context name in the
NAMEcolumn. 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.
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.
oc new-project gloo-mesh --context $MGMT_CONTEXT
Add and update the
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
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
oc get pods -n gloo-mesh --context $MGMT_CONTEXT
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.
Create a Helm values file to ensure that the
gloo-mesh-agentHelm 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=trueflag 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
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
solotag to use Gloo Mesh Istio, a hardened Istio enterprise image. If you downloaded a different version, make sure to specify that version instead.
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
Elevate the permissions of the
istio-operatorservice accounts that will be created in
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_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
istio-ingressgatewayload 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
meshresources 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.
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
falsedue to a Helm bug where
nullvalues do not overwrite non-
nullsubchart 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.