Installing Gloo Edge on Kubernetes

Gloo Edge can be installed on a Kubernetes cluster by using either the glooctl command line tool or a Helm chart. The following document will take you through the process of either installation, verifying the installation, and how to remove Gloo Edge if necessary.

Minimum required Kubernetes is 1.11.x. For older versions see our release support guide

Installing the Gloo Edge on Kubernetes

These directions assume you’ve prepared your Kubernetes cluster appropriately. Full details on setting up your Kubernetes cluster here.

For certain providers with more strict multi-tenant security, like OpenShift, be sure to follow the cluster set up accordingly.

Install command line tool (CLI)

The glooctl command line provides useful functions to install, configure, and debug Gloo Edge, though it is not required to use Gloo Edge.

You can verify the glooctl CLI is installed and running correctly by executing the command:

glooctl version

The command returns your client version and a missing server version (we have not installed Gloo Edge yet!):

Client: {"version":"1.2.3"}
Server: version undefined, could not find any version of gloo running

Update glooctl CLI version

You should always try to use the same minor glooctl version as the version of Gloo Edge installed in your cluster, i.e., if you’re using Gloo Edge 1.6.x, you should use a 1.6.x release of glooctl.

Fortunately, glooctl is able to update itself to different versions. To change the version of glooctl you currently have installed, you can run:

glooctl upgrade --release v1.6.0

Note: The glooctl upgrade command can also be used to roll back your glooctl version to previous releases. This can be convenient if you are using an older version of Gloo Edge and want to use the same verison of glooctl to ensure compatability.

Installing on Kubernetes with glooctl

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

glooctl install gateway
Special Instructions to Install Gloo Edge 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 Edge to publish those same ports from the proxy as well.
cat <<EOF | glooctl install gateway --values -
      type: NodePort
      httpPort: 31500
      httpsPort: 32500
      httpNodePort: 31500
      httpsNodePort: 32500
Creating namespace gloo-system... Done.
Starting Gloo Edge installation...

Gloo Edge was successfully installed!

Note also that the url to invoke services published via Gloo Edge will be slightly different with Kind-hosted clusters. Much of the Gloo Edge 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 Edge, 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 Edge 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 Edge v1.8.0.

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

helm repo add gloo
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 Edge, please be sure to verify your installation.

Customizing your installation with Helm

You can customize the Gloo Edge installation by providing your own value file.

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

    # do not create kubernetes rbac resources
    create: false
  # configure gloo to write generated custom resources to a custom namespace
  writeNamespace: my-custom-namespace

and use it to override default values in the Gloo Edge Helm chart:

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

List of Gloo Edge 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 Edge 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 Edge 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-5689fd59d7-wsg7f        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         ClusterIP     <none>        443/TCP                     5m
service/gateway-proxy   LoadBalancer   <pending>     80:30221/TCP,443:32340/TCP  5m
service/gloo            ClusterIP   <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         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-5689fd59d7        1         1         1         5m
replicaset.apps/gateway-proxy-9d79d48cd   1         1         1         5m
replicaset.apps/gloo-5b7b748dbf           1         1         1         5m

NAME                        COMPLETIONS   DURATION   AGE
job.batch/gateway-certgen   1/1           14s        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.


It’s so hard to say goodbye. Actually, in this case it’s not.

Uninstall with glooctl

To uninstall Gloo Edge simply run the following.

glooctl uninstall

If you installed Gloo Edge to a different namespace, you will have to specify that namespace using the -n option:

glooctl uninstall -n my-namespace

The gloo-system namespace and Custom Resource Definitions created by the glooctl install command will not be removed. Those can also be deleted by running the following commands. Proceed with caution and only remove the CRDs if there are no more instances of Gloo Edge in the cluster.

glooctl uninstall --all

Next Steps

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