Repository navigation
docs(migrations): document xmc-profile upgrades after component cutover - #1606
Merged
Merged
Conversation
Add an "After Migration: Upgrading XMC" section to the component migration runbook: xmc-profile is a separate Helm release that gcluster and umbrella upgrades do not touch, and `migrate.py prepare` pins the gateway imageTag (and parameters.image when a custom gateway image is set), which takes precedence over the xmc-bridge default image. Replace the elided gcluster command in Step 3 with the exact create/deploy commands from INSTALL.md, and link the new section from INSTALL.md upgrade Step 6. TAG=agy CONV=5fd8cc79-e39e-4f23-8a80-e529a7076077
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for migrating legacy metrics workloads to XMC components. It adds explicit gcluster commands for standalone cluster toolkit deployments and introduces a new section detailing the post-migration upgrade process for the separate xmc-profile Helm release. A review comment suggests using the <IMAGE_TAG> placeholder in the upgrade instructions to maintain terminology consistency with INSTALL.md.
Comment link: #1606 (comment) TAG=agy CONV=5fd8cc79-e39e-4f23-8a80-e529a7076077
VLukiantsev
marked this pull request as ready for review
November 6, 2026 13:54
janzak-dev
previously approved these changes
Nov 6, 2026
Comment link: #1606 (comment) TAG=agy CONV=5fd8cc79-e39e-4f23-8a80-e529a7076077
There was a problem hiding this comment.
🤖 Incremental PR Approval
PR author is a code owner and changes since last approval (3 lines) are within the 50-line grace delta.
Preserving prior approval by @janzak-dev on commit 7518a38.
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.
Summary
Closes two happy-path gaps in the component migration runbook (
docs/migrations/components.md) ahead of0.18.0. It documents how to keepxmc-profileup to date after the cutover, and replaces the elidedgclustercommand in Step 3 with the exact commands.Motivation & Context
The migration targets existing installations on
0.18.x. After cutover, operators keep upgrading XMC, but nothing in the docs mentions that:xmc-profileis a separate Helm release. Neithergcluster deploynor an umbrellahelm upgradetouches it.migrate.py preparepins the gateway image that was running at migration time:components.ingestion-gateway.imageTag, plusparameters.imagewhen the umbrella setsingestion_gateway_custom_image, as Cluster Toolkit does. These pinned values take precedence over theDEFAULT_INGESTION_GATEWAY_IMAGEthatxmc-bridgewould otherwise use (ResolveImageprecedence). Without the new step, the gateway stays on the pre-migration image after later upgrades.Scope is deliberately limited to the happy path. Rollback variants and troubleshooting are left out on purpose: the migration has a very small set of existing installations, which will be supported directly, and new installations start with components enabled.
Key Changes
docs/migrations/components.md:enable_components: true, bump the pinned gateway image inprofile-values.yaml, then re-run the Step 4xmc-profileupgrade.gcluster create/gcluster deploy --only xmc_appcommands used inINSTALL.md.INSTALL.mdupgrade Step 6: links the new section.INSTALL.mdupgrade Step 4 (Option A, Cluster Toolkit): re-compile the blueprint (gcluster create … -w --force) beforegcluster deploy --only xmc_app. Without it,deployre-applies a stalectk-out/that lacks the newimage_tagand chart templates.Assumptions
--reset-then-reuse-values, deleting a key from the file does not clear the previously supplied value.Verification & Testing
./.githooks/pre-commit(docs-only; linters pass, affected tests skipped). CI: 17/17 checks green.Live Deployment & Manual Testing
dev_env.py gke-upgrade, built from this branch (code identical tomain). Includes the stability-contract, vizier/hpo profile and bridge RBAC changes merged since feat(migrations): add one-time component migration script and runbook #1461.verify_xmc.py: 17/17 pods Ready, services, routes, TLS and log monitor all ✅ PASS.gke-upgrade --no-enable-componentswith in-cluster Redpanda/ClickHouse metrics addons.ingestion-gateway-deployment3/3, HPA, and<release>-ingestion-gateway-network-policy.prepare:migrate.py prepare -n xmc -r <release> -o profile-values.yaml.parameters.imagewas pinned to the runningingestion_gateway_custom_image(...:latest) andimageTag: latest. This confirms the pinning the new "After Migration" section documents.handoff:migrate.py handoff -n xmc -r <release>.dev_env):gke-upgrade --enable-components --profile-values <abs-path> --only app.gcluster create … -w --force+gcluster deploy … --only xmc_app --auto-approvedocumented in Step 3, thenhelm upgrade --install --reset-then-reuse-values xmc-profile …. Gateway pods untouched until the bridge adopted the release.finalize:migrate.py finalize -n xmc -r <release>.redpanda,clickhouseandingestion-gatewayCOMPONENT_STATE_ENABLED(Ready/Synced);vizier/hpoDISABLED.xmc-cmp-ingestion-gatewayrev 1deployed, legacy NetworkPolicy replaced byingestion-gateway-network-policy,/readyzOK. The bridge adoption did a rolling update of the gateway pods (0 restarts).components.ingestion-gateway.parameters.imageinprofile-values.yamlto the digest form of the same image, then re-ran the documentedhelm upgrade --install --reset-then-reuse-values xmc-profile ….Componentspec and gateway Deployment image updated to the new reference,xmc-cmp-ingestion-gatewayrev 2deployed, rolling update completed,Ready/Synced,/readyzOK.Live Execution Output (Sanitized)
Related Issues / Bugs
N/A
TAG=agy
CONV=5fd8cc79-e39e-4f23-8a80-e529a7076077