Skip to content

Commit f1044c1

Browse files
bergerhofferbergerhoffer
authored
Merge pull request #51163 from bergerhoffer/OSDOCS-3574
OSDOCS-3574: Adding preparing to update to 4.12 docs
2 parents 64fb866 + d670fcd commit f1044c1

10 files changed

+231
-5
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -531,6 +531,12 @@ Topics:
531531
File: understanding-upgrade-channels-release
532532
- Name: Understanding OpenShift update duration
533533
File: understanding-openshift-update-duration
534+
- Name: Preparing to update to OpenShift Container Platform 4.12
535+
File: updating-cluster-prepare
536+
Distros: openshift-enterprise
537+
- Name: Preparing to update to OKD 4.12
538+
File: updating-cluster-prepare
539+
Distros: openshift-origin
534540
- Name: Preparing to perform an EUS-to-EUS update
535541
File: preparing-eus-eus-upgrade
536542
- Name: Updating a cluster using the web console

‎modules/update-preparing-ack.adoc

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="update-preparing-ack_{context}"]
7+
= Providing the administrator acknowledgment
8+
9+
After you have evaluated your cluster for any removed APIs and have migrated any removed APIs, you can acknowledge that your cluster is ready to upgrade from {product-title} 4.11 to 4.12.
10+
11+
[WARNING]
12+
====
13+
Be aware that all responsibility falls on the administrator to ensure that all uses of removed APIs have been resolved and migrated as necessary before providing this administrator acknowledgment. {product-title} can assist with the evaluation, but cannot identify all possible uses of removed APIs, especially idle workloads or external tools.
14+
====
15+
16+
.Prerequisites
17+
18+
* You must have access to the cluster as a user with the `cluster-admin` role.
19+
20+
.Procedure
21+
22+
* Run the following command to acknowledge that you have completed the evaluation and your cluster is ready for the Kubernetes API removals in {product-title} 4.12:
23+
+
24+
[source,terminal]
25+
----
26+
$ oc -n openshift-config patch cm admin-acks --patch '{"data":{"ack-4.11-kube-1.25-api-removals-in-4.12":"true"}}' --type=merge
27+
----

‎modules/update-preparing-evaluate-alerts.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
[id="update-preparing-evaluate-alerts_{context}"]
6+
= Reviewing alerts to identify uses of removed APIs
7+
8+
Two alerts fire when an API is in use that will be removed in the next release:
9+
10+
* `APIRemovedInNextReleaseInUse` - for APIs that will be removed in the next {product-title} release.
11+
* `APIRemovedInNextEUSReleaseInUse` - for APIs that will be removed in the next {product-title} Extended Update Support (EUS) release.
12+
13+
If either of these alerts are firing in your cluster, review the alerts and take action to clear the alerts by migrating manifests and API clients to use the new API version.
14+
15+
Use the `APIRequestCount` API to get more information about which APIs are in use and which workloads are using removed APIs, because the alerts do not provide this information. Additionally, some APIs might not trigger these alerts but are still captured by `APIRequestCount`. The alerts are tuned to be less sensitive to avoid alerting fatigue in production systems.

‎modules/update-preparing-evaluate-apirequestcount-workloads.adoc

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="update-preparing-evaluate-apirequestcount-workloads_{context}"]
7+
= Using APIRequestCount to identify which workloads are using the removed APIs
8+
9+
You can examine the `APIRequestCount` resource for a given API version to help identify which workloads are using the API.
10+
11+
.Prerequisites
12+
13+
* You must have access to the cluster as a user with the `cluster-admin` role.
14+
15+
.Procedure
16+
17+
* Run the following command and examine the `username` and `userAgent` fields to help identify the workloads that are using the API:
18+
+
19+
[source,terminal]
20+
----
21+
$ oc get apirequestcounts <resource>.<version>.<group> -o yaml
22+
----
23+
+
24+
For example:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc get apirequestcounts poddisruptionbudgets.v1beta1.policy -o yaml
29+
----
30+
+
31+
You can also use `-o jsonpath` to extract the `username` and `userAgent` values from an `APIRequestCount` resource:
32+
+
33+
[source,terminal]
34+
----
35+
$ oc get apirequestcounts poddisruptionbudgets.v1beta1.policy \
36+
-o jsonpath='{range .status.currentHour..byUser[*]}{..byVerb[*].verb}{","}{.username}{","}{.userAgent}{"\n"}{end}' \
37+
| sort -k 2 -t, -u | column -t -s, -NVERBS,USERNAME,USERAGENT
38+
----
39+
+
40+
.Example output
41+
[source,terminal]
42+
----
43+
VERBS USERNAME USERAGENT
44+
watch system:serviceaccount:openshift-operators:3scale-operator manager/v0.0.0
45+
watch system:serviceaccount:openshift-operators:datadog-operator-controller-manager manager/v0.0.0
46+
----

‎modules/update-preparing-evaluate-apirequestcount.adoc

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="update-preparing-evaluate-apirequestcount_{context}"]
7+
= Using APIRequestCount to identify uses of removed APIs
8+
9+
You can use the `APIRequestCount` API to track API requests and review whether any of them are using one of the removed APIs.
10+
11+
.Prerequisites
12+
13+
* You must have access to the cluster as a user with the `cluster-admin` role.
14+
15+
.Procedure
16+
17+
* Run the following command and examine the `REMOVEDINRELEASE` column of the output to identify the removed APIs that are currently in use:
18+
+
19+
[source,terminal]
20+
----
21+
$ oc get apirequestcounts
22+
----
23+
+
24+
.Example output
25+
[source,terminal]
26+
----
27+
NAME REMOVEDINRELEASE REQUESTSINCURRENTHOUR REQUESTSINLAST24H
28+
...
29+
poddisruptionbudgets.v1.policy 391 8114
30+
poddisruptionbudgets.v1beta1.policy 1.25 2 23
31+
podmonitors.v1.monitoring.coreos.com 3 70
32+
podnetworkconnectivitychecks.v1alpha1.controlplane.operator.openshift.io 612 11748
33+
pods.v1 1531 38634
34+
podsecuritypolicies.v1beta1.policy 1.25 3 39
35+
podtemplates.v1 2 79
36+
preprovisioningimages.v1alpha1.metal3.io 2 39
37+
priorityclasses.v1.scheduling.k8s.io 12 248
38+
prioritylevelconfigurations.v1beta1.flowcontrol.apiserver.k8s.io 1.26 3 86
39+
...
40+
----
41+
+
42+
[IMPORTANT]
43+
====
44+
You can safely ignore the following entries that appear in the results:
45+
46+
* The `system:serviceaccount:kube-system:generic-garbage-collector` and the `system:serviceaccount:kube-system:namespace-controller` users might appear in the results because these services invoke all registered APIs when searching for resources to remove.
47+
* The `system:kube-controller-manager` and `system:cluster-policy-controller` users might appear in the results because they walk through all resources while enforcing various policies.
48+
====
49+
+
50+
You can also use `-o jsonpath` to filter the results:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc get apirequestcounts -o jsonpath='{range .items[?(@.status.removedInRelease!="")]}{.status.removedInRelease}{"\t"}{.metadata.name}{"\n"}{end}'
55+
----
56+
+
57+
.Example output
58+
[source,terminal]
59+
----
60+
1.26 flowschemas.v1beta1.flowcontrol.apiserver.k8s.io
61+
1.26 horizontalpodautoscalers.v2beta2.autoscaling
62+
1.25 poddisruptionbudgets.v1beta1.policy
63+
1.25 podsecuritypolicies.v1beta1.policy
64+
1.26 prioritylevelconfigurations.v1beta1.flowcontrol.apiserver.k8s.io
65+
----

‎modules/update-preparing-list.adoc

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
[id="update-preparing-list_{context}"]
6+
= Removed Kubernetes APIs
7+
8+
{product-title} 4.12 uses Kubernetes 1.25, which removed the following deprecated APIs. You must migrate manifests and API clients to use the appropriate API version. For more information about migrating removed APIs, see the link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-25[Kubernetes documentation].
9+
10+
.APIs removed from Kubernetes 1.25
11+
[cols="2,2,2,1",options="header",]
12+
|===
13+
|Resource |Removed API |Migrate to |Notable changes
14+
15+
|`CronJob`
16+
|`batch/v1beta1`
17+
|`batch/v1`
18+
|No
19+
20+
|`EndpointSlice`
21+
|`discovery.k8s.io/v1beta1`
22+
|`discovery.k8s.io/v1`
23+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#endpointslice-v125[Yes]
24+
25+
|`Event`
26+
|`events.k8s.io/v1beta1`
27+
|`events.k8s.io/v1`
28+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#event-v125[Yes]
29+
30+
|`HorizontalPodAutoscaler`
31+
|`autoscaling/v2beta1`
32+
|`autoscaling/v2`
33+
|No
34+
35+
|`PodDisruptionBudget`
36+
|`policy/v1beta1`
37+
|`policy/v1`
38+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#poddisruptionbudget-v125[Yes]
39+
40+
|`PodSecurityPolicy`
41+
|`policy/v1beta1`
42+
|link:https://kubernetes.io/docs/concepts/security/pod-security-admission/[Pod Security Admission] ^[1]^
43+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#psp-v125[Yes]
44+
45+
|`RuntimeClass`
46+
|`node.k8s.io/v1beta1`
47+
|`node.k8s.io/v1`
48+
|No
49+
50+
|===
51+
[.small]
52+
1. For more information about pod security admission in {product-title}, see _Understanding and managing pod security admission_.

‎modules/update-preparing-migrate.adoc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
[id="update-preparing-migrate_{context}"]
6+
= Migrating instances of removed APIs
7+
8+
For information about how to migrate removed Kubernetes APIs, see the link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-25[Deprecated API Migration Guide] in the Kubernetes documentation.

‎updating/updating-cluster-cli.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis
2424
* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see xref:../updating/updating-cluster-cli.adoc#manually-maintained-credentials-upgrade_updating-cluster-cli[Upgrading clusters with manually maintained credentials].
2525
* If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being updated to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[Upgrading an OpenShift Container Platform cluster configured for manual mode with STS].
2626
* Ensure that you address all `Upgradeable=False` conditions so the cluster allows an update to the next minor version. An alert displays at the top of the *Cluster Settings* page when you have one or more cluster Operators that cannot be upgraded. You can still update to the next available patch update for the minor release you are currently on.
27+
* Review the list of APIs that were removed in Kubernetes 1.25, migrate any affected components to use the new API version, and provide the administrator acknowledgment. For more information, see xref:../updating/updating-cluster-prepare.adoc#updating-cluster-prepare[Preparing to update to {product-title} 4.12].
2728

2829
[IMPORTANT]
2930
====

‎updating/updating-cluster-prepare.adoc

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,25 @@
11
:_content-type: ASSEMBLY
22
[id="updating-cluster-prepare"]
3-
= Preparing to update to {product-title} 4.9
3+
= Preparing to update to {product-title} 4.12
44
include::_attributes/common-attributes.adoc[]
55
:context: updating-cluster-prepare
66

77
toc::[]
88

9-
{product-title} 4.9 uses Kubernetes 1.22, which removed a significant number of deprecated `v1beta1` APIs.
9+
{product-title} 4.12 uses Kubernetes 1.25, which removed several deprecated APIs.
1010

11-
{product-title} 4.8.14 introduced a requirement that an administrator must provide a manual acknowledgment before the cluster can be updated from {product-title} 4.8 to 4.9. This is to help prevent issues after upgrading to {product-title} 4.9, where APIs that have been removed are still in use by workloads, tools, or other components running on or interacting with the cluster. Administrators must evaluate their cluster for any APIs in use that will be removed and migrate the affected components to use the appropriate new API version. After this evaluation and migration is complete, the administrator can provide the acknowledgment.
11+
A cluster administrator must provide a manual acknowledgment before the cluster can be updated from {product-title} 4.11 to 4.12. This is to help prevent issues after upgrading to {product-title} 4.12, where APIs that have been removed are still in use by workloads, tools, or other components running on or interacting with the cluster. Administrators must evaluate their cluster for any APIs in use that will be removed and migrate the affected components to use the appropriate new API version. After this evaluation and migration is complete, the administrator can provide the acknowledgment.
1212

13-
Before you can update your {product-title} 4.8 cluster to 4.9, you must provide the administrator acknowledgment.
13+
Before you can update your {product-title} 4.11 cluster to 4.12, you must provide the administrator acknowledgment.
1414

1515
// Removed Kubernetes APIs
1616
include::modules/update-preparing-list.adoc[leveloffset=+1]
1717

18+
[role="_additional-resources"]
19+
.Additional resources
20+
21+
* xref:../authentication/understanding-and-managing-pod-security-admission.adoc#understanding-and-managing-pod-security-admission[Understanding and managing pod security admission]
22+
1823
[id="evaluating-cluster-removed-apis"]
1924
== Evaluating your cluster for removed APIs
2025

‎updating/updating-cluster-within-minor.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,10 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis
2222
* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid update path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster update. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information.
2323
* Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy.
2424
//remove this???^ or maybe just add another bullet that you can break up the update?
25-
* To accommodate the time it takes to update, you are able to do a partial update by updating the worker or custom pool nodes. You can pause and resume within the progress bar of each pool.
25+
* To accommodate the time it takes to update, you are able to do a partial update by updating the worker or custom pool nodes. You can pause and resume within the progress bar of each pool.
2626
* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see xref:../updating/updating-cluster-cli.adoc#manually-maintained-credentials-upgrade_updating-cluster-cli[Upgrading clusters with manually maintained credentials].
2727
* If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being updated to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[Upgrading an OpenShift Container Platform cluster configured for manual mode with STS].
28+
* Review the list of APIs that were removed in Kubernetes 1.25, migrate any affected components to use the new API version, and provide the administrator acknowledgment. For more information, see xref:../updating/updating-cluster-prepare.adoc#updating-cluster-prepare[Preparing to update to {product-title} 4.12].
2829

2930
[IMPORTANT]
3031
====

0 commit comments

Comments
 (0)