☰
Navigation :

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. Check whether glooctl, the Gloo Edge command line tool (CLI), is installed. 
    glooctl version

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

When it’s time to upgrade Gloo Edge, 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 Edge 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 Edge Enterprise, specify the Gloo Edge OSS version that corresponds to the Gloo Edge Enterprise version you want to upgrade to. To find the OSS version that corresponds to each Gloo Edge Enterprise release, see the Gloo Edge 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 Edge is not installed yet.

glooctl version

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, 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.

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-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 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 your installation, CRDs, and glooctl CLI to get the latest features and security updates.