☰
Navigation :

1.7.0+ Upgrade Notice

In this guide we will describe the necessary steps to upgrade your Gloo Edge or Gloo Edge Enterprise deployments to their 1.7 versions using Helm. This guide also includes upgrade steps to Gloo Edge v1.6, as that is required as an intermediate step for upgrading to v1.7 from earlier versions without downtime. This is because Gloo Edge v1.6 supports both v2 and v3 of Envoy’s API in preparation of Envoy’s plan to drop support for V2 in 1.18 (i.e., Gloo 1.7). Gloo Edge v1.7 drops support for Envoy’s v2 API, so upgrading Gloo Edge to v1.7 requires a pit stop upgrade at v1.6 to transition from Envoy v2 to v3 and maintain a continuous uptime.

The guide assumes that you are running Gloo Edge 1.5.0+ or Gloo Edge Enterprise 1.5.0+. If you need to upgrade from earlier versions, you should consider an intermediate upgrade to the 1.5 versions. In this case, please refer to the 1.5.0 upgrade guide

This upgrade guide also assumes that was gloo installed via helm or with glooctl version 1.5.0+ (i.e., gloo is a helm release named “gloo”, which you can confirm exists by running helm ls --all-namespaces).

Also, please make sure to check out our general configuration recommendations to avoid downtime during upgrades.

Breaking Changes

Open Source

  1. in glooctl, the --with-admin-console flag was removed from installations, as the read-only UI as part of open source has been removed, in favor of the multi-cluster UI that ships with enterprise.

  2. the helm value gatewayProxies.gatewayProxy.tracing.provider is applied on the gateway instead of the gateway proxy config map. Therefore, the value needs to be of type v1.ListenerTracingSettings.

  3. In v1.7.19 the validationServerGrpcMaxSize was replaced by validationServerGrpcMaxSizeBytes in the settings CRD. If the new settings CRD is not applied, you will see the following type of error:

    • Error: UPGRADE FAILED: error validating "": error validating data: ValidationError(Settings.spec.gateway.validation): unknown field "validationServerGrpcMaxSizeBytes" in io.solo.gloo.v1.Settings.spec.gateway.validation
    • To apply the new settings CRD: 
      helm pull gloo/gloo --version 1.7.19 --untar
kubectl apply -f gloo/crds/gloo.solo.io_v1_Settings.yaml
Enterprise

  1. The Gloo UI has been replaced by the Gloo-Fed UI, which is a multicluster version of the UI (that is read-only). This UI is deployed in the gloo-fed namespace, and to open it with glooctl ui you will need to upgrade your glooctl version.

  2. Some helm values changed as part of consolidating the open source and enterprise charts. In particular, all ratelimit helm values live under global.extensions.rateLimit rather than rateLimit. In addition, any settings helm values now live under gloo.settings (in the subchart) rather than top-level in settings.

The helm values under apiServer have been removed and now are under glooFedApiserver. For example apiServer.enable is now glooFedApiserver.enable.

The following helm values are no longer supported by glooFedApiserver:

Upgrade prerequisites

You will need to have the following command line utilities installed:

Setup

Install Gloo Edge or Gloo Edge Enterprise v1.5.

helm upgrade gloo gloo/gloo --namespace gloo-system --version 1.5.0 --install --create-namespace

helm upgrade gloo glooe/gloo-ee --namespace gloo-system --version 1.5.0 --set license_key=YOUR_LICENSE_KEY --install --create-namespace

Adding Optional Upstream for Downtime Testing

If you wish to test downtime using hey, add an upstream for hey to ping. You'll need to apply some yaml for the 'with downtime check' commands to work in subsequent sections. Click to expand.

First add the upstream.

apiVersion: gloo.solo.io/v1
kind: Upstream
metadata:
  name: json-upstream
  namespace: gloo-system
spec:
  static:
    hosts:
      - addr: jsonplaceholder.typicode.com
        port: 80

Then make it routable:

apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: test-prefix
  namespace: gloo-system
spec:
  virtualHost:
    routes:
      - matchers:
         - prefix: /posts
        routeAction:
          single:
            upstream:
              name: json-upstream
              namespace: gloo-system
        options:
          autoHostRewrite: true

To ensure that the the upstream works, wait until the following returns:

curl $(glooctl proxy url)/posts

  ... # omitted for brevity, this will be at the end of a long output
  {
    "userId": 10,
    "id": 100,
    "title": "at nam consequatur ea labore ea harum",
    "body": "cupiditate quo est a modi nesciunt soluta\nipsa voluptas error itaque dicta in\nautem qui minus magnam et distinctio eum\naccusamus ratione error aut"
  }
]

Upgrading the Gloo Edge deployment to v1.6

Run whichever upgrade command is appropriate for your setup:

helm upgrade gloo gloo/gloo --namespace gloo-system --version 1.6.0

hey -n 6000 -c 10 -q 10 $(glooctl proxy url)/posts & helm upgrade gloo gloo/gloo --namespace gloo-system --version 1.6.0 --set gatewayProxies.gatewayProxy.podTemplate.probes=true

helm upgrade gloo glooe/gloo-ee --namespace gloo-system --version 1.6.0 --set license_key=YOUR_LICENSE_KEY

hey -n 6000 -c 10 -q 10 $(glooctl proxy url)/posts & helm upgrade gloo glooe/gloo-ee --namespace gloo-system --version 1.6.0 --set license_key=YOUR_LICENSE_KEY --set gatewayProxies.gatewayProxy.podTemplate.probes=true

Verify v1.6 upgrade

If you chose to run hey alongside the upgrade command for a downtime check, then the hey command will spend a minute pinging gloo before printing diagnostic data like this:

Click for example hey output 
Summary:
  Total:	66.9389 secs
  Slowest:	1.3237 secs
  Fastest:	0.0241 secs
  Average:	0.0649 secs
  Requests/sec:	89.6340
  

Response time histogram:
  0.024 [1]	|
  0.154 [5677]	|■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  0.284 [195]	|■
  0.414 [44]	|
  0.544 [44]	|
  0.674 [11]	|
  0.804 [6]	|
  0.934 [5]	|
  1.064 [2]	|
  1.194 [2]	|
  1.324 [3]	|


Latency distribution:
  10% in 0.0324 secs
  25% in 0.0367 secs
  50% in 0.0433 secs
  75% in 0.0603 secs
  90% in 0.1087 secs
  95% in 0.1601 secs
  99% in 0.4220 secs

Details (average, fastest, slowest):
  DNS+dialup:	0.0000 secs, 0.0241 secs, 1.3237 secs
  DNS-lookup:	0.0000 secs, 0.0000 secs, 0.0000 secs
  req write:	0.0000 secs, 0.0000 secs, 0.0006 secs
  resp wait:	0.0631 secs, 0.0229 secs, 1.3220 secs
  resp read:	0.0016 secs, 0.0002 secs, 0.0783 secs

Status code distribution:
  [200]	6000 responses

You should expect less than 20 errors at most, and a healthy response time histogram that’s mostly under .25 seconds.

Next, let’s verify that gloo was actually upgraded as expected by checking the installed version:

glooctl version

You should see the expected version for all the server components.

Let’s also check that your Gloo Edge installation is healthy by running:

glooctl check

If everything has gone smoothly, it will state that all the deployments are ok and that no problems were detected.

Manually Transition from v2 to v3.

Gloo Edge’s default helm configurations for v1.6 and v1.7 will smoothly transistion from v2 to v3. However, if you have manually edited any bootstrap configurations, you may need to remove v2 references yourself by removing the following config value wherever it is has been added:

envoy.reloadable_features.enable_deprecated_v2_api: true

See Envoy’s documentation for more info.

Upgrading the Gloo Edge deployment to v1.7

Once you’ve installed gloo v1.6, you should be able to upgrade to v1.7 without downtime by following similar steps to the previous upgrade.

helm upgrade gloo gloo/gloo --namespace gloo-system --version 1.7.0

hey -n 6000 -c 10 -q 10 $(glooctl proxy url)/posts & helm upgrade gloo gloo/gloo --namespace gloo-system --version 1.7.0 --set gatewayProxies.gatewayProxy.podTemplate.probes=true

helm upgrade gloo glooe/gloo-ee --namespace gloo-system --version 1.7.0 --set license_key=YOUR_LICENSE_KEY

hey -n 6000 -c 10 -q 10 $(glooctl proxy url)/posts & helm upgrade gloo glooe/gloo-ee --namespace gloo-system --version 1.7.0 --set license_key=YOUR_LICENSE_KEY --set gatewayProxies.gatewayProxy.podTemplate.probes=true

Verify v1.7 upgrade

Verify the upgrade as before with glooctl and hey. If you once again see no issues, then the upgrade is complete!