OSDOCS#7103: adding admin guideline for conditional updates#64646
OSDOCS#7103: adding admin guideline for conditional updates#64646jab-rh merged 1 commit intoopenshift:mainfrom
Conversation
openshift-ci-robot
added
the
jira/valid-reference
|
@skopacz1: This pull request references OSDOCS-7103 which is a valid jira issue. DetailsIn 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. |
openshift-ci
bot
added
the
size/M
|
🤖 Updated build preview is available at: Build log: https://circleci.com/gh/ocpdocs-previewbot/openshift-docs/24812 |
|
@skopacz1: This pull request references OSDOCS-7103 which is a valid jira issue. DetailsIn 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. |
skopacz1
changed the title
openshift-ci-robot
removed
the
jira/valid-reference
|
@skopacz1: No Jira issue is referenced in the title of this pull request. DetailsIn 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. |
| [id="update-preparing-conditional_{context}"] | ||
| = Assessing the risk of conditional updates | ||
|
|
||
| A conditional update is a supported update target that is available but not recommended due to a known risk that applies to your cluster. |
There was a problem hiding this comment.
IMO we should remove the supported word from here. Just A conditional update is an update path that is available but not recommended due to a known risk that applies to your cluster.
There was a problem hiding this comment.
What RH supports is a hard question because we do not deny customers support in general irrespective of the situation.
There was a problem hiding this comment.
Sure thing, just wanted to take this opportunity to keep hammering the idea that "just because it doesn't have the word recommended next to it doesn't mean it's unsupported and has to be avoided at all costs", but I can remove the word here
| = Assessing the risk of conditional updates | ||
|
|
||
| A conditional update is a supported update target that is available but not recommended due to a known risk that applies to your cluster. | ||
| The Cluster Version Operator (CVO) periodically queries the OpenShift Update Service (OSUS) for the most recent data about update possibilities, and some potential update targets have conditional risks. |
There was a problem hiding this comment.
s/update possibilities/update recommendations/
There was a problem hiding this comment.
s/some potential update targets have conditional risks./some potential update targets might have risks associated with them./
| A conditional update is a supported update target that is available but not recommended due to a known risk that applies to your cluster. | ||
| The Cluster Version Operator (CVO) periodically queries the OpenShift Update Service (OSUS) for the most recent data about update possibilities, and some potential update targets have conditional risks. | ||
|
|
||
| These conditional risks are evaluated by the CVO, and if the risk is not applicable to the cluster then the update is available to users as a recommended update. |
There was a problem hiding this comment.
suggested text: and if the risk is not applicable to the cluster then the target version is available as a recommended update path for the cluster.
| The Cluster Version Operator (CVO) periodically queries the OpenShift Update Service (OSUS) for the most recent data about update possibilities, and some potential update targets have conditional risks. | ||
|
|
||
| These conditional risks are evaluated by the CVO, and if the risk is not applicable to the cluster then the update is available to users as a recommended update. | ||
| If the risk is determined to be applicable, or if for some reason CVO cannot evaluate the risk, then the update is available to users as a conditional update. |
There was a problem hiding this comment.
suggested text: then the update target is available to the cluster as a conditional update.
|
/cc |
skopacz1
force-pushed
the
OSDOCS-7103
branch
from
a51959e to
401f760
Compare
|
@shellyyang1989 could you PTAL when you have a chance? Thanks! |
The content looks good to me. Just wonder why we won't apply it to 4.13 and earlier. |
|
@shellyyang1989 sorry, forgot to mention in my comment 0 that I will be backporting it to earlier versions. Ever since my documentation reorg, all assembly level changes to docs for versions 4.13 and earlier need to be done in separate PRs. Thanks for bringing it up! |
|
/label peer-review-needed |
openshift-ci
bot
added
the
peer-review-needed
|
/label peer-review-in-progress |
openshift-ci
bot
added
peer-review-in-progress
| These conditional risks are evaluated by the CVO, and if the risk is not applicable to the cluster, then the target version is available as a recommended update path for the cluster. | ||
| If the risk is determined to be applicable, or if for some reason CVO cannot evaluate the risk, then the update target is available to the cluster as a conditional update. | ||
|
|
||
| When you encounter a conditional update while trying to update to a target version, you must assess the risk of updating your cluster to this version. |
There was a problem hiding this comment.
| When you encounter a conditional update while trying to update to a target version, you must assess the risk of updating your cluster to this version. | |
| When you encounter a conditional update while you are trying to update to a target version, you must assess the risk of updating your cluster to that version. |
- Added "you are" to avoid a dangling modifier.
- Replaced "this" with "that" because the word "that" seems to more clearly refer back to "the target version". Might just be my personal preference, though.
| If the risk is determined to be applicable, or if for some reason CVO cannot evaluate the risk, then the update target is available to the cluster as a conditional update. | ||
|
|
||
| When you encounter a conditional update while trying to update to a target version, you must assess the risk of updating your cluster to this version. | ||
| Generally, if there is no specific need to update to this target version, it is best to wait for a recommended update path from Red Hat. |
There was a problem hiding this comment.
| Generally, if there is no specific need to update to this target version, it is best to wait for a recommended update path from Red Hat. | |
| Generally, if you do not have a specific need to update to that target version, wait for a recommended update path from Red Hat. |
IBM Style suggests rewriting phrases that include there is where possible.
There was a problem hiding this comment.
I understand the intention to remove "it is best to" and to just state the recommended action, per the RHSSG, but I feel that this is one of those scenarios where we are specifically trying to avoid being prescriptive.
The entire module is trying to coach the user on how to make their own decision rather than following any sort of formal instruction, and I'm not sure we want to be on the hook for explicitly telling users to not perform a conditional update. Is it possible to keep this or replace it with similar wording?
There was a problem hiding this comment.
@skopacz1 Considering the intent of the topic, I think it's okay to leave in the "it is best to". Thanks for the background!
There was a problem hiding this comment.
Awesome, thanks! I'll still reword to avoid "there is"
| When you encounter a conditional update while trying to update to a target version, you must assess the risk of updating your cluster to this version. | ||
| Generally, if there is no specific need to update to this target version, it is best to wait for a recommended update path from Red Hat. | ||
|
|
||
| However, if there is a strong reason to update to this version, for example fixing an important CVE, then the benefit of fixing the CVE may outweigh the risk of the update being problematic for your cluster. |
There was a problem hiding this comment.
| However, if there is a strong reason to update to this version, for example fixing an important CVE, then the benefit of fixing the CVE may outweigh the risk of the update being problematic for your cluster. | |
| However, if you have a strong reason to update to that version, for example, if you need to fix an important CVE, then the benefit of fixing the CVE might outweigh the risk of the update being problematic for your cluster. |
- Per IBM Style, use may to indicate permission, not ability.
- I revised the wording around for example per the IBM Style Examples topic.
| Generally, if there is no specific need to update to this target version, it is best to wait for a recommended update path from Red Hat. | ||
|
|
||
| However, if there is a strong reason to update to this version, for example fixing an important CVE, then the benefit of fixing the CVE may outweigh the risk of the update being problematic for your cluster. | ||
| You can perform the following tasks to determine whether you agree with Red Hat's assessment of the update risk: |
There was a problem hiding this comment.
| You can perform the following tasks to determine whether you agree with Red Hat's assessment of the update risk: | |
| You can complete the following tasks to determine whether you agree with the Red Hat assessment of the update risk: |
- Because "Red Hat" is a trademarked term, it doesn't take the possessive.
- Per IBM Style, the term complete is preferred over perform.
| However, if there is a strong reason to update to this version, for example fixing an important CVE, then the benefit of fixing the CVE may outweigh the risk of the update being problematic for your cluster. | ||
| You can perform the following tasks to determine whether you agree with Red Hat's assessment of the update risk: | ||
|
|
||
| * Perform extensive testing in a non-production environment to the extent that you are comfortable performing this update in your production environment. |
There was a problem hiding this comment.
| * Perform extensive testing in a non-production environment to the extent that you are comfortable performing this update in your production environment. | |
| * Complete extensive testing in a non-production environment to the extent that you are comfortable completing the update in your production environment. |
| [id="update-preparing-conditional_{context}"] | ||
| = Assessing the risk of conditional updates | ||
|
|
||
| A conditional update is an update target that is available but not recommended due to a known risk that applies to your cluster. |
There was a problem hiding this comment.
| A conditional update is an update target that is available but not recommended due to a known risk that applies to your cluster. | |
| A _conditional update_ is an update target that is available but not recommended due to a known risk that applies to your cluster. |
From the IBM Style Highlighting topic, words that are being defined or explained are highlighted in italics.
There was a problem hiding this comment.
Interesting, this is good to know!
| A conditional update is an update target that is available but not recommended due to a known risk that applies to your cluster. | ||
| The Cluster Version Operator (CVO) periodically queries the OpenShift Update Service (OSUS) for the most recent data about update recommendations, and some potential update targets might have risks associated with them. | ||
|
|
||
| These conditional risks are evaluated by the CVO, and if the risk is not applicable to the cluster, then the target version is available as a recommended update path for the cluster. |
There was a problem hiding this comment.
| These conditional risks are evaluated by the CVO, and if the risk is not applicable to the cluster, then the target version is available as a recommended update path for the cluster. | |
| The CVO evaluates the conditional risks, and if the risks are not applicable to the cluster, then the target version is available as a recommended update path for the cluster. |
Revising to use active voice.
openshift-ci
bot
added
the
peer-review-done
|
/label qe-approved |
openshift-ci
bot
added
the
qe-approved
skopacz1
force-pushed
the
OSDOCS-7103
branch
from
401f760 to
29ceefe
Compare
|
/remove-label peer-review-in-progress |
openshift-ci
bot
added
merge-review-needed
|
|
||
| Learn more about administrative tasks that cluster admins must perform to successfully initialize an update, as well as optional guidelines for ensuring a successful update. | ||
|
|
||
| == Kubernetes API deprecations and removals |
There was a problem hiding this comment.
@skopacz1, I believe this needs an id even as a level 2, such as:
[id="{context}_kubernetes-api-deprecations-and-removals"]
There was a problem hiding this comment.
Good call, thanks!
jab-rh
added
merge-review-in-progress
skopacz1
force-pushed
the
OSDOCS-7103
branch
from
29ceefe to
4f1e8a9
Compare
|
/cherry-pick enterprise-4.14 |
|
@jab-rh: new pull request created: #64792 DetailsIn 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. |
jab-rh
removed
the
merge-review-in-progress
9 participants
OSDOCS-7103
Versions: 4.14+
This PR adds guidance to users who want to determine whether they should update to a conditional update.
After merging, this content can be backported to earlier versions.
QE review:
Preview: Assessing the risk of conditional updates