how to upgrade enclave#294
Conversation
WalkthroughAdds a new docs page, ChangesDocumentation Addition
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Tarball created: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/UPGRADE.md (1)
11-11: Clarify the phrasing for better readability.The phrase "artifact as-is" is awkward and unclear. Consider rephrasing for clarity.
📝 Suggested rephrasing
-The tarball contains all version definitions in `defaults/*.yaml` files and is the artifact as-is—a complete, tested release. +The tarball contains all version definitions in `defaults/*.yaml` files and is a self-contained, tested release.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/UPGRADE.md` at line 11, The sentence "The tarball contains all version definitions in `defaults/*.yaml` files and is the artifact as-is—a complete, tested release." is awkward; update that sentence in UPGRADE.md to clearer phrasing such as "The tarball contains all version definitions in `defaults/*.yaml` files and is provided as a complete, tested release." Replace the exact original sentence with the new wording to improve readability while keeping the meaning intact.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/UPGRADE.md`:
- Line 18: The step title "Sync/Mirror new content" and its description "sync
process" have inconsistent capitalization; update the description so it matches
the title capitalization by changing "sync process" to "Sync process" (or
alternatively make both the title and description lowercase if you prefer
sentence case) — locate the text strings "Sync/Mirror new content" and "sync
process" and make the capitalization consistent.
- Line 46: The line "Update operators to versions in tarball" is missing an
article; replace that phrase with either "Update operators to the versions in
the tarball" or "Update operators to versions specified in the tarball" (update
the text fragment "Update operators to versions in tarball" accordingly) to
correct the grammar.
- Line 25: The sentence "**Important**: Components must be upgraded in
order—tarball first, then sync content, then cluster, then operators." is
ambiguous about whether the "Validation" step (referenced earlier in steps
15-21) is mandatory; update that line to explicitly state whether Validation is
part of the required upgrade sequence or is an optional post-upgrade
verification step—either append ", then validation" to include it in the
required order or add a clarifying clause like "Validation is a recommended
post-upgrade verification step and is not required in the strict upgrade
sequence." Reference the existing phrasing exactly when making the edit so
reviewers can see the intent is clarified.
---
Nitpick comments:
In `@docs/UPGRADE.md`:
- Line 11: The sentence "The tarball contains all version definitions in
`defaults/*.yaml` files and is the artifact as-is—a complete, tested release."
is awkward; update that sentence in UPGRADE.md to clearer phrasing such as "The
tarball contains all version definitions in `defaults/*.yaml` files and is
provided as a complete, tested release." Replace the exact original sentence
with the new wording to improve readability while keeping the meaning intact.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
|
We may also need to cover the upgrade of the LZ pieces: packages and units deployed there (quay, metal3 stack, etc) |
added in eb58f93 |
|
Tarball created: |
rporres
left a comment
rporres
left a comment
There was a problem hiding this comment.
This is a starting point of the process.
|
another point to add: how to upgrade plugins? |
|
Another point (CC @danielerez ), if we update the pinned image set when installing, we need to also check what to do when upgrading. |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/UPGRADE.md`:
- Around line 30-56: Add a new "Upgrade plugins" step into the Upgrade Steps
sequence (suggested between steps 6 and 7) that explains: where to find plugin
version information in the release defaults (reference defaults/*.yaml), how to
back up/merge site overrides in config/*.yaml, how to construct the plugin
payload (e.g., PLUGINS=$(cat defaults/plugins.yaml | yq -c .plugins)) and run
the orchestration command (e.g., enclave-reconcile plugin-versions --plugins
$PLUGINS), and include a short compatibility checklist (verify
operator/OpenShift versions from defaults/*.yaml and any breaking changes) plus
rollback guidance if plugin upgrade fails. Ensure the step names and example
command use the existing enclave-reconcile symbol and a PLUGINS variable so
reviewers can locate and standardize the implementation.
- Line 20: The docs currently list "Upgrade Landing Zone components" as step 3
but give no concrete actions; update the UPGRADE.md to either add explicit
upgrade steps for the Landing Zone or explain why extraction is sufficient: add
commands and notes for upgrading mirror-registry, metal3 stack, packages, and
binaries (e.g., pull/new images, apply manifests, helm/oc commands used to
upgrade each component) under the "Upgrade Landing Zone components" section or
add a short justification that extracting the tarball already contains and
applies those upgrades; reference the existing "Extract tarball" step and ensure
the new text maps each LZ component to the exact action/command required so
readers can follow the same explicit pattern used for cluster/operator upgrades.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
|
|
||
| 1. **Deploy new Enclave tarball** - Extract new release to Landing Zone, preserving your `config/*.yaml` customizations | ||
| 2. **Sync/Mirror new content** - Run sync process to download and mirror new OpenShift and operator images to local registry (disconnected mode) | ||
| 3. **Upgrade Landing Zone components** - Update components to the versions specified in the new tarball |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for Landing Zone upgrade documentation or procedures
rg -n -i -C3 'landing.zone.*(upgrade|update)|(upgrade|update).*landing.zone|metal3.*(upgrade|update)|mirror-registry.*(upgrade|update)' --type=mdRepository: rh-ecosystem-edge/enclave
Length of output: 1179
🏁 Script executed:
cat -n docs/UPGRADE.md | sed -n '35,65p'Repository: rh-ecosystem-edge/enclave
Length of output: 1661
Missing explicit steps for Landing Zone component upgrades.
The high-level overview (line 20) explicitly lists "Upgrade Landing Zone components" as step 3, but the detailed checklist (lines 40-55) lacks corresponding action items. While "Extract tarball" (step 3) deploys to the Landing Zone, it doesn't clarify what specific component upgrades are required (mirror-registry, metal3 stack, packages, binaries) or how to perform them. In contrast, cluster and operator upgrades (steps 7-8) include explicit commands. Add either explicit upgrade procedures for LZ components or clarify why extraction is sufficient.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/UPGRADE.md` at line 20, The docs currently list "Upgrade Landing Zone
components" as step 3 but give no concrete actions; update the UPGRADE.md to
either add explicit upgrade steps for the Landing Zone or explain why extraction
is sufficient: add commands and notes for upgrading mirror-registry, metal3
stack, packages, and binaries (e.g., pull/new images, apply manifests, helm/oc
commands used to upgrade each component) under the "Upgrade Landing Zone
components" section or add a short justification that extracting the tarball
already contains and applies those upgrades; reference the existing "Extract
tarball" step and ensure the new text maps each LZ component to the exact
action/command required so readers can follow the same explicit pattern used for
cluster/operator upgrades.
| ## Upgrading to a New Enclave Release | ||
|
|
||
| Each Enclave tarball release includes: | ||
| - Automation code (playbooks, scripts) | ||
| - Tested version matrix (OpenShift, operators, control binaries) in `defaults/*.yaml` | ||
| - Bug fixes and new features | ||
| - Updated documentation | ||
|
|
||
| ### Upgrade Steps | ||
|
|
||
| 1. **Obtain new tarball** - Download the new Enclave release tarball | ||
| 2. **Backup configurations** - Save your `config/*.yaml` files (these contain your site-specific settings) | ||
| 3. **Extract tarball** - Deploy to Landing Zone, replacing automation and defaults | ||
| 4. **Restore configurations** - Copy your `config/*.yaml` files back (or merge if needed) | ||
| 5. **Validate configuration** - Ensure your configs are compatible with new release | ||
| 6. **Sync content** - Run sync process to mirror new versions (disconnected mode) | ||
| 7. **Upgrade management cluster** - Update OpenShift to the version in the tarball: | ||
| ```sh | ||
| $ VERSION=$(cat defaults/platforms.yaml | yq -c .mgmt_openshift_version) | ||
| $ enclave-reconcile mgmt-cluster-version $VERSION | ||
| ``` | ||
| 8. **Upgrade operators** - Update operators to the versions in the tarball: | ||
| ```sh | ||
| $ OPERATORS=$(cat defaults/operators.yaml | yq -c .operators) | ||
| $ enclave-reconcile operator-versions --operators $OPERATORS | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Missing documentation for plugins upgrade.
The detailed upgrade checklist does not include steps for upgrading plugins, which was specifically requested in the PR comments by maorfr. Consider adding a step that covers plugin upgrade procedures, including how to update plugin versions and any compatibility considerations.
Would you like me to help draft a plugins upgrade step? I can propose where it should fit in the sequence and what information to include.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 48-48: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 49-49: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 53-53: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 54-54: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/UPGRADE.md` around lines 30 - 56, Add a new "Upgrade plugins" step into
the Upgrade Steps sequence (suggested between steps 6 and 7) that explains:
where to find plugin version information in the release defaults (reference
defaults/*.yaml), how to back up/merge site overrides in config/*.yaml, how to
construct the plugin payload (e.g., PLUGINS=$(cat defaults/plugins.yaml | yq -c
.plugins)) and run the orchestration command (e.g., enclave-reconcile
plugin-versions --plugins $PLUGINS), and include a short compatibility checklist
(verify operator/OpenShift versions from defaults/*.yaml and any breaking
changes) plus rollback guidance if plugin upgrade fails. Ensure the step names
and example command use the existing enclave-reconcile symbol and a PLUGINS
variable so reviewers can locate and standardize the implementation.
| 7. **Upgrade management cluster** - Update OpenShift to the version in the tarball: | ||
| ```sh | ||
| $ VERSION=$(cat defaults/platforms.yaml | yq -c .mgmt_openshift_version) | ||
| $ enclave-reconcile mgmt-cluster-version $VERSION |
There was a problem hiding this comment.
Why do we need customers to specify the version to upgrade into? It should be as simple as "upgrade into the latest" - and under the hood the script should check what is the definition of "latest", by introspecting defaults/platforms.yaml.
Given we say that each version is pre-validated and pre-configured with specific versions, we should not add another complexity for the end users - at least the default bahavior should be that they do not need to specify version.
| 8. **Upgrade operators** - Update operators to the versions in the tarball: | ||
| ```sh | ||
| $ OPERATORS=$(cat defaults/operators.yaml | yq -c .operators) | ||
| $ enclave-reconcile operator-versions --operators $OPERATORS |
There was a problem hiding this comment.
same comment as for the OCP version - the end user should not be asked to specify which oeprators/versions to upgrade, at least not by default
| 7. **Upgrade management cluster** - Update OpenShift to the version in the tarball: | ||
| ```sh | ||
| $ VERSION=$(cat defaults/platforms.yaml | yq -c .mgmt_openshift_version) | ||
| $ enclave-reconcile mgmt-cluster-version $VERSION |
There was a problem hiding this comment.
I also would question the name of the tool - enclave-reconcile does not mean a lot.
|
|
||
| 1. **Deploy new Enclave tarball** - Extract new release to Landing Zone, preserving your `config/*.yaml` customizations | ||
| 2. **Sync/Mirror new content** - Run sync process to download and mirror new OpenShift and operator images to local registry (disconnected mode) | ||
| 3. **Upgrade Landing Zone components** - Update components to the versions specified in the new tarball |
There was a problem hiding this comment.
I might be missing, but what is the procedure of upgrading Landing Zone components please? It seems that enclave-reconcile updated control plane OCP/operators only...
5 participants
this PR adds documentation on how to upgrade enclave
markdown preview: https://github.com/rh-ecosystem-edge/enclave/blob/upgrade-docs/docs/UPGRADE.md
enclave-reconcile references:
Summary by CodeRabbit
Release Notes