Skip to content

Commit 4ee9dd4

Browse files
bergerhofferbergerhoffer
authored
Merge pull request #36809 from bergerhoffer/OSDOCS-2627-49-upgrading
OSDOCS-2627: Adding docs for admin ack required to upgrade to OCP 4.9
2 parents f6c505f + be4081f commit 4ee9dd4

9 files changed

+290
-0
lines changed

‎_topic_map.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -456,6 +456,14 @@ Topics:
456456
File: understanding-the-update-service
457457
- Name: Installing and configuring the OpenShift Update Service
458458
File: installing-update-service
459+
# TODO: Remove below assembly for 4.10:
460+
- Name: Preparing to update to OpenShift Container Platform 4.9
461+
File: updating-cluster-prepare
462+
Distros: openshift-enterprise
463+
# TODO: Remove below assembly for 4.10:
464+
- Name: Preparing to update to OKD 4.9
465+
File: updating-cluster-prepare
466+
Distros: openshift-origin
459467
- Name: Updating a cluster between minor versions
460468
File: updating-cluster-between-minor
461469
- Name: Updating a cluster within a minor version from the web console

‎modules/update-preparing-ack.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
[id="update-preparing-ack_{context}"]
6+
= Providing the administrator acknowledgment
7+
8+
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.8 to 4.9.
9+
10+
[WARNING]
11+
====
12+
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.
13+
====
14+
15+
.Prerequisites
16+
17+
* You must have access to the cluster as a user with the `cluster-admin` role.
18+
19+
.Procedure
20+
21+
* Run the following command to acknowledge that you have completed the evaluation and your cluster is ready to upgrade to {product-title} 4.9:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc -n openshift-config patch cm admin-acks --patch '{"data":{"ack-4.8-kube-1.22-api-removals-in-4.9":"true"}}' --type=merge
26+
----

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
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+
{product-title} 4.8 introduced two new alerts that 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. You can use the `APIRequestCount` API to get more information about which APIs are in use and which workloads are using removed APIs.

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
[id="update-preparing-evaluate-apirequestcount-workloads_{context}"]
6+
= Using APIRequestCount to identify which workloads are using the removed APIs
7+
8+
You can examine the `APIRequestCount` resource for a given API version to help identify which workloads are using the API.
9+
10+
.Prerequisites
11+
12+
* You must have access to the cluster as a user with the `cluster-admin` role.
13+
14+
.Procedure
15+
16+
* Run the following command and examine the `username` and `userAgent` fields to help identify the workloads that are using the API:
17+
+
18+
[source,terminal]
19+
----
20+
$ oc get apirequestcounts <resource>.<version>.<group> -o yaml
21+
----
22+
+
23+
For example:
24+
+
25+
[source,terminal]
26+
----
27+
$ oc get apirequestcounts ingresses.v1beta1.networking.k8s.io -o yaml
28+
----
29+
+
30+
You can also use `-o jsonpath` to extract the `username` values from an `APIRequestCount` resource:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc get apirequestcounts ingresses.v1beta1.networking.k8s.io -o jsonpath='{range ..username}{$}{"\n"}{end}' | sort | uniq
35+
----
36+
+
37+
.Example output
38+
[source,terminal]
39+
----
40+
user1
41+
user2
42+
app:serviceaccount:delta
43+
----

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

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * updating/updating-cluster-prepare.adoc
4+
5+
[id="update-preparing-evaluate-apirequestcount_{context}"]
6+
= Using APIRequestCount to identify uses of removed APIs
7+
8+
You can use the `APIRequestCount` API to track API requests and review whether any of them are using one of the removed APIs.
9+
10+
.Prerequisites
11+
12+
* You must have access to the cluster as a user with the `cluster-admin` role.
13+
14+
.Procedure
15+
16+
* Run the following command and examine the `REMOVEDINRELEASE` column of the output to identify the removed APIs that are currently in use:
17+
+
18+
[source,terminal]
19+
----
20+
$ oc get apirequestcounts
21+
----
22+
+
23+
.Example output
24+
[source,terminal]
25+
----
26+
NAME REMOVEDINRELEASE REQUESTSINCURRENTHOUR REQUESTSINLAST24H
27+
cloudcredentials.v1.operator.openshift.io 32 111
28+
ingresses.v1.networking.k8s.io 28 110
29+
ingresses.v1beta1.extensions 1.22 16 66
30+
ingresses.v1beta1.networking.k8s.io 1.22 0 1
31+
installplans.v1alpha1.operators.coreos.com 93 167
32+
...
33+
----
34+
+
35+
You can also use `-o jsonpath` to filter the results:
36+
+
37+
[source,terminal]
38+
----
39+
$ oc get apirequestcounts -o jsonpath='{range .items[?(@.status.removedInRelease!="")]}{.status.removedInRelease}{"\t"}{.metadata.name}{"\n"}{end}'
40+
----
41+
+
42+
.Example output
43+
[source,terminal]
44+
----
45+
1.22 certificatesigningrequests.v1beta1.certificates.k8s.io
46+
1.22 ingresses.v1beta1.extensions
47+
1.22 ingresses.v1beta1.networking.k8s.io
48+
----

‎modules/update-preparing-list.adoc‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
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+
// TODO: Keep michael's section in the release notes (which this duplicates), or link to this from his RN section?
9+
{product-title} 4.9 uses Kubernetes 1.22, which removed the following deprecated `v1beta1` APIs. You must migrate manifests and API clients to use the `v1` API version. For more information about migrating removed APIs, see the link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22[Kubernetes documentation].
10+
11+
.`v1beta1` APIs removed from Kubernetes 1.22
12+
[cols="2,2,1",options="header",]
13+
|===
14+
|Resource |API |Notable changes
15+
16+
|`APIService`
17+
|`apiregistration.k8s.io/v1beta1`
18+
|No
19+
20+
|`CertificateSigningRequest`
21+
|`certificates.k8s.io/v1beta1`
22+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#certificatesigningrequest-v122[Yes]
23+
24+
|`ClusterRole`
25+
|`rbac.authorization.k8s.io/v1beta1`
26+
|No
27+
28+
|`ClusterRoleBinding`
29+
|`rbac.authorization.k8s.io/v1beta1`
30+
|No
31+
32+
|`CSIDriver`
33+
|`storage.k8s.io/v1beta1`
34+
|No
35+
36+
|`CSINode`
37+
|`storage.k8s.io/v1beta1`
38+
|No
39+
40+
|`CustomResourceDefinition`
41+
|`apiextensions.k8s.io/v1beta1`
42+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#customresourcedefinition-v122[Yes]
43+
44+
|`Ingress`
45+
|`extensions/v1beta1`
46+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#ingress-v122[Yes]
47+
48+
|`Ingress`
49+
|`networking.k8s.io/v1beta1`
50+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#ingress-v122[Yes]
51+
52+
|`IngressClass`
53+
|`networking.k8s.io/v1beta1`
54+
|No
55+
56+
|`Lease`
57+
|`coordination.k8s.io/v1beta1`
58+
|No
59+
60+
|`LocalSubjectAccessReview`
61+
|`authorization.k8s.io/v1beta1`
62+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#subjectaccessreview-resources-v122[Yes]
63+
64+
|`MutatingWebhookConfiguration`
65+
|`admissionregistration.k8s.io/v1beta1`
66+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#webhook-resources-v122[Yes]
67+
68+
|`PriorityClass`
69+
|`scheduling.k8s.io/v1beta1`
70+
|No
71+
72+
|`Role`
73+
|`rbac.authorization.k8s.io/v1beta1`
74+
|No
75+
76+
|`RoleBinding`
77+
|`rbac.authorization.k8s.io/v1beta1`
78+
|No
79+
80+
|`SelfSubjectAccessReview`
81+
|`authorization.k8s.io/v1beta1`
82+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#subjectaccessreview-resources-v122[Yes]
83+
84+
|`StorageClass`
85+
|`storage.k8s.io/v1beta1`
86+
|No
87+
88+
|`SubjectAccessReview`
89+
|`authorization.k8s.io/v1beta1`
90+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#subjectaccessreview-resources-v122[Yes]
91+
92+
|`TokenReview`
93+
|`authentication.k8s.io/v1beta1`
94+
|No
95+
96+
|`ValidatingWebhookConfiguration`
97+
|`admissionregistration.k8s.io/v1beta1`
98+
|link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#webhook-resources-v122[Yes]
99+
100+
|`VolumeAttachment`
101+
|`storage.k8s.io/v1beta1`
102+
|No
103+
104+
|===

‎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 on how to migrate removed Kubernetes APIs, see the link:https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-22[Deprecated API Migration Guide] in the Kubernetes documentation.

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,9 @@ See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permis
2121
* 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.
2222
* If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see _Upgrading clusters with manually maintained credentials_ for xref:../installing/installing_aws/manually-creating-iam.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-aws[AWS], xref:../installing/installing_azure/manually-creating-iam-azure.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-azure[Azure], or xref:../installing/installing_gcp/manually-creating-iam-gcp.adoc#manually-maintained-credentials-upgrade_manually-creating-iam-gcp[GCP].
2323
* 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 upgraded 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_].
24+
* Review the list of APIs that were removed in Kubernetes 1.22, 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.9].
25+
+
26+
// TODO: Currently, this ^ admin ack is only applicable for 4.9 and should be removed for 4.10+
2427

2528
[IMPORTANT]
2629
====

‎updating/updating-cluster-prepare.adoc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
[id="updating-cluster-prepare"]
2+
= Preparing to update to {product-title} 4.9
3+
include::modules/common-attributes.adoc[]
4+
:context: updating-cluster-prepare
5+
6+
toc::[]
7+
8+
{product-title} 4.9 uses Kubernetes 1.22, which removed a significant number of deprecated `v1beta1` APIs.
9+
10+
4.8.TODO introduced a requirement that an administrator must provide a manual acknowledgment before the cluster can be upgraded 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 is done, the administrator can provide the administrator acknowledgment.
11+
12+
Before you can upgrade your {product-title} 4.8 cluster to 4.9, you must provide the administrator acknowledgment.
13+
14+
// TODO: Update to specify which 4.8 z-stream this check was introduced in.
15+
16+
// Removed Kubernetes APIs
17+
include::modules/update-preparing-list.adoc[leveloffset=+1]
18+
19+
[id="evaluating-cluster-removed-apis"]
20+
== Evaluating your cluster for removed APIs
21+
22+
There are several methods to help administrators identify where APIs that will be removed are in use. However, {product-title} cannot identify all instances, especially workloads that are idle or external tools that are used. It is the responsibility of the administrator to properly evaluate all workloads and other integrations for instances of removed APIs.
23+
24+
// Reviewing alerts to identify uses of removed APIs
25+
include::modules/update-preparing-evaluate-alerts.adoc[leveloffset=+2]
26+
27+
// Using APIRequestCount to identify uses of removed APIs
28+
include::modules/update-preparing-evaluate-apirequestcount.adoc[leveloffset=+2]
29+
30+
// Using APIRequestCount to identify which workloads are using the removed APIs
31+
include::modules/update-preparing-evaluate-apirequestcount-workloads.adoc[leveloffset=+2]
32+
33+
// Migrating instances of removed APIs
34+
include::modules/update-preparing-migrate.adoc[leveloffset=+1]
35+
36+
// Providing the administrator acknowledgment
37+
include::modules/update-preparing-ack.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)