docs: add the missing "Updating the bundled version of Istio" section - #5179
Open
dimitri-nicolo wants to merge 1 commit into
Open
docs: add the missing "Updating the bundled version of Istio" section#5179dimitri-nicolo wants to merge 1 commit into
dimitri-nicolo wants to merge 1 commit into
Conversation
The Makefile has pointed at this section since Istio was bundled: # To update the Istio version, see "Updating the bundled version of Istio" # in docs/common_tasks.md. but the section was never written. docs/common_tasks.md has the equivalent Envoy Gateway section and nothing for Istio, so the pointer has been dead on master and on every release branch back to release-v1.40. Writes the section, following the Envoy Gateway one, from the procedure as it actually works today: bump ISTIO_VERSION, delete the downloaded charts, re-run istio_charts, rebuild, and re-run the render tests. Two things worth having written down, both of which are easy to get wrong: - The chart tarballs are gitignored and never committed, so a stale copy left in pkg/render/istio silently keeps being used after a version bump. They have to be deleted, not just re-made. - The version has to stay in step with the Istio version the calico repo builds istio-pilot, istio-install-cni, istio-ztunnel and istio-proxyv2 from. The operator renders the upstream charts; calico builds the images those manifests reference. If they drift you get manifests from one Istio release pointing at images from another. The Makefile comment now says so too. Found by a review bot on a version-alignment PR against release-v1.42.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the previously-missing “Updating the bundled version of Istio” documentation so the Makefile’s pointer is no longer dead, and clarifies the Makefile comment to reflect the cross-repo version-alignment requirement with projectcalico/calico.
Changes:
- Expanded the
ISTIO_VERSIONMakefile comment to include the required version alignment context with Calico-built Istio images. - Added a new “Updating the bundled version of Istio” section to
docs/common_tasks.md, mirroring the existing Envoy Gateway procedure and capturing the chart-cleanup + rebuild/test workflow.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| Makefile | Clarifies the Istio update pointer and adds a warning about keeping versions aligned with Calico’s Istio image builds. |
| docs/common_tasks.md | Adds the missing Istio update procedure, including chart cleanup, rebuild, tests, and Calico repo coordination steps. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
dimitri-nicolo
added
docs-not-required
release-note-not-required
and removed
release-note-required
docs-pr-required
labels
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The
Makefilehas pointed at a doc section that was never written:# To update the Istio version, see "Updating the bundled version of Istio" in docs/common_tasks.md.docs/common_tasks.mdhas the equivalent Envoy Gateway section but nothing for Istio, so that pointer is dead — on master and on every release branch back to release-v1.40. Anyone following it to bump Istio finds nothing.This writes the section, following the Envoy Gateway one, from the procedure as it actually works today: bump
ISTIO_VERSION, delete the downloaded charts, re-runistio_charts, rebuild, re-run the render tests.Two things worth writing down
Both are easy to get wrong and neither is discoverable from the Makefile:
pkg/render/istiosilently keeps being used after a version bump —make istio_chartswon't re-fetch over an existing file. They have to be deleted, not just re-made. (The failure mode is worse than it sounds: you get a green build and green tests rendering the old Istio version.)projectcalico/calicobuilds the images those manifests point at (istio-pilot,istio-install-cni,istio-ztunnel,istio-proxyv2) underistio/andthird_party/istio-ztunnel/. If the two drift you get manifests from one Istio release referencing images built from another. The Makefile comment now says this too.Origin
Found by the review bot on #5177, a version-alignment PR against release-v1.42. The finding was valid but pre-existing and repo-wide, so it's fixed here at the source rather than in the release-branch PRs — those keep to version pins only, and this can be picked back if it's wanted on the release branches.
Docs-only; no code or generated files change.
Release Note