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.
- If
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.- In your browser, navigate to the Gloo project releases.
- 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. - Click the version of
glooctl
that you want to install. - In the Assets, download the
glooctl
package that matches your operating system, and follow your operating system procedures for replacing your existingglooctl
binary file with the upgraded version. - After downloading, rename the executable to
glooctl
and add it to your system’sPATH
.
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.
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, andglooctl
CLI to get the latest features and security updates.