☰
Navigation :

Install

Use Helm to customize your setup of Gloo Gateway in a single cluster.

In a single-cluster setup, you install the Gloo Gateway control plane and gateway proxy together, as shown in the following diagram.

Gloo Gateway single cluster installation architecture

To use a dedicated cluster for your Gloo Gateway control plane, and install gateway proxies in one or more workload clusters instead, see the Multicluster setup guide.

Before you begin

  1. Create or use an existing Kubernetes or OpenShift cluster, and save the name of the cluster as an environment variable. Note: The cluster name must be alphanumeric with no special characters except a hyphen (-), lowercase, and begin with a letter (not a number).

    export CLUSTER_NAME=<cluster_name>

  2. Set your Gloo Gateway license key as an environment variable. If you do not have one, contact an account representative. If you prefer to specify license keys in a secret instead, see Licensing.

    export GLOO_GATEWAY_LICENSE_KEY=<gloo-gateway-license-key>

  3. Set the Gloo Gateway version as an environment variable. 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.4.0-fips’. Do not include v before the version number.

    export GLOO_VERSION=2.4.0

  4. Install the following CLI tools:

    • helm, the Kubernetes package manager.
    • meshctl, the Gloo command line tool for bootstrapping Gloo Platform, registering clusters, describing configured resources, and more. Be sure to download version 2.4.0, which uses the latest Gloo Gateway CRDs.
    • 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.

  5. Production installations: Review Best practices for production to prepare your 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.

Install Gloo Gateway with Helm

Customize your Gloo setup by installing with the Gloo Platform Helm chart.

  1. Add and update the Helm repository for Gloo Platform.

    helm repo add gloo-platform https://storage.googleapis.com/gloo-platform/helm-charts
helm repo update

  2. Apply the Gloo Platform CRDs to your cluster by creating a gloo-platform-crds Helm release. Note: If you plan to manually deploy and manage your Istio installation in workload clusters rather than using the Solo Istio lifecycle manager, include the --set installIstioOperator=false flag to ensure that the Istio operator CRD is not managed by this Gloo CRD Helm release.

    helm install gloo-platform-crds gloo-platform/gloo-platform-crds \
   --namespace=gloo-mesh \
   --create-namespace \
   --version $GLOO_VERSION

  3. Prepare a Helm values file for production-level settings, including FIPS-compliant images, OIDC authorization for the Gloo UI, and more. To get started, you can use the minimum settings in the gloo-gateway-single profile as a basis for your values file. This profile enables all of the necessary components that are required for a single-cluster Gloo Gateway installation, such as the management server, agent, and gateway proxy, as well as some optional components, such as the Gloo UI. 

    curl https://storage.googleapis.com/gloo-platform/helm-profiles/$GLOO_VERSION/gloo-gateway-single.yaml > gloo-gateway-single.yaml
open gloo-gateway-single.yaml

    For more information, see the Istio on OpenShift documentation.

    1. Elevate the permissions of the following service accounts that will be created. These permissions allow the ingress gateway proxy 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
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways
# Update revision as needed
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-18-2
    2. Create the gloo-mesh-gateways project, and create a NetworkAttachmentDefinition custom resource for the project. 
      kubectl create ns gloo-mesh-gateways
cat <<EOF | oc -n gloo-mesh-gateways create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF
    3. Elevate the permissions of the service account in each project where you want to deploy workloads. 
      oc adm policy add-scc-to-group anyuid system:serviceaccounts:<project>
    4. Create a NetworkAttachmentDefinition custom resource for each project where you want to deploy workloads. 
      cat <<EOF | oc -n <project> create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF
    5. Download the gloo-gateway-single-openshift profile as a basis for your values file. 
      curl https://storage.googleapis.com/gloo-platform/helm-profiles/$GLOO_VERSION/gloo-gateway-single-openshift.yaml > gloo-gateway-single.yaml
open gloo-gateway-single.yaml

      Note: When you use the settings in this profile to install Gloo Gateway in OpenShift 4.11 and later, you might see warnings for the pods and containers which violate the OpenShift PodSecurity "restricted:v1.24" profile, due to the elevated permissions required by Istio. You can ignore these warnings. For more info, see this article.

  4. Edit the file to provide your own details for settings that are recommended for production deployments, such as the following optional settings.

    Field Decription
    glooMgmtServer.resources.limits Add resource limits for the gloo-mesh-mgmt-server pod, such as cpu: 1000m and memory: 1Gi.
    glooMgmtServer.serviceOverrides.metadata.annotations Add annotations for the management server load balancer as needed, such as AWS-specific load balancer annotations. For more information, see Deployment and service overrides.
    glooUi.auth Set up OIDC authorization for the Gloo UI. For more information, see UI authentication.
    istioInstallations The default supported version of Istio is used to install the managed gateway proxies. You can instead choose the Istio version you want to use for your gateway proxy. For an example of how this section might look, expand “Example: istioInstallations section” after this table.
    NOTE: To manage the gateway proxies yourself instead of the gateway lifecycle manager in this Helm chart, set istioInstallations.enabled to false, and manually deploy gateway proxies.
    prometheus.enabled Disable the default Prometheus instance as needed to provide your own. Otherwise, you can keep the default Prometheus server enabled, and deploy a production-level server to scrape metrics from the server. For more information on each option, see Customization options.
    redis Disable the default Redis deployment and provide your own backing database as needed. For more information, see Backing databases.

    Example: istioInstallations section

    For more information about the settings you can configure:

  5. Install the Gloo Gateway control plane and data plane components in your cluster, including the customizations in your Helm values file.

    helm install gloo-platform gloo-platform/gloo-platform \
   --namespace gloo-mesh \
   --version $GLOO_VERSION \
   --values gloo-gateway-single.yaml \
   --set common.cluster=$CLUSTER_NAME \
   --set licensing.glooGatewayLicenseKey=$GLOO_GATEWAY_LICENSE_KEY

  6. Optional: Install add-ons, such as the external auth and rate limit servers, in a separate Helm release. Only create this release if you did not enable the extAuthService and rateLimiter in your main installation release.

    Want to expose your APIs through a developer portal? You must include some extra Helm settings. To install, see Portal.

    helm install gloo-agent-addons gloo-platform/gloo-platform \
   --namespace gloo-mesh-addons \
   --create-namespace \
   --version $GLOO_VERSION \
   --set common.cluster=$CLUSTER_NAME \
   --set extAuthService.enabled=true \
   --set rateLimiter.enabled=true
    1. Elevate the permissions of the gloo-mesh-addons service account that will be created. 
      oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-addons
    2. Create the gloo-mesh-addons project, and create a NetworkAttachmentDefinition custom resource for the project. 
      kubectl create ns gloo-mesh-addons
cat <<EOF | oc -n gloo-mesh-addons create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF
    3. Create the add-ons release. 
      helm install gloo-agent-addons gloo-platform/gloo-platform \
   --namespace gloo-mesh-addons \
   --version $GLOO_VERSION \
   --set common.cluster=$CLUSTER_NAME \
   --set extAuthService.enabled=true \
   --set rateLimiter.enabled=true

  7. Create a workspace that selects all clusters and namespaces by default, and workspace settings that enable communication across clusters. Gloo workspaces let you organize team resources across Kubernetes namespaces and clusters. In this example, you create a global workspace that imports and exports all resources and namespaces, and a workspace settings resource in the gloo-mesh-config namespace. 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. 

    kubectl apply -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: Workspace
metadata:
  name: $CLUSTER_NAME
  namespace: gloo-mesh
spec:
  workloadClusters:
    - name: '*'
      namespaces:
        - name: '*'
---
apiVersion: v1
kind: Namespace
metadata:
  name: gloo-mesh-config
---
apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
  name: $CLUSTER_NAME
  namespace: gloo-mesh-config
spec:
  options:
    serviceIsolation:
      enabled: false
    federation:
      enabled: false
      serviceSelector:
      - {}
    eastWestGateways:
    - selector:
        labels:
          istio: eastwestgateway
EOF

Verify the installation

Ensure that Gloo Gateway is successfully installed to your cluster.

  1. Verify that Gloo Gateway is correctly installed. This check might take a few seconds to verify that:

    • Your Gloo Platform product licenses are valid and current.
    • The Gloo Platform CRDs are installed at the correct version.
    • The Gloo Gateway pods are running and healthy.
    • The Gloo agent is running and connected to the management server.
    meshctl check

    Example output:

    🟢 License status

 INFO  gloo-gateway enterprise license expiration is 25 Aug 23 10:38 CDT
 INFO  Valid GraphQL license module found

🟢 CRD version check

🟢 Gloo Platform deployment status

Namespace        | Name                           | Ready | Status 
gloo-mesh        | gloo-mesh-agent                | 1/1   | Healthy
gloo-mesh        | gloo-mesh-mgmt-server          | 1/1   | Healthy
gloo-mesh        | gloo-mesh-redis                | 1/1   | Healthy
gloo-mesh        | gloo-mesh-ui                   | 1/1   | Healthy
gloo-mesh        | prometheus-server              | 1/1   | Healthy
gloo-mesh-addons | ext-auth-service               | 1/1   | Healthy
gloo-mesh-addons | rate-limiter                   | 1/1   | Healthy
gloo-mesh-addons | redis                          | 1/1   | Healthy
gloo-mesh        | gloo-telemetry-collector-agent | 3/3   | Healthy


🟢 Mgmt server connectivity to workload agents

Cluster  | Registered | Connected Pod                                   
cluster1 | true       | gloo-mesh/gloo-mesh-mgmt-server-65bd557b95-v8qq6

  2. Verify that the gateway proxy service is created and assigned an external IP address. It might take a few minutes for the load balancer to deploy. Note: If you did not deploy a managed gateway proxy through the Helm installation, manually deploy the gateway proxy instead.

    kubectl get svc -n gloo-mesh-gateways

    Example output:

    NAME                            TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)                                                      AGE
istio-ingressgateway            LoadBalancer   10.XX.X.XXX    34.XXX.XXX.XXX   15021:30826/TCP,80:31257/TCP,443:30673/TCP,15443:30789/TCP   48s

  3. Optional: Check out the workspace and workspace settings that were created for you. Workspaces help to organize team resources in your cluster, and to isolate Kubernetes and Gloo Gateway resources. Because the default workspace is used for demonstration purposes, it does not isolate any resources, and instead allows all Kubernetes and Gloo Gateway resources in the workspace.

    kubectl get workspace $CLUSTER_NAME -n gloo-mesh -o yaml

    kubectl get workspacesettings default -n gloo-mesh -o yaml

    If you want to learn more about how to configure workspaces to isolate Kubernetes and Gloo Gateway resources for multiple teams, see the Multitenancy concepts page and the Organize team resources with workspaces guide.

  4. Optional for OpenShift: Expose the ingress gateway by using an OpenShift route.

    oc -n gloo-mesh-gateways expose svc istio-ingressgateway --port=http2

Next steps

Now that Gloo Gateway is installed, check out the following resources to explore Gloo Gateway capabilities: