☰
Navigation :

Installing Gloo Gateway on Kubernetes

Gloo Gateway can be installed on a Kubernetes cluster by using either the glooctl command line tool or a Helm chart. Follow this guide to install, verify the installation, or uninstall Gloo Gateway.

Before you begin

  1. Make sure that you prepared your Kubernetes cluster according to the instructions for platform configuration.

    Pay attention to provider-specific information in the setup guide. For example, OpenShift requires stricter multi-tenant support, so the setup guide includes an example Helm chart values.yaml file that you must supply while installing Gloo Gateway Enterprise.

  2. Enterprise Edition only: Get your Gloo Gateway Enterprise license key. To run the Enterprise Edition, you must install or upgrade Gloo Gateway with an enterprise license key. Contact your Solo Account Representative for a license key. To request a trial, fill out this request form and check Gloo Gateway. If your license key is expired, you can update the license key.

  3. Check whether glooctl, the Gloo Gateway command line tool (CLI), is installed.

    glooctl version

Install the Gloo Gateway command line tool (CLI)

You can install the Gloo Gateway command line, glooctl, to help install, configure, and debug Gloo Gateway. Depending on your operating system, you have several installation options.

Update glooctl CLI version

When it’s time to upgrade Gloo Gateway, make sure to update the glooctl version before upgrading.

You can use the glooctl upgrade command to upgrade or roll back the glooctl version. For example, you might change versions during an upgrade process, or when you have multiple versions of Gloo Gateway across clusters that you manage from the same workstation. For more options, run glooctl upgrade --help.

  1. Set the version to upgrade glooctl to in an environment variable. Include the patch version. For Gloo Gateway Enterprise, specify the Gloo Gateway OSS version that corresponds to the Gloo Gateway Enterprise version you want to upgrade to. To find the OSS version that corresponds to each Gloo Gateway Enterprise release, see the Gloo Gateway Enterprise changelogs.

    export GLOOCTL_VERSION=<version>

  2. Upgrade your version of glooctl.

    glooctl upgrade --release v${GLOOCTL_VERSION}

Verify the installation or update

Verify the glooctl CLI is installed and running the appropriate version. In the output, the Client is your local version. The Server is the version that runs in your cluster, and is undefined if Gloo Gateway is not installed yet.

glooctl version

Installing Gloo Gateway on Kubernetes

Review the following steps to install Gloo Gateway with glooctl or with Helm.

Installing on Kubernetes with glooctl

Once your Kubernetes cluster is up and running, run the following command to deploy Gloo Gateway to the gloo-system namespace:

glooctl install gateway
Special Instructions to Install Gloo Gateway on Kind If you followed the cluster setup instructions for Kind here, then you should have exposed custom ports 31500 (for http) and 32500 (https) from your cluster's Docker container to its host machine. The purpose of this is to make it easier to access your service endpoints from your host workstation. Use the following custom installation for Gloo Gateway to publish those same ports from the proxy as well. 
cat <<EOF | glooctl install gateway --values -
gatewayProxies:
  gatewayProxy:
    service:
      type: NodePort
      httpPort: 31500
      httpsPort: 32500
      httpNodePort: 31500
      httpsNodePort: 32500
EOF

Creating namespace gloo-system... Done.
Starting Gloo Gateway installation...

Gloo Gateway was successfully installed!

Note also that the url to invoke services published via Gloo Gateway will be slightly different with Kind-hosted clusters. Much of the Gloo Gateway documentation instructs you to use $(glooctl proxy url) as the header for your service url. This will not work with kind. For example, instead of using curl commands like this:

curl $(glooctl proxy url)/all-pets

You will instead route your request to the custom port that you configured above for your docker container to publish. For example:

curl http://localhost:31500/all-pets

Video with example output

Once you’ve installed Gloo Gateway, please be sure to verify your installation.

You can run the command with the flag --dry-run to output the Kubernetes manifests (as yaml) that glooctl will apply to the cluster instead of installing them. Note that a proper Gloo Gateway installation depends on Helm Chart Hooks, so the behavior of your installation may not be correct if you install by directly applying the dry run manifests, e.g. glooctl install gateway --dry-run | kubectl apply -f -.

Installing on Kubernetes with Helm

Using Helm 2 is not supported in Gloo Gateway.

As a first step, you have to add the Gloo Gateway repository to the list of known chart repositories, as well as prepare the installation namespace:

helm repo add gloo https://storage.googleapis.com/solo-public-helm
helm repo update
kubectl create namespace my-namespace

For an installation with all the default values, use one of the following commands:

helm install gloo gloo/gloo --namespace my-namespace

Once you’ve installed Gloo Gateway, please be sure to verify your installation.


Customizing your installation with Helm

You can customize the Gloo Gateway installation by providing your own Helm chart values file.

For example, you can create a file named value-overrides.yaml with the following content.

global:
  glooRbac:
    # do not create kubernetes rbac resources
    create: false
settings:
  # configure gloo to write generated custom resources to a custom namespace
  writeNamespace: my-custom-namespace
  watchNamespaces:
  - default
  - my-custom-namespace
gloo:
  gateway:
    # For multiple gateways: read Gateway config in all 'watchNamespaces',
    # not just the namespace that the gateway controller is deployed to
    readGatewaysFromAllNamespaces: true

Then, refer to the file during installation to override default values in the Gloo Gateway Helm chart.

helm install gloo-custom-0-7-6 gloo/gloo --namespace my-namespace -f value-overrides.yaml

List of Gloo Gateway Helm chart values

The Helm Chart Values page describes all the values that you can override in your custom values file.

Verify your Installation

To verify that your installation was successful, check that the Gloo Gateway pods and services have been created. Depending on your install options, you may see some differences from the following example. If you choose to install Gloo Gateway into a namespace other than the default gloo-system, you will need to query your chosen namespace instead.

kubectl get all -n gloo-system

NAME                                READY     STATUS    RESTARTS   AGE
pod/discovery-f7548d984-slddk       1/1       Running   0          5m
pod/gateway-proxy-9d79d48cd-wg8b8   1/1       Running   0          5m
pod/gloo-5b7b748dbf-jdsvg           1/1       Running   0          5m

NAME                    TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                     AGE
service/gateway-proxy   LoadBalancer   10.97.232.107   <pending>     80:30221/TCP,443:32340/TCP  5m
service/gloo            ClusterIP      10.100.64.166   <none>        9977/TCP,9988/TCP,9966/TCP  5m

NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/discovery       1/1     1            1           5m
deployment.apps/gateway-proxy   1/1     1            1           5m
deployment.apps/gloo            1/1     1            1           5m

NAME                                      DESIRED   CURRENT   READY     AGE
replicaset.apps/discovery-f7548d984       1         1         1         5m
replicaset.apps/gateway-proxy-9d79d48cd   1         1         1         5m
replicaset.apps/gloo-5b7b748dbf           1         1         1         5m

Looking for opened ports?

You will NOT have any open ports listening on a default install. For Envoy to open the ports and actually listen, you need to have a Route defined in one of the VirtualServices that will be associated with that particular Gateway/Listener. Please see the Hello World tutorial to get started.

NOT opening the listener ports when there are no listeners (routes) is by design with the intention of not over-exposing your cluster by accident (for security). If you feel this behavior is not justified, please let us know.

Uninstall

To uninstall Gloo Gateway, you can use the glooctl CLI. If you installed Gloo Gateway to a different namespace, include the -n option.

glooctl uninstall -n my-namespace

By default, the gloo-system namespace and Custom Resource Definitions created by the glooctl install command are not removed. To remove the namespace and CRDs, include the --all option.

Make sure that your cluster has no other instances of Gloo Gateway running, such as by running kubectl get pods --all-namespaces. If you remove the CRDs while Gloo Gateway is still installed, you will experience errors.

glooctl uninstall --all

Uninstall with glooctl video

Next Steps

After you’ve installed Gloo Gateway, please check out our user guides on Traffic Management.

As you continue to use Gloo Gateway, remember to periodically upgrade your installation, CRDs, and glooctl CLI to get the latest features and security updates.