Skip to content

ROX-18976: fix language around secured cluster and central version matching #63530

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.

Sign up for GitHub

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

Closed
wants to merge 3 commits into from
Closed

ROX-18976: fix language around secured cluster and central version matching #63530

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c2f1e57
Update upgrade info
kcarmichael08 Aug 11, 2023
0888dc1
fix language around secured cluster and central version matching
kcarmichael08 Aug 14, 2023
2470bf2
Merge branch 'rhacs-docs' into ROX-18976-cloud-service-versions
kcarmichael08 Sep 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion modules/install-acs-operator.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ If you choose manual updates, when a newer version of the Operator is available,
+
[IMPORTANT]
====
If you choose manual updates, you must update the {product-title-short} Operator in all secured clusters when you update the {product-title-short} Operator in the cluster where Central is installed. The secured clusters and the cluster where Central is installed must have the same version to ensure optimal functionality.
If you choose manual updates, you must update the {product-title-short} Operator in all secured clusters when you update the {product-title-short} Operator in the cluster where Central is installed. The secured clusters and the cluster where Central is installed must have the same version to ensure optimal functionality. For {product-title-managed-short}, use the latest version of the software that is available. (The software version for Central is automatically updated.)
====
Comment on lines 34 to 37
Copy link

@msugakov msugakov Aug 29, 2023

Choose a reason for hiding this comment

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

This gets rendered on the page dedicated to the installation for self-managed. https://63530--docspreview.netlify.app/openshift-acs/latest/installing/installing_ocp/install-central-ocp#install-acs-operator_install-central-ocp

There's a page about Operator installation for Secured Cluster connected to ACS CS mentioning manual operator updates. https://63530--docspreview.netlify.app/openshift-acs/latest/cloud_service/installing_cloud_ocp/cloud-install-operator#install-acs-operator-cloud_cloud-install-operator
I think, we should add a note there saying that Red Hat recommends enabling automatic upgrades.

I suggest removing the new sentence from this page but adding one as [IMPORTANT] note to the CS page.

Copy link
Contributor Author

@kcarmichael08 kcarmichael08 Sep 27, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

This gets rendered on the page dedicated to the installation for self-managed. 63530--docspreview.netlify.app/openshift-acs/latest/installing/installing_ocp/install-central-ocp#install-acs-operator_install-central-ocp

(disregard previous message - have moved this note to the cloud services operator install module)


. Click *Install*.
Expand Down
9 changes: 8 additions & 1 deletion modules/prepare-operator-upgrades.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,14 @@
= Preparing to upgrade

[role="_abstract"]
Before you upgrade {rh-rhacs-first} version, you must:
Before you upgrade the {rh-rhacs-first} version, you must perform the following steps:

* 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 `SecuredCluster` custom resource is present in the cluster, ensure the per node collection setting is set to EBPF by following these steps:
. In the {ocp} web console, navigate to the {rh-rhacs-first} Operator page.
. Select *Secured Cluster* in the top navigation bar, and then select the instance by clicking on the name (for example, *stackrox-secured-cluster-services*).
. Click *YAML* to open the YAML editor view.
. Locate the `spec.perNode.collector.collection` attribute.
. If the value of this attribute is `KernelModule`, change it to `EBPF`.
. Click `Save`.
3 changes: 1 addition & 2 deletions modules/updates-and-upgrades.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,4 @@ The decision regarding the need for a Service update to the Central instance and
Customers have no control over when a Central service update occurs. For more information, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES].
Upgrades to the version of {rh-rhacscs-first} are considered part of the service update.

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.
To ensure optimal functionality and compatibility between Central and secured clusters, upgrade your secured clusters to the latest software version available. (The software version for Central is automatically updated.)
Copy link

@msugakov msugakov Aug 29, 2023

Choose a reason for hiding this comment

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

Optional suggestion:

Suggested change
To ensure optimal functionality and compatibility between Central and secured clusters, upgrade your secured clusters to the latest software version available. (The software version for Central is automatically updated.)
To ensure optimal functionality and compatibility between Central service and Secured Clusters, upgrade your secured clusters to the latest software version available. (The software version for Central is automatically updated.)

Copy link
Contributor Author

@kcarmichael08 kcarmichael08 Sep 27, 2023

Choose a reason for hiding this comment

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

secured clusters are not capitalized in the docs.

2 changes: 1 addition & 1 deletion modules/upgrade-helm-chart.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
You can use the `helm upgrade` command to update {rh-rhacs-first}.

.Prerequisites
* You must have access to the `values-private.yaml` configuration file that you have used to install {rh-rhacs-first}. Otherwise, you must generate the `values-private.yaml` configuration file containg root certificates, before proceeding with the commands here.
* You must have access to the `values-private.yaml` configuration file that you have used to install {rh-rhacs-first}. Otherwise, you must generate the `values-private.yaml` configuration file containing root certificates, before proceeding with the commands here.

.Procedure
* Run the helm upgrade command and specify the configuration files by using the `-f` option:
Expand Down
2 changes: 1 addition & 1 deletion upgrading/upgrade-helm.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ If you have installed {product-title} by using Helm charts, to upgrade to the la

[IMPORTANT]
====
To ensure optimal functionality, use the same version for your secured-cluster-services Helm chart and central-services Helm chart.
To ensure optimal functionality, use the same version for your secured-cluster-services Helm chart and central-services Helm chart. For {product-title-managed-short}, use the latest version of the secured-cluster-services Helm chart that is available. (The software version for Central is automatically updated.)
====

include::modules/back-up-central-database.adoc[leveloffset=+1]
Expand Down
15 changes: 9 additions & 6 deletions upgrading/upgrade-operator.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@ include::modules/common-attributes.adoc[]
toc::[]

[role="_abstract"]
Upgrades through the {rh-rhacs-first} Operator are performed automatically or manually, depending on the *Update approval* option you chose at installation.
Upgrades through the {rh-rhacs-first} Operator are performed automatically or manually, depending on the *Update approval* option you chose at installation. Upgrading from version 3.74 to 4.x requires some additional steps that are described on this page. Upgrading within 4.y versions requires no additional steps.
Copy link

@msugakov msugakov Aug 29, 2023

Choose a reason for hiding this comment

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

I suggest stick to 4.x for consistency unless you meant to highlight the difference between 4.x and 4.y in this sentence.

Suggested change
Upgrades through the {rh-rhacs-first} Operator are performed automatically or manually, depending on the *Update approval* option you chose at installation. Upgrading from version 3.74 to 4.x requires some additional steps that are described on this page. Upgrading within 4.y versions requires no additional steps.
Upgrades through the {rh-rhacs-first} Operator are performed automatically or manually, depending on the *Update approval* option you chose at installation. Upgrading from version 3.74 to 4.x requires some additional steps that are described on this page. Upgrading within 4.x versions requires no additional steps.


[id="upgrading-from-version-3x-to-4x_{context}"]
== Upgrading from version 3.74 to 4.x

{product-title-short} 4.0 includes a significant architectural change, moving Central’s database to PostgreSQL. Because of this change, {product-title-short} 4.0 Operator is published by a new subscription channel. Therefore, as part of the upgrade instructions, you must manually change the subscription channel to upgrade from {product-title-short} 3.74 to {product-title-short} 4.0.

Expand All @@ -19,16 +22,16 @@ Upgrades through the {rh-rhacs-first} Operator are performed automatically or ma
* You must be using {product-title-short} 3.74 to upgrade to {product-title-short} 4.0. If you are using a version older than 3.74, you must first upgrade to {product-title-short} 3.74 and then upgrade to {product-title-short} 4.0.
====

include::modules/prepare-operator-upgrades.adoc[leveloffset=+1]
include::modules/prepare-operator-upgrades.adoc[leveloffset=+2]

[role="_additional-resources"]
.Additional resources
* link:https://docs.openshift.com/container-platform/latest/operators/admin/olm-upgrading-operators.html[Updating installed Operators]
* xref:../backup_and_restore/backing-up-acs.adoc[Backing up {product-title}]

include::modules/operator-upgrade-modify-central-custom-resource.adoc[leveloffset=+1]
include::modules/operator-upgrade-modify-central-custom-resource.adoc[leveloffset=+3]

include::modules/operator-upgrade-modify-central-custom-resource-tech-preview.adoc[leveloffset=+1]
include::modules/operator-upgrade-modify-central-custom-resource-tech-preview.adoc[leveloffset=+3]

[role="_additional-resources"]
.Additional resources
Expand All @@ -37,9 +40,9 @@ include::modules/operator-upgrade-modify-central-custom-resource-tech-preview.ad

include::modules/operator-upgrade-change-subscription-channel.adoc[leveloffset=+1]

include::modules/remove-central-attached-pv-overview.adoc[leveloffset=+1]
include::modules/remove-central-attached-pv-overview.adoc[leveloffset=+3]

include::modules/remove-central-attached-pv-operator.adoc[leveloffset=+2]
include::modules/remove-central-attached-pv-operator.adoc[leveloffset=+4]
Comment on lines +43 to +45
Copy link

@msugakov msugakov Aug 29, 2023

Choose a reason for hiding this comment

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

I noticed the PR description says

  • cherry pick to rhacs-docs-4.0

This will be wrong w.r.t. Remove Central-attached PV section because it only applies to 4.1+ releases.
Continuing our earlier conversation #63482 (comment) (and the one in JIRA), I suggest to structure this page in a following manner:

# Upgrading from 4.0

## Remove Central-attached PV

# Upgrading from 3.x

(notes about upgrading 3.x to 3.74, then from 3.74 to 4.0, then from 4.0 further)

## (upgrade steps)
### Preparing to upgrade
### Changing subscription channel

## Rolling back an Operator upgrade
## Troubleshooting Operator upgrade issues

I.e. group steps corresponding to the release from which the user will upgrade.
Also, optionally, make newer "from" releases go before older ones so that users who upgrade often don't need to scroll the page to check if there are any instructions that apply to their case.

I don't know if we can avoid maintaining separate versions of this page per releases. Cherry-picking shouldn't be used, but at least the new content will be additive.

Copy link
Contributor Author

@kcarmichael08 kcarmichael08 Sep 27, 2023

Choose a reason for hiding this comment

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

OK, based on this and looking into it more, I am going to need to make separate PRs for the branches. I'll be closing this one and opening new ones.


[id="rollback-operator-upgrade"]
== Rolling back an Operator upgrade
Expand Down