Set up Gloo Mesh and Istio
Start with setting up Gloo Mesh Enterprise in three clusters.
The following figure depicts the multi-mesh architecture created by this quick-start guide.
Before you begin
-
Add your Gloo Mesh Enterprise license that you got from your Solo account representative. Or, you might have a trial license key instead for a trial installation. If you do not have one, contact an account representative. If you prefer to specify license keys in a secret instead, see Prepare to install.
export GLOO_MESH_LICENSE_KEY=<gloo-mesh-or-trial-license-key>
-
Install the following CLI tools:
meshctl
, the Gloo command line tool for bootstrapping Gloo Platform, registering clusters, describing configured resources, and more.kubectl
, the Kubernetes command line tool. Download thekubectl
version that is within one minor version of the Kubernetes cluster you plan to use.- Openshift only:
oc
, the OpenShift command line tool. Download theoc
version that is the same minor version of the OpenShift cluster you plan to use.
-
Create three Kubernetes or OpenShift clusters. In this guide, the cluster names
mgmt-cluster
,cluster-1
, andcluster-2
are used. Themgmt-cluster
serves as the management cluster, andcluster-1
andcluster-2
serve as the workload clusters in this setup. Note: The cluster names cannot contain underscores (_
). -
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 theCLUSTER
column, and get the context name in theNAME
column. Note: Do not use context names with underscores. The context name is used as a SAN specification in the generated certificate that connects workload clusters to the management cluster, and underscores in SAN are not FQDN compliant. You can rename a context by runningkubectl 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>
Install Gloo in the management cluster
-
Install Gloo Mesh in your management cluster. This command creates a
gloo-mesh
namespace and installs the Gloo Platform components, such as the Gloo management server, and Prometheus server, in your management cluster.meshctl install --namespace gloo-mesh \ --kubecontext $MGMT_CONTEXT \ --license $GLOO_MESH_LICENSE_KEY \ --set mgmtClusterName=$MGMT_CLUSTER \ --set global.cluster=$MGMT_CLUSTER
By default, self-signed certificates are used to secure communication between the management and data planes. If you prefer to set up Gloo without secure communication for quick demonstrations, include the
--set insecure=true
flag. -
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
Register workload clusters
-
Save the following information in environment variables. This information is required for deploying managed Istio installations in workload clusters.
$REPO
: A Gloo 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.$ISTIO_IMAGE
: The Istio version, such as1.16.1-solo
.$REVISION
: Take the Istio major and minor version numbers and replace the period with a hyphen, such as1-16
.
export REPO=<repo-key> export ISTIO_IMAGE=1.16.1-solo export REVISION=1-16
-
Download the sample Helm values file from GitHub to your local workstation.
curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/getting-started/2.3/gs-multi.yaml > gs-multi.yaml
curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/getting-started/2.3/gs-multi-openshift.yaml > gs-multi.yaml
-
Update the
gs-multi.yaml
file with the environment variables that you previously set. Save the updated file asgs-multi-values.yaml
.- Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
envsubst < gs-multi.yaml > gs-multi-values.yaml
- Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
-
Openshift only: Elevate the permissions of the following service accounts that will be created in each workload cluster. These permissions allow the Istio sidecars to make use of a user ID that is normally restricted by OpenShift.
oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system --context $REMOTE_CONTEXT1 oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-16 --context $REMOTE_CONTEXT1 oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways --context $REMOTE_CONTEXT1
oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system --context $REMOTE_CONTEXT2 oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-16 --context $REMOTE_CONTEXT2 oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways --context $REMOTE_CONTEXT2
-
Use the commands in both tabs to register both workload clusters with the management server. These commands install the Gloo agent and managed Istio components in each workload cluster. If you installed the management components insecurely, include the
--relay-server-insecure=true
flag in these commands too.meshctl cluster register $REMOTE_CLUSTER1 \ --kubecontext $MGMT_CONTEXT \ --remote-context $REMOTE_CONTEXT1 \ --version $GLOO_VERSION \ --gloo-mesh-agent-chart-file gs-multi-values.yaml
meshctl cluster register $REMOTE_CLUSTER2 \ --kubecontext $MGMT_CONTEXT \ --remote-context $REMOTE_CONTEXT2 \ --version $GLOO_VERSION \ --gloo-mesh-agent-chart-file gs-multi-values.yaml
-
Verify that the Gloo agent and Istio pods have a status of
Running
.kubectl get pods -n gloo-mesh --context $REMOTE_CONTEXT1 kubectl get pods -n istio-system --context $REMOTE_CONTEXT1
kubectl get pods -n gloo-mesh --context $REMOTE_CONTEXT2 kubectl get pods -n istio-system --context $REMOTE_CONTEXT2
Example output:
NAME READY STATUS RESTARTS AGE gloo-mesh-agent-7f6bbc9f7f-gs89q 1/1 Running 0 31h
NAME READY STATUS RESTARTS AGE istiod-1-16-b65676555-g2vmr 1/1 Running 0 8m57s
-
Verify that the workload clusters are successfully identified by the management plane. If not, try debugging the relay connection. Note that this check might take a few seconds to ensure that the expected relay agents are now running and are connected to the relay server in the management cluster.
meshctl check --kubecontext $MGMT_CONTEXT
Example output:
Running Gloo Platform checks 🟢 Gloo Platform Deployment Status 🟢 Gloo Mgmt Server Connectivity to Agents +----------+------------+--------------------------------------------------+ | CLUSTER | REGISTERED | CONNECTED POD | +----------+------------+--------------------------------------------------+ | cluster1 | true | gloo-mesh/gloo-mesh-mgmt-server-676f4b9945-2pngd | +----------+------------+--------------------------------------------------+ | cluster2 | true | gloo-mesh/gloo-mesh-mgmt-server-676f4b9945-2pngd | +----------+------------+--------------------------------------------------+
-
Verify that Gloo successfully discovered the Istio service meshes in each workload cluster. Gloo 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
Create a Gloo workspace
Gloo workspaces let you organize team resources across Kubernetes namespaces and clusters. In this example, you create a single workspace for everything. Later, as your teams grow, you can create a workspace for each team, to enforce service isolation, set up federation, and even share resources by importing and exporting.
-
Create a workspace that selects all clusters and namespaces by default.
kubectl apply --context $MGMT_CONTEXT -f- <<EOF apiVersion: admin.gloo.solo.io/v2 kind: Workspace metadata: name: $MGMT_CLUSTER namespace: gloo-mesh spec: workloadClusters: - name: '*' namespaces: - name: '*' EOF
-
Create a workspace settings for the workspace that enables federation across clusters and selects the Istio east-west gateway.
kubectl apply --context $MGMT_CONTEXT -f- <<EOF apiVersion: admin.gloo.solo.io/v2 kind: WorkspaceSettings metadata: name: $MGMT_CLUSTER namespace: gloo-mesh spec: options: serviceIsolation: enabled: false federation: enabled: false serviceSelector: - {} eastWestGateways: - selector: labels: istio: eastwestgateway EOF
Next
Multitenancy, federation, and isolation: To see how Gloo Mesh helps you create a secure, multi-cluster service mesh, continue with the next section to configure Gloo Mesh for a multicluster use case.
Understand 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 profiles in this getting started guide were provided within the Gloo installation Helm chart for simplicity. However, Gloo Mesh can discover and manage Istio deployments regardless of their installation options. For more information, see the Gloo Istio setup guides.
Gloo workspace: Gloo workspaces let you organize team resources across Kubernetes namespaces and clusters. In this example, a single workspace is created for everything. Later, as your teams grow, you can create a workspace for each team, to enforce service isolation, set up federation, and even share resources by importing and exporting. You can also change the default workspace by following the Workspace setup guide.