☰
Navigation :

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.

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

Before you begin

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

  2. 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 the kubectl version that is within one minor version of the Kubernetes cluster you plan to use.
    • Openshift only: oc, the OpenShift command line tool. Download the oc version that is the same minor version of the OpenShift cluster you plan to use.

  3. Create three Kubernetes or OpenShift 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: The cluster names cannot contain underscores (_).

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

Install Gloo in the management cluster

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

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

  1. 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 as 1.16.1-solo.
    • $REVISION: Take the Istio major and minor version numbers and replace the period with a hyphen, such as 1-16.
    export REPO=<repo-key>
export ISTIO_IMAGE=1.16.1-solo
export REVISION=1-16

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

  3. Update the gs-multi.yaml file with the environment variables that you previously set. Save the updated file as gs-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

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

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

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

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

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

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

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