Docsright arrowEdge Stackright arrowUpgrade Ambassador Edge Stack 2.5.Z to Ambassador Edge Stack 3.6.0 (YAML)

5 min • read

Upgrade Ambassador Edge Stack 2.5.Z to Ambassador Edge Stack 3.6.0 (YAML)

Since Ambassador Edge Stack's configuration is entirely stored in Kubernetes resources, upgrading between versions is straightforward.

Ambassador Edge Stack 3 is functionally compatible with Ambassador Edge Stack 2.x, but with any major upgrade there are some changes to consider. Such as, Envoy removing support for V2 Transport Protocol features. Below we will outline some of these changes and things to consider when upgrading.

Resources to check before migrating to 3.6.0.

Ambassador Edge Stack 3.X has been upgraded from Envoy 1.17.X to Envoy 1.24.1. Envoy has removed support for the Envoy V2 Transport Protocol and it is no longer valid. This means all AuthService, RatelimitService, LogServices, and External Filters must be updated to use the V3 Protocol. Additionally, support for some of the runtime bootstrap flags has been removed.

You can refer to the Major changes in Ambassador Edge Stack 3.x guide for an overview of the changes. Here are a few items that need to be checked or addressed before upgrading:

  1. Check Transport Protocol usage on all resources before migrating.

    The AuthService, RatelimitService, LogServices, and External Filters that use the grpc protocol will now need to explicilty set protocol_version: "v3". If not set or set to v2 then an error will be posted and a static response will be returned.

    protocol_version should be updated to v3 for all of the above resources while still running Ambassador Edge Stack 2.5.1. As of version 2.3.z+, support for protocol_version v2 and v3 is supported in order to allow migration from protocol_version v2 to v3 before upgrading to Ambassador Edge Stack 3.6.0 where support for v2 is removed.

    Upgrading any application code for your own implementations of these services is very straightforward.

    The following imports simply need to be updated to switch from Envoy's Transport Protocol v2 to v3, and then the configuration for these resources can be updated to add the protocl_version: "v3" when the updated service is deployed.

    v2 Imports:

    v3 Imports:

  2. Check removed runtime flags for behavior changes that may affect you:

  3. Support for LightStep tracing driver removed

Ambassador Edge Stack 3.4 is based on Envoy 1.24.1 which removed support for the LightStep tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.

Migration Steps

Migration is a two-step process:

  1. Install new CRDs.

    After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions in previous version of Ambassador Edge Stack and does not require the complex migration steps that the migration from 1.x tto 2.x required.

    Before installing Ambassador Edge Stack 3.6.0 itself, you need to update the CRDs in your cluster. This is mandatory during any upgrade of Ambassador Edge Stack.

  2. Install Ambassador Edge Stack 3.6.0.

    After installing the new CRDs, upgrade Ambassador Edge Stack 3.6.0: