Quick start Gloo Mesh on Kubernetes

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

With this guide, you can use a managed Kubernetes 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.7. To check your installed version, run istioctl version.
    • kubectl, the Kubernetes command line tool. Download the kubectl version that is within one minor version of the Kubernetes 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. Note: For any clusters that you plan to register as workload clusters, the cluster name cannot include underscores (_).

  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. 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>
  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.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
  2. Install Gloo Mesh Enterprise in your management cluster. This command creates a gloo-mesh namespace and uses default Helm chart values to install the management components.

    meshctl install --kubecontext $MGMT_CONTEXT --license $GLOO_MESH_LICENSE_KEY --version $GLOO_MESH_VERSION

    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.

  3. Verify that the management components have a status of Running.

    kubectl 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. 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 \
    meshctl cluster register \
      --kubecontext=$MGMT_CONTEXT \
      --remote-context=$REMOTE_CONTEXT2 \
      --version $GLOO_MESH_VERSION \

  2. 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.7-solo
  2. Set the Istio image repo.

    export REPO=<repo-key>
  3. Use the commands in both tabs to install Istio in each workload cluster.

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

  4. 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.

    kubectl get mesh -n gloo-mesh --context $REMOTE_CONTEXT1
    kubectl 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, 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 meshctl to install a minimum deployment of Gloo Mesh Enterprise for testing purposes, and some optional components are not installed. For example, self-signed certificates are used to secure communication between the management and workload clusters. To learn more about production-level 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.