Install Gloo

Install the Gloo Platform management components into a cluster.

Your Gloo setup consists of a management plane and a data plane.

Before you begin

  1. Create or choose a cluster to serve as the management cluster. Note: If this cluster runs a service mesh, and you plan to also register it with Gloo as a workload cluster, the cluster name cannot include underscores (_).

  2. Set the names of your clusters from your infrastructure provider.
    export MGMT_CLUSTER=<management_cluster_name>
    
  3. 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>
    
  4. 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>
    
  5. Set the Gloo Mesh Enterprise version. The latest version is used as an example. You can find other versions in the Changelog documentation. Append -fips for a FIPS-compliant image, such as 2.1.0-beta27-fips. Do not include v before the version number.

    Gloo Platform version 2.1.0-beta27 is not compatible with previous 1.x releases and custom resources such as VirtualMesh or TrafficPolicy.

    export GLOO_MESH_VERSION=2.1.0-beta27
    
  6. Production installations: Review Best practices for production to prepare your optional security measures. For example, before you begin your Gloo installation, you can provide your own certificates and set up secure access to the Gloo UI.

  7. To customize your installation in detail, such as for production environments, install with Helm. For quick installations, such as for testing environments, you can install with meshctl.

Installing with Helm

Customize your management plane by installing with the Gloo Helm chart.

  1. Install helm, the Kubernetes package manager.

  2. Add and update the Helm repository for the Gloo management server.

    helm repo add gloo-mesh-enterprise https://storage.googleapis.com/gloo-mesh-enterprise/gloo-mesh-enterprise
    helm repo update
    
  3. Prepare a Helm values file for production-level settings or for default settings.

    You can edit the values-mgmt-plane.yaml values file to provide your own details for settings that are recommended for production-level deployments, including FIPS-compliant images, custom certificates, and OIDC authorization for the Gloo UI. Additionally, this values file includes a glooMeshMgmtServer.serviceOverrides section, which applies the recommended Amazon Web Services (AWS) annotations for modifying the deployed load balancer service. For more information about these settings, see Best practices for production and the Helm values documentation for each component.

    1. Download the sample values file from GitHub to your local workstation.
      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/helm-install/2.1/values-mgmt-plane.yaml > values-mgmt-plane.yaml
      
    2. Update the Helm values file with the environment variables that you previously set for $MGMT_CLUSTER, $GLOO_MESH_LICENSE_KEY, and $GLOO_MESH_VERSION. Save the updated file as values-mgmt-plane-env.yaml.
      • Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
        envsubst < values-mgmt-plane.yaml > values-mgmt-plane-env.yaml
        
    3. Edit the file to provide your own details for settings that are recommended for production deployments, including custom certificates, OIDC authorization for the Gloo Mesh UI, and more. If you do not want to use these settings, you must comment them out. Note: To install the Gloo Mesh management components on a workload cluster that you also plan to register with Gloo Mesh, set the glooMeshMgmtServer.mgmtClusterName value to the same name that you plan to use for this cluster during cluster registration.
    1. Save the default Helm values. Note that the gloo-mesh-enterprise Helm chart bundles multiple components, including glooMeshMgmtServer, glooMeshUi, and glooMeshRedis. Each is versioned in step with the parent gloo-mesh-enterprise chart, and each has its own Helm values for advanced customization. For more information, review the Gloo management Helm values documentation.
      helm show values gloo-mesh-enterprise/gloo-mesh-enterprise --version $GLOO_MESH_VERSION > values-mgmt-plane-env.yaml
      
    2. Edit the file to provide the required details.
      • For glooMeshLicenseKey, specify $GLOO_MESH_LICENSE_KEY.
      • For global.cluster, specify $MGMT_CLUSTER. To install the Gloo management components on a workload cluster that you also plan to register with Gloo, set the value to the same name that you plan to use for this cluster during cluster registration.

  4. Create the gloo-mesh namespace in your management cluster.

    kubectl create ns gloo-mesh --context $MGMT_CONTEXT
    
  5. Install the Gloo management Helm chart in the gloo-mesh namespace, including the customizations in your Helm values file.

    helm install gloo-mgmt gloo-mesh-enterprise/gloo-mesh-enterprise \
      --namespace gloo-mesh \
      --kube-context=$MGMT_CONTEXT \
      --set licenseKey=$GLOO_MESH_LICENSE_KEY
      --values values-mgmt-plane-env.yaml
    
  6. Verify that the management component pods 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
    

Installing with meshctl

Quickly install Gloo Platform by using meshctl.

  1. Install the latest version of meshctl. For more information, see Install the meshctl CLI.

  2. Install the Gloo management components. Note that this command installs a minimum deployment of Gloo 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. If you want to customize your installation, you can include a Helm values override file in the --chart-values-file flag, or specify individual Helm settings by using --set <setting>=<value>. For more information, review the Gloo management Helm values documentation.

    meshctl install creates a self-signed certificate authority for mTLS if you do not supply your own certificates. If you prefer to set up Gloo without secure communication for quick demonstrations, include the --set insecure=true flag. Note that using the default self-signed CAs or using insecure mode are not suitable for production environments.

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

    Example output:

    Installing Helm chart
    Finished installing chart 'gloo-mesh-enterprise' as release gloo-mesh:gloo-mesh
    
  3. Verify that the management component pods 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
    

Next Steps

Now that the Gloo management components are installed, you can register workload clusters so that Gloo can identify and manage their service meshes.