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


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 Edge Enterprise.

  2. Get your Gloo Edge Enterprise license key. If you don’t have one already, you may request a trial license key here.

    You must provide the license key during the installation process. When you install Gloo Edge, a Kubernetes secret is created to store the license key. Note that each trial license key is typically valid for 30 days. When the license key expires, you can request a new license key by contacting your Account Representative or filling out this form. For more information, see Updating Enterprise Licenses.

  3. Install or upgrade glooctl with the following instructions.

Install the Gloo Edge command line tool (CLI)

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

Update glooctl CLI version

If you already installed glooctl, make sure to update glooctl to the same minor version as the version of Gloo Edge that is installed in your cluster. For example, if you’re using Gloo Edge 1.10.0, you should use a 1.10.0 release of glooctl.

You can use the glooctl upgrade command to set the --release that you want to use. You can use this 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 Edge across clusters that you manage from the same workstation.

glooctl upgrade --release v1.10.0

Verify that glooctl is installed

You can verify the glooctl CLI is installed and running the appropriate version.

glooctl version

In the output, the Client is your local version. The Server is the version that runs in your cluster, and is undefined if you did not install Gloo Edge yet!

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

Installing Gloo Edge on Kubernetes

Review the following steps to install Gloo Edge 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 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 -
gatewayProxies:
  gatewayProxy:
    service:
      type: NodePort
      httpPort: 31500
      httpsPort: 32500
      httpNodePort: 31500
      httpsNodePort: 32500
EOF
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 (https://helm.sh/docs/topics/charts_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 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 Edge, please be sure to verify your installation.


Customizing your installation with Helm

You can customize the Gloo Edge 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

Then, refer to the file during installation 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      10.0.180.15     <none>        443/TCP                     5m
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         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.


Uninstall

To uninstall Gloo Edge, you can use the glooctl CLI. If you installed Gloo Edge 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 Edge running, such as by running kubectl get pods --all-namespaces. If you remove the CRDs while Gloo Edge is still installed, you will experience errors.

glooctl uninstall --all

Uninstall with glooctl video


Next Steps

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

As you continue to use Gloo Edge, remember to periodically [upgrade]({{< versioned_link_path fromRoot=”/operations/upgrading/” >}}) your installation, CRDs, and glooctl CLI to get the latest features and security updates.