Navigation :

Installing Gloo Edge Enterprise

Review how to install Gloo Edge Enterprise.

Before you begin

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.
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.
Check whether glooctl, the Gloo Edge command line tool (CLI), is installed.
```
glooctl version
```
- If glooctl is not installed, install it.
- If glooctl is installed, update it to the latest 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.

macOS: You can use the Homebrew package manager.
```
brew install glooctl
```
Most platforms: You can use the following installation script, which requires Python to execute properly.
```
curl -sL https://run.solo.io/gloo/install | sh
export PATH=$HOME/.gloo/bin:$PATH
```

Windows: You can use the following installation script, which requires OpenSSL to execute properly.

(New-Object System.Net.WebClient).DownloadString("https://run.solo.io/gloo/windows/install") | iex
$env:Path += ";$env:userprofile/.gloo/bin/"

Direct download: You can download glooctl directly via the GitHub releases page.
1. In your browser, navigate to the Gloo project releases.
2. Choose the version to upgrade glooctl to. For Gloo Edge Enterprise, use 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.
3. Click the version of glooctl that you want to install.
4. In the Assets, download the glooctl package that matches your operating system, and follow your operating system procedures for replacing your existing glooctl binary file with the upgraded version.
5. After downloading, rename the executable to glooctl and add it to your system’s PATH.

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.

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>
```

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 Enterprise on Kubernetes

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

Installing on Kubernetes with `glooctl`

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

glooctl install gateway enterprise --license-key YOUR_LICENSE_KEY

For OpenShift clusters, make sure to include the --values values.yaml option to point to the Helm chart custom values file that you created.

Special Instructions to Install Gloo Edge Enterprise 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 enterprise --license-key YOUR_LICENSE_KEY --values -
gloo:
  gatewayProxies:
    gatewayProxy:
      service:
        type: NodePort
        httpPort: 31500
        httpsPort: 32500
        httpNodePort: 31500
        httpsNodePort: 32500
EOF

Creating namespace gloo-system... Done.
Starting Gloo Edge Enterprise installation...

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

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.

Installing on Kubernetes with Helm

This is the recommended method for installing Gloo Edge Enterprise to your production environment as it offers rich customization to the Gloo Edge control plane and the proxies Gloo Edge manages.

As a first step, you have to add the Gloo Edge repository to the list of known chart repositories:

helm repo add glooe https://storage.googleapis.com/gloo-ee-helm

Finally, install Gloo Edge using the following command:

helm install gloo glooe/gloo-ee --namespace gloo-system \
  --create-namespace --set-string license_key=YOUR_LICENSE_KEY

For OpenShift clusters, make sure to include the --values values.yaml option to point to the Helm chart custom values file that you created.

Using Helm 2 is not supported in Gloo Edge.

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

Airgap installation

You can install Gloo Edge Enterprise in an air-gapped environment, such as an on-premises datacenter, clusters that run on an intranet or private network only, or other disconnected environments.

Before you begin, make sure that you have the following setup:

A connected device that can pull the required images from the internet.
An air-gapped or disconnected device that you want to install Gloo Edge Enterprise in.
A private image registry such as Sonatype Nexus Repository or JFrog Artifactory that both the connected and disconnected devices can connect to.

To install Gloo Edge Enterprise in an air-gapped environment:

Set the Gloo Edge Enterprise version that you want to use as an environment variable, such as the latest version in the following example.
```
export GLOO_EE_VERSION=1.15.0
```

On the connected device, download the Gloo Edge Enterprise images.

helm template glooe/gloo-ee --version $GLOO_EE_VERSION | yq e '. | .. | select(has("image"))' - | grep image: | sed 's/image: //'

The example output includes the list of images.

quay.io/solo-io/gloo-fed-apiserver:1.15.0
quay.io/solo-io/gloo-federation-console:1.15.0
quay.io/solo-io/gloo-fed-apiserver-envoy:1.15.0
quay.io/solo-io/gloo-fed:1.15.0
quay.io/solo-io/gloo-ee:1.15.0
quay.io/solo-io/discovery-ee:1.15.0
quay.io/solo-io/gloo-ee-envoy-wrapper:1.15.0
"grafana/grafana:8.2.1"
"quay.io/coreos/kube-state-metrics:v1.9.7"
"jimmidyson/configmap-reload:v0.5.0"
"quay.io/prometheus/prometheus:v2.24.0"
docker.io/busybox:1.28
docker.io/redis:6.2.4
quay.io/solo-io/rate-limit-ee:1.15.0
quay.io/solo-io/extauth-ee:1.15.0
quay.io/solo-io/observability-ee:1.15.0
quay.io/solo-io/certgen:1.15.0
quay.io/solo-io/kubectl:1.22.9

Push the images from the connected device to a private registry that the disconnected device can pull from. For instructions and any credentials you must set up to complete this step, consult your registry provider, such as Nexus Repository Manager or JFrog Artifactory.
Optional: You might want to set up your private registry so that you can also pull the Helm charts. For instructions, consult your registry provider, such as Nexus Repository Manager or JFrog Artifactory.
When you install Gloo Edge Enterprise with a custom Helm chart values file, make sure to use the specific images that you downloaded and stored in your private registry in the previous steps.

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 glooe/gloo-ee --namespace gloo-system \
  -f value-overrides.yaml --create-namespace --set-string license_key=YOUR_LICENSE_KEY

Using Helm 2 is not supported in Gloo Edge.

List of Gloo Edge Helm chart values

The following table describes the most important enterprise-only values that you can override in your custom values file.

For more information, see the following resources:

Gloo Edge Open Source overrides (also available in Enterprise).
Advanced customization guide.
Enterprise Helm chart reference document.

Gloo Edge Open Source Helm values in Enterprise must be prefixed with gloo, unless they are the Gloo Edge settings, such as settings.<rest of helm value>.

Option	Type	Description
global.extensions.caching.enabled	bool	Deploy the caching server in the `gloo-system` namespace. Default is `false`.
global.extensions.extAuth.enabled	bool	Deploy the ext-auth server in the `gloo-system` namespace. Default is `true`.
global.extensions.extAuth.envoySidecar	bool	Deploy ext-auth in the `gateway-proxy` pod as a sidecar to Envoy. Communicates over a Unix domain socket instead of TCP. Default is `false`.
gloo.gatewayProxies.NAME.tcpKeepaliveTimeSeconds	unit32	The amount of time in seconds for connections to be idle before sending keep-alive probes. Defaults to 60s. You might use this to prevent sync issues due to network connectivity glitches. For more information, see the Knowledge Base help article.
gloo.gloo.disableLeaderElection	bool	Leave this field set to the default value of `false` when you have multiple replicas of the `gloo` deployment. This way, Gloo Edge elects a leader from the replicas, with the other replicas ready to become leader if needed in case the elected leader pod fails or restarts. If you want to run only one replica of `gloo`, you can set this value to `true`.
grafana.defaultInstallationEnabled	bool	Deploy Grafana in the `gloo-system` namespace. Default is `true`.
observability.enabled	bool	Deploy Grafana in the `gloo-system` namespace. Default is `true`.
observability.customGrafana.enabled	bool	Use your own Grafana instance instead of the default Gloo Edge Grafana instance. Default is `false`.
observability.customGrafana.username	string	Authenticate to your custom Grafana instance using this username for basic auth.
observability.customGrafana.password	string	Authenticate to your custom Grafana instance using this password basic auth.
observability.customGrafana.apiKey	string	Authenticate to your custom Grafana instance using this API key.
observability.customGrafana.url	string	The URL for your custom Grafana instance.
prometheus.enabled	bool	Deploy Prometheus in the `gloo-system` namespace. Default is `true`.
rateLimit.enabled	bool	Deploy the rate-limiting server in the `gloo-system` namespace. Default is `true`.

Enterprise UI

Gloo Edge Enterprise comes with a built-in UI that you can use to view information about your cluster and the Gloo Edge instance that you installed. You can enable the Gloo Edge Enterprise UI by using the gloo-fed.glooFedApiserver.enable=true setting during the installation.

glooctl install
helm install

echo "gloo-fed:
  glooFedApiserver:
    enable: true" > values.yaml
glooctl install gateway enterprise --values values.yaml --license-key=<LICENSE_KEY>

helm install gloo glooe/gloo-ee --namespace gloo-system --set gloo-fed.glooFedApiserver.enable=true --set license_key=<LICENSE_KEY>

Note that when you also enable Gloo Federation by using the gloo-fed.enabled=true setting, the UI does not show any federation data until you register one or more clusters.

Verify your Installation

Check that the Gloo Edge pods and services have been created. Depending on your install option, you may see some differences from the following example. And if you choose to install Gloo Edge into a different namespace than the default gloo-system, then you will need to query your chosen namespace instead.

kubectl --namespace gloo-system get all

NAME                                                          READY   STATUS    RESTARTS   AGE
pod/discovery-6dbb5fd8bc-gk2th                                1/1     Running   0          2m5s
pod/extauth-68bb4745fc-2rs7b                                  1/1     Running   0          2m5s
pod/gateway-proxy-7c49898fdf-blxps                            1/1     Running   0          2m5s
pod/gloo-7748b94989-dj85p                                     1/1     Running   0          2m5s
pod/gloo-fed-76c85d689b-q62k4                                 1/1     Running   0          2m5s
pod/gloo-fed-console-dd5f877bd-jgg8n                          3/3     Running   0          2m5s
pod/glooe-grafana-6f95948945-pvbcg                            1/1     Running   0          2m4s
pod/glooe-prometheus-kube-state-metrics-v2-6c79cc9554-hlhns   1/1     Running   0          2m5s
pod/glooe-prometheus-server-757dc7d8f7-x489q                  2/2     Running   0          2m5s
pod/observability-78cb7bddf7-kcrbm                            1/1     Running   0          2m5s
pod/rate-limit-5ddd4b69d-84d6b                                1/1     Running   0          2m5s
pod/redis-888f4d9b5-p76wk                                     1/1     Running   0          2m4s

NAME                                             TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)                                                AGE
service/extauth                                  ClusterIP      10.xxx.xx.xx    <none>          8083/TCP                                               2m6s
service/gateway-proxy                            LoadBalancer   10.xxx.xx.xx    34.xx.xxx.xxx   80:30437/TCP,443:31651/TCP                             2m6s
service/gloo                                     ClusterIP      10.xxx.xx.xx    <none>          9977/TCP,9976/TCP,9988/TCP,9966/TCP,9979/TCP,443/TCP   2m7s
service/gloo-fed-console                         ClusterIP      10.xxx.xx.xx    <none>          10101/TCP,8090/TCP,8081/TCP                            2m6s
service/glooe-grafana                            ClusterIP      10.xxx.xx.xxx   <none>          80/TCP                                                 2m6s
service/glooe-prometheus-kube-state-metrics-v2   ClusterIP      10.xxx.xx.xxx   <none>          8080/TCP                                               2m6s
service/glooe-prometheus-server                  ClusterIP      10.xxx.xx.xx    <none>          80/TCP                                                 2m7s
service/rate-limit                               ClusterIP      10.xxx.xx.xxx   <none>          18081/TCP                                              2m7s
service/redis                                    ClusterIP      10.xxx.xx.xx    <none>          6379/TCP                                               2m6s

NAME                                                     READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/discovery                                1/1     1            1           2m7s
deployment.apps/extauth                                  1/1     1            1           2m7s
deployment.apps/gateway-proxy                            1/1     1            1           2m7s
deployment.apps/gloo                                     1/1     1            1           2m7s
deployment.apps/gloo-fed                                 1/1     1            1           2m7s
deployment.apps/gloo-fed-console                         1/1     1            1           2m7s
deployment.apps/glooe-grafana                            1/1     1            1           2m7s
deployment.apps/glooe-prometheus-kube-state-metrics-v2   1/1     1            1           2m7s
deployment.apps/glooe-prometheus-server                  1/1     1            1           2m7s
deployment.apps/observability                            1/1     1            1           2m7s
deployment.apps/rate-limit                               1/1     1            1           2m7s
deployment.apps/redis                                    1/1     1            1           2m7s

NAME                                                                DESIRED   CURRENT   READY   AGE
replicaset.apps/discovery-6dbb5fd8bc                                1         1         1       2m6s
replicaset.apps/extauth-68bb4745fc                                  1         1         1       2m7s
replicaset.apps/gateway-proxy-7c49898fdf                            1         1         1       2m6s
replicaset.apps/gloo-7748b94989                                     1         1         1       2m7s
replicaset.apps/gloo-fed-76c85d689b                                 1         1         1       2m7s
replicaset.apps/gloo-fed-console-dd5f877bd                          1         1         1       2m6s
replicaset.apps/glooe-grafana-6f95948945                            1         1         1       2m6s
replicaset.apps/glooe-prometheus-kube-state-metrics-v2-6c79cc9554   1         1         1       2m6s
replicaset.apps/glooe-prometheus-server-757dc7d8f7                  1         1         1       2m6s
replicaset.apps/observability-78cb7bddf7                            1         1         1       2m7s
replicaset.apps/rate-limit-5ddd4b69d                                1         1         1       2m7s
replicaset.apps/redis-888f4d9b5                                     1         1         1       2m6s

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

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

Next Steps

After you install Gloo Edge, check out the User Guides.

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.