-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Updates to upgrade procedures #65388
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Updates to upgrade procedures #65388
Conversation
1c2d647 to
f065605
Compare
|
Issues go stale after 90d of inactivity. Mark the issue as fresh by commenting If this issue is safe to close now please do so with /lifecycle stale |
|
Stale issues rot after 30d of inactivity. Mark the issue as fresh by commenting If this issue is safe to close now please do so with /lifecycle rotten |
|
Rotten issues close after 30d of inactivity. Reopen the issue by commenting /close |
|
@openshift-bot: Closed this PR. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
|
/reopen |
|
@kcarmichael08: Reopened this PR. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
f065605 to
f4f277d
Compare
3e9a121 to
f09025c
Compare
msugakov
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Partial review. Need to allocate more time to complete going through this change.
msugakov
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another partial review.
|
I think I have everyone's suggestions incorporated, except for a 4.5 version (which I will wait to create until after we get this one completed). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hopefully the last round of comments from me. I hope my suggestions don't contradict the earlier ones, otherwise please let me know 😸. Approving as I think it's mergeable after addressing these.
| When upgrading from earlier releases, follow this guidance: | ||
|
|
||
| * If the release for Central is earlier than 3.74, you must upgrade to the latest 3.74 patch before upgrading to a 4.x release. See the link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_security_for_kubernetes/3.74/html/upgrading/index[upgrade documentation for version 3.74] for information about upgrades from earlier versions to 3.74. | ||
| * When upgrading Helm-based installations from release 3.74, you can upgrade to any latest patch of {product-title-short} version 4.0 through 4.4. However, for full functionality, upgrade to release 4.4. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[no-op for now] I hope this will not become
- When upgrading Helm-based installations from release 3.74, you can upgrade to any latest patch of {product-title-short} version 4.0 through 4.4. However, for full functionality, upgrade to release 4.5.
in 4.5 release because this is exactly the thing we don't want. They must do in two steps: from 3.74 to 4.0...4.4, from 4.0...4.4 to 4.5+ and we should communicate that clearly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Created https://issues.redhat.com/browse/ROX-24162 for 4.5+
upgrading/upgrade-roxctl.adoc
Outdated
| * You need to perform the manual upgrade procedure only if you used the `roxctl` CLI to install {product-title-short}. | ||
| * For upgrading to {product-title-short} 4.0, you must be using the latest patch release of {product-title-short} 3.74. If you are using an older version, you must first upgrade to {product-title-short} 3.74 before upgrading to {product-title-short} 4.0. | ||
| * There are manual steps for each version upgrade that must be followed, for example, from version 3.74 to version 4.0, and from version 4.0 to version 4.1. Therefore, Red{nbsp}Hat recommends upgrading first from 3.74 to 4.0, then from 4.0 to 4.1, then 4.1 to 4.2, until the selected version is installed. | ||
| * For manifest-based (roxctl) Central deployments, you can upgrade to any latest patch of {product-title-short} version 4.0 through 4.4. However, for full functionality, upgrade to version 4.4. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm realizing the last bullet point is now redundant and perhaps even confusing given the previous one which suggests to upgrade one minor version at a time, which achieves the same result. I suggest deleting it.
| * For manifest-based (roxctl) Central deployments, you can upgrade to any latest patch of {product-title-short} version 4.0 through 4.4. However, for full functionality, upgrade to version 4.4. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think originally it was meant to advise people to always upgrade to the latest version to get the latest features, but I think that's implicit anyway, so I'll delete.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
took your suggestion in the next comment - so this is fixed
upgrading/upgrade-roxctl.adoc
Outdated
| ==== | ||
| * You need to perform the manual upgrade procedure only if you used the `roxctl` CLI to install {product-title-short}. | ||
| * For upgrading to {product-title-short} 4.0, you must be using the latest patch release of {product-title-short} 3.74. If you are using an older version, you must first upgrade to {product-title-short} 3.74 before upgrading to {product-title-short} 4.0. | ||
| * There are manual steps for each version upgrade that must be followed, for example, from version 3.74 to version 4.0, and from version 4.0 to version 4.1. Therefore, Red{nbsp}Hat recommends upgrading first from 3.74 to 4.0, then from 4.0 to 4.1, then 4.1 to 4.2, until the selected version is installed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Optional suggestion:
| * There are manual steps for each version upgrade that must be followed, for example, from version 3.74 to version 4.0, and from version 4.0 to version 4.1. Therefore, Red{nbsp}Hat recommends upgrading first from 3.74 to 4.0, then from 4.0 to 4.1, then 4.1 to 4.2, until the selected version is installed. | |
| * There are manual steps for each version upgrade that must be followed, for example, from version 3.74 to version 4.0, and from version 4.0 to version 4.1. Therefore, Red{nbsp}Hat recommends upgrading first from 3.74 to 4.0, then from 4.0 to 4.1, then 4.1 to 4.2, and so on until the selected version is installed. For full functionality, Red{nbsp}Hat recommends upgrading to the most recent version. |
8fb7061 to
d6718a3
Compare
d6718a3 to
0022280
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Made some comments and suggestions. Re-label or progress to merge review when ready! 👍
| + | ||
| If you select manual updates, when a newer version of the Operator is available, OLM creates an update request. As a cluster administrator, you must manually approve the update request to update the Operator to the latest version. | ||
| + | ||
| Red{nbsp}Hat recommends enabling automatic upgrades for Operator in {product-title-managed-short}. See the link:https://access.redhat.com/articles/7045053[Red Hat Advanced Cluster Security for Kubernetes Support Matrix] for more information. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Haven't seen Red{nbsp}Hat before. Is there a reason for formatting it like this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| * If you are upgrading from version 3.74, verify that you are running the latest patch release version of the {product-title-short} Operator 3.74. | ||
| * Backup your existing Central database. | ||
| * If the cluster you are upgrading contains the `SecuredCluster` custom resource (CR), change the collection method to `EBPF` or `CORE_BPF`. | ||
| * If the cluster you are upgrading contains the `SecuredCluster` custom resource (CR), change the collection method to EBPF or CORE_BPF. See "Changing the collection method" in the next section. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| :_mod-docs-content-type: PROCEDURE | ||
| [id="remove-central-attached-pv-operator_{context}"] | ||
| = Remove Central-attached PV using the {product-title-short} Operator | ||
| = Remove Central-attached PV using the {product-title-short} Operator (version 4.1 and later) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ideally, this would be rewritten to exclude the parens. I don't think this is a total prohibition on it, but ISG generally allows them only as a last resort.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It makes for a long heading but I rewrote.
| :_mod-docs-content-type: PROCEDURE | ||
| [id="remove-central-attached-pv-operator_{context}"] | ||
| = Remove Central-attached PV using the {product-title-short} Operator | ||
| = Remove Central-attached PV using the {product-title-short} Operator (version 4.1 and later) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Procedure titles should be gerund phrases per mod docs guidance.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That was existing content, which I was generally trying to avoid restructuring. I was just asked to specify the version info.
| :_mod-docs-content-type: CONCEPT | ||
| [id="remove-central-attached-pv-overview_{context}"] | ||
| = Remove Central-attached PV | ||
| = Remove Central-attached PV after upgrading to version 4.1 and later |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Gerund phrase.
| The PV has data and persistent files used by earlier {product-title-short} versions. You can use the PV to roll back to an earlier version before {product-title-short} 4.1. Or, if you have a large RocksDB backup bundle for Central, you can use the PV to restore that data. | ||
|
|
||
| If you do not plan to roll back or restore from earlier RocksDB backups, you can remove the Central-attached persistent volume claim (PVC) to free up the storage. | ||
| After completing the upgrade to 4.1, you can remove the Central-attached persistent volume claim (PVC) to free up the storage if you do not plan to roll back or restore from earlier RocksDB backups. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thinking of something like this to make the language more active and simplify the first verb phrase: "After you upgrade RHACS to 4.1, you can remove the Central-attached persistent volume..."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Might consider breaking up the sentence. It's quite long.
modules/updates-and-upgrades.adoc
Outdated
|
|
||
| The version of {product-title-managed-short} used on Secured Clusters must match the version of the Central instance of {product-title-managed-short} to ensure compatibility. | ||
| Customers are responsible for Secured Cluster services upgrades required to maintain this version compatibility. | ||
| Customers are responsible for timely {product-title-short} Secured Cluster services upgrades required to maintain compatibility with {product-title-managed-short}. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Customers are responsible for timely {product-title-short} Secured Cluster services upgrades required to maintain compatibility with {product-title-managed-short}. | |
| Customers are responsible for timely {product-title-short} Secured Cluster services upgrades that are required to maintain compatibility with {product-title-managed-short}. |
ISG specifies "that" for restrictive clauses.
modules/updates-and-upgrades.adoc
Outdated
| Customers are responsible for Secured Cluster services upgrades required to maintain this version compatibility. | ||
| Customers are responsible for timely {product-title-short} Secured Cluster services upgrades required to maintain compatibility with {product-title-managed-short}. | ||
|
|
||
| Red Hat recommends enabling automatic upgrades for Secured Clusters connected to {product-title-managed-short}. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Red Hat recommends enabling automatic upgrades for Secured Clusters connected to {product-title-managed-short}. | |
| Red Hat recommends enabling automatic upgrades for Secured Clusters that are connected to {product-title-managed-short}. |
or
| Red Hat recommends enabling automatic upgrades for Secured Clusters connected to {product-title-managed-short}. | |
| Red Hat recommends enabling automatic upgrades for Secured Clusters that connect to {product-title-managed-short}. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I realize this is a weird distinction, but the clusters exist outside of RHACS and while they do connect to them, the component that manages the connection as a whole (Central) is within ACS so I think it's more clear to say "that are connected to", if that makes sense.
upgrading/upgrade-helm.adoc
Outdated
|
|
||
| [role="_abstract"] | ||
| You can upgrade to the latest version of {product-title} from a supported older version. For upgrading to {product-title-short} 4.0, you must be using the latest patch release of {product-title-short} 3.74. If you are using an older version, you must first upgrade to {product-title-short} 3.74. | ||
| Upgrading {product-title-short} requires a specific upgrade path depending on the release of {product-title-short} that you are running. You must also back up your Central database before updating the Helm chart and peforming the upgrade. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could make this a bit more active. E.g., "You must follow a specific path to upgrade {product-title-short}..."
upgrading/upgrade-helm.adoc
Outdated
| . (Optional) Optimize Central database and Persistent Volume Claims (PVC). | ||
| . (Optional) Generate `values-private.yaml` configuration file containing root certificates for the central-services Helm chart. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| . (Optional) Optimize Central database and Persistent Volume Claims (PVC). | |
| . (Optional) Generate `values-private.yaml` configuration file containing root certificates for the central-services Helm chart. | |
| . Optional: Optimize central database and Persistent Volume Claims (PVC). | |
| . Optional: Generate `values-private.yaml` configuration file containing root certificates for the central-services Helm chart. |
or, because it's not a procedure, maybe:
| . (Optional) Optimize Central database and Persistent Volume Claims (PVC). | |
| . (Optional) Generate `values-private.yaml` configuration file containing root certificates for the central-services Helm chart. | |
| . Optionally, optimize central database and Persistent Volume Claims (PVC). | |
| . Optionally, generate `values-private.yaml` configuration file containing root certificates for the central-services Helm chart. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Central is a component and is always capitalized in the RHACS docs.
0022280 to
59c9535
Compare
|
@kcarmichael08: all tests passed! Full PR test history. Your PR dashboard. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
|
/cherrypick rhacs-docs-4.3 |
|
/cherrypick rhacs-docs-4.4 |
|
/cherrypick rhacs-docs-4.5 |
|
@kcarmichael08: #65388 failed to apply on top of branch "rhacs-docs-4.3": In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
@kcarmichael08: new pull request created: #75921 In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
@kcarmichael08: new pull request created: #75922 In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
Version(s):
rhacs-docs-mainrhacs-docs-4.3,rhacs-docs-4.4, andrhacs-docs-4.5(but 4.5 will have further updates - see https://issues.redhat.com/browse/ROX-24162)Issues:
Link to docs previews:
QE review: ACS has no QE, approved by SMEs
Additional information:
Replaces #63482 and #63530
See also #65656