Skip to content

Conversation

@kcarmichael08
Copy link
Contributor

@kcarmichael08 kcarmichael08 commented Sep 28, 2023

@openshift-ci openshift-ci bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Sep 28, 2023
@kcarmichael08 kcarmichael08 force-pushed the acs-upgrade-changes-all-versions branch from 1c2d647 to f065605 Compare October 4, 2023 20:49
@openshift-bot
Copy link

Issues go stale after 90d of inactivity.

Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.

If this issue is safe to close now please do so with /close.

/lifecycle stale

@openshift-ci openshift-ci bot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Jan 3, 2024
@openshift-bot
Copy link

Stale issues rot after 30d of inactivity.

Mark the issue as fresh by commenting /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
Exclude this issue from closing by commenting /lifecycle frozen.

If this issue is safe to close now please do so with /close.

/lifecycle rotten
/remove-lifecycle stale

@openshift-ci openshift-ci bot added lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. and removed lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. labels Feb 3, 2024
@openshift-bot
Copy link

Rotten issues close after 30d of inactivity.

Reopen the issue by commenting /reopen.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Exclude this issue from closing again by commenting /lifecycle frozen.

/close

@openshift-ci openshift-ci bot closed this Mar 4, 2024
@openshift-ci
Copy link

openshift-ci bot commented Mar 4, 2024

@openshift-bot: Closed this PR.

In response to this:

Rotten issues close after 30d of inactivity.

Reopen the issue by commenting /reopen.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Exclude this issue from closing again by commenting /lifecycle frozen.

/close

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.

@kcarmichael08
Copy link
Contributor Author

/reopen

@openshift-ci
Copy link

openshift-ci bot commented Mar 25, 2024

@kcarmichael08: Reopened this PR.

In response to this:

/reopen

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.

@openshift-ci openshift-ci bot reopened this Mar 25, 2024
@openshift-merge-robot openshift-merge-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 25, 2024
@kcarmichael08 kcarmichael08 removed the lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. label Apr 17, 2024
@kcarmichael08 kcarmichael08 changed the base branch from rhacs-docs to rhacs-docs-main April 17, 2024 13:57
@kcarmichael08 kcarmichael08 force-pushed the acs-upgrade-changes-all-versions branch from f065605 to f4f277d Compare April 17, 2024 14:52
@openshift-merge-robot openshift-merge-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 17, 2024
@kcarmichael08 kcarmichael08 force-pushed the acs-upgrade-changes-all-versions branch 3 times, most recently from 3e9a121 to f09025c Compare April 23, 2024 13:53
Copy link

@msugakov msugakov left a 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.

Copy link

@msugakov msugakov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another partial review.

@kcarmichael08
Copy link
Contributor Author

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).

Copy link

@msugakov msugakov left a 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.
Copy link

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

* 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.
Copy link

@msugakov msugakov May 3, 2024

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.

Suggested change
* 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.

Copy link
Contributor Author

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.

Copy link
Contributor Author

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

====
* 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional suggestion:

Suggested change
* 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.

@kcarmichael08 kcarmichael08 force-pushed the acs-upgrade-changes-all-versions branch 2 times, most recently from 8fb7061 to d6718a3 Compare May 10, 2024 18:23
@kcarmichael08 kcarmichael08 added RHACS Label for RHACS related PRs that go in the rhacs-docs branch rhacs-docs-4.3 rhacs-docs-4.4 Label for PRs that apply to RHACS 4.4 labels May 10, 2024
@kcarmichael08 kcarmichael08 force-pushed the acs-upgrade-changes-all-versions branch from d6718a3 to 0022280 Compare May 10, 2024 18:29
@kcarmichael08 kcarmichael08 added peer-review-needed Signifies that the peer review team needs to review this PR rhacs-docs-4.5 labels May 10, 2024
@maxwelldb maxwelldb added peer-review-in-progress Signifies that the peer review team is reviewing this PR and removed peer-review-needed Signifies that the peer review team needs to review this PR labels May 13, 2024
@maxwelldb maxwelldb self-requested a review May 13, 2024 13:10
Copy link
Contributor

@maxwelldb maxwelldb left a 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.
Copy link
Contributor

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?

Copy link
Contributor Author

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.
Copy link
Contributor

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)
Copy link
Contributor

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.

Copy link
Contributor Author

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)
Copy link
Contributor

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.

Copy link
Contributor Author

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
Copy link
Contributor

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.
Copy link
Contributor

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..."

Copy link
Contributor

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.


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}.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

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}.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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

Suggested change
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}.

Copy link
Contributor Author

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.


[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.
Copy link
Contributor

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}..."

Comment on lines 23 to 24
. (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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
. (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:

Suggested change
. (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.

Copy link
Contributor Author

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.

@maxwelldb maxwelldb added peer-review-done Signifies that the peer review team has reviewed this PR and removed peer-review-in-progress Signifies that the peer review team is reviewing this PR labels May 13, 2024
@kcarmichael08 kcarmichael08 force-pushed the acs-upgrade-changes-all-versions branch from 0022280 to 59c9535 Compare May 13, 2024 19:47
@openshift-ci
Copy link

openshift-ci bot commented May 13, 2024

@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.

@kcarmichael08 kcarmichael08 merged commit 1dcf229 into openshift:rhacs-docs-main May 14, 2024
@kcarmichael08
Copy link
Contributor Author

/cherrypick rhacs-docs-4.3

@kcarmichael08
Copy link
Contributor Author

/cherrypick rhacs-docs-4.4

@kcarmichael08
Copy link
Contributor Author

/cherrypick rhacs-docs-4.5

@openshift-cherrypick-robot

@kcarmichael08: #65388 failed to apply on top of branch "rhacs-docs-4.3":

Applying: Updates to upgrade procedures
Using index info to reconstruct a base tree...
M	modules/install-acs-operator-cloud.adoc
M	modules/prepare-operator-upgrades.adoc
M	modules/updates-and-upgrades.adoc
M	upgrading/upgrade-operator.adoc
M	upgrading/upgrade-roxctl.adoc
Falling back to patching base and 3-way merge...
Auto-merging upgrading/upgrade-roxctl.adoc
Auto-merging upgrading/upgrade-operator.adoc
Auto-merging modules/updates-and-upgrades.adoc
Auto-merging modules/prepare-operator-upgrades.adoc
CONFLICT (content): Merge conflict in modules/prepare-operator-upgrades.adoc
Auto-merging modules/install-acs-operator-cloud.adoc
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
Patch failed at 0001 Updates to upgrade procedures
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".

In response to this:

/cherrypick rhacs-docs-4.3

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.

@openshift-cherrypick-robot

@kcarmichael08: new pull request created: #75921

In response to this:

/cherrypick rhacs-docs-4.4

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.

@openshift-cherrypick-robot

@kcarmichael08: new pull request created: #75922

In response to this:

/cherrypick rhacs-docs-4.5

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

peer-review-done Signifies that the peer review team has reviewed this PR RHACS Label for RHACS related PRs that go in the rhacs-docs branch rhacs-docs-4.4 Label for PRs that apply to RHACS 4.4 rhacs-docs-4.5 size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.