Skip to main content

Envoy Versions

This is the single source of truth for how Elchi handles Envoy versions. Other pages that mention a specific Envoy version are illustrative; the authoritative, live list always comes from the archive described below.

Supported versions are fetched, not hardcoded​

Elchi does not ship a static list of supported Envoy versions. The controller fetches the current catalog at runtime from the release archive:

GET https://archive.elchi.io/index.json

The backend surfaces this to the UI through:

GET /api/v3/custom/available_versions

The handler proxies the archive's index.json verbatim. Envoy builds live under the top-level releases array; each release carries a version, a date, and per-architecture binaries entries with a download_url (pointing at the elchi-archive GitHub releases) and a sha256. Because the list is fetched on demand, new Envoy builds become available in Elchi as soon as they are published to the archive, with no backend release required.

{
  "releases": [
    {
      "version": "v1.39.0",
      "date": "…",
      "binaries": [
        {
          "arch": "linux-amd64",
          "download_url": "https://github.com/CloudNativeWorks/elchi-archive/releases/…",
          "sha256": "…"
        }
      ]
    }
  ],
  "elchi_client_releases": ["…"],
  "ui_releases": ["…"]
}
Always query the API for the real list

Any version number quoted in docs is a snapshot in time. To see what your platform can actually deploy right now, call GET /api/v3/custom/available_versions (or open the version picker in the UI). Do not treat a hardcoded number in prose as canonical.

Pinned control-plane baseline​

The management plane is built against a pinned versioned go-control-plane, which sets the Envoy API baseline the control-plane speaks. As of the current backend go.mod:

  • versioned-go-control-plane — v0.14.0-envoy1.39.0
  • versioned-go-control-plane/envoy — v1.39.0

That baseline is ~1.39. The supported deployable range currently spans roughly 1.35 – 1.39 — the archive lists what is actually available, and the pinned control-plane defines the newest API vocabulary the platform can emit. Older data-plane binaries in the range are configured against a compatible subset.

Everything is version-scoped​

A single logical object in Elchi exists per Envoy version. This is the core mental model — the same listener, WAF policy, or certificate is materialized independently for each version you run:

  • Resources — every xDS resource (listeners, clusters, routes, filters, extensions) is stored and rendered against a specific Envoy version. Editing "the" listener means editing its per-version instance.
  • WAF configurations — Coraza/CRS WAF configs are version-scoped; CRS rule sets are themselves versioned (e.g. GET /api/v3/waf/config?version=…, GET /api/v3/waf/crs/versions).
  • ACME certificates — issued certificate secrets are materialized per Envoy version so each running data-plane version has a matching secret.

Practically: when you introduce a new Envoy version, its resources/configs/certs are provisioned for that version; when you retire one, its version-scoped objects are cleaned up.

Upgrade and cleanup flows​

Adding a version, migrating resources onto it, and cleaning up a retired version are per-version operations. The backend exposes a resource upgrade path (POST /api/v3/resource/upgrade) and version cleanup (DELETE /api/v3/setting/maintenance/cleanup/versions/:version).

For the end-to-end walkthrough — how to add a new Envoy version, upgrade resources across versions, and safely retire an old one — see:

See also​