Address review comments

Author: liggitt

content/en/docs/contribute/style/style-guide.md

@@ -576,6 +576,10 @@ Avoid making promises or giving hints about the future. If you need to talk abou
 an alpha feature, put the text under a heading that identifies it as alpha
 information.
 
+An exception to this rule is documentation about announced deprecations
+targeting removal in future versions. One example of documentation like this
+is the [Deprecated API migration guide](/docs/reference/using-api/deprecation-guide/).
+
 ### Avoid statements that will soon be out of date
 
 Avoid words like "currently" and "new." A feature that is new today might not be

content/en/docs/reference/using-api/deprecation-guide.md

@@ -6,7 +6,7 @@ reviewers:
 - smarterclayton
 title: "Deprecated API Migration Guide"
 weight: 45
-content_type: api_reference
+content_type: reference
 ---
 
 <!-- overview -->
@@ -25,15 +25,23 @@ deprecated API versions to newer and more stable API versions.
 
 The **v1.25** release will stop serving the following deprecated API versions:
 
-#### Event
+#### Event {#event-v125}
 
 The **events.k8s.io/v1beta1** API version of Event will no longer be served in v1.25.
 
 * Migrate manifests and API clients to use the **events.k8s.io/v1** API version, available since v1.19.
 * All existing persisted objects are accessible via the new API
-* Notable changes
-
-#### RuntimeClass
+* Notable changes in **events.k8s.io/v1**:
+    * `type` is limited to `Normal` and `Warning`
+    * `involvedObject` is renamed to `regarding`
+    * `action`, `reason`, `reportingComponent`, and `reportingInstance` are required when creating new **events.k8s.io/v1** Events
+    * use `eventTime` instead of the deprecated `firstTimestamp` field (which is renamed to `deprecatedFirstTimestamp` and not permitted in new **events.k8s.io/v1** Events)
+    * use `series.lastObservedTime` instead of the deprecated `lastTimestamp` field (which is renamed to `deprecatedLastTimestamp` and not permitted in new **events.k8s.io/v1** Events)
+    * use `series.count` instead of the deprecated `count` field (which is renamed to `deprecatedCount` and not permitted in new **events.k8s.io/v1** Events)
+    * use `reportingComponent` instead of the deprecated `source.component` field (which is renamed to `deprecatedSource.component` and not permitted in new **events.k8s.io/v1** Events)
+    * use `reportingInstance` instead of the deprecated `source.host` field (which is renamed to `deprecatedSource.host` and not permitted in new **events.k8s.io/v1** Events)
+
+#### RuntimeClass {#runtimeclass-v125}
 
 RuntimeClass in the **node.k8s.io/v1beta1** API version will no longer be served in v1.25.
 
@@ -45,12 +53,12 @@ RuntimeClass in the **node.k8s.io/v1beta1** API version will no longer be served
 
 The **v1.22** release will stop serving the following deprecated API versions:
 
-#### MutatingWebhookConfiguration and ValidatingWebhookConfiguration
+#### Webhook resources {#webhook-resources-v122}
 
 The **admissionregistration.k8s.io/v1beta1** API version of MutatingWebhookConfiguration and ValidatingWebhookConfiguration will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **admissionregistration.k8s.io/v1** API version, available since v1.16.
-* All existing persisted objects are accessible via the new API
+* All existing persisted objects are accessible via the new APIs
 * Notable changes:
     * `webhooks[*].failurePolicy` default changed from `Ignore` to `Fail` for v1
     * `webhooks[*].matchPolicy` default changed from `Exact` to `Equivalent` for v1
@@ -59,7 +67,7 @@ The **admissionregistration.k8s.io/v1beta1** API version of MutatingWebhookConfi
     * `webhooks[*].admissionReviewVersions` default value is removed and the field made required for v1 (supported versions for AdmissionReview are `v1` and `v1beta1`)
     * `webhooks[*].name` must be unique in the list for objects created via `admissionregistration.k8s.io/v1`
 
-#### CustomResourceDefinitions
+#### CustomResourceDefinition {#customresourcedefinition-v122}
 
 The **apiextensions.k8s.io/v1beta1** API version of CustomResourceDefinition will no longer be served in v1.22.
 
@@ -73,34 +81,34 @@ The **apiextensions.k8s.io/v1beta1** API version of CustomResourceDefinition wil
     * `spec.additionalPrinterColumns` is removed in v1; use `spec.versions[*].additionalPrinterColumns` instead
     * `spec.conversion.webhookClientConfig` is moved to `spec.conversion.webhook.clientConfig` in v1
     * `spec.conversion.conversionReviewVersions` is moved to `spec.conversion.webhook.conversionReviewVersions` in v1
-    * `spec.versions[*].schema.openAPIV3Schema` is now required when creating v1 CustomResourceDefinitions, and must be a [structural schema](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema)
-    * `spec.preserveUnknownFields: true` is disallowed when creating v1 CustomResourceDefinitions; it must be specified within schema definitions as `x-kubernetes-preserve-unknown-fields: true`
+    * `spec.versions[*].schema.openAPIV3Schema` is now required when creating v1 CustomResourceDefinition objects, and must be a [structural schema](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema)
+    * `spec.preserveUnknownFields: true` is disallowed when creating v1 CustomResourceDefinition objects; it must be specified within schema definitions as `x-kubernetes-preserve-unknown-fields: true`
     * In `additionalPrinterColumns` items, the `JSONPath` field was renamed to `jsonPath` in v1 (fixes [#66531](https://github.com/kubernetes/kubernetes/issues/66531))
 
-#### APIService
+#### APIService {#apiservice-v122}
 
 The **apiregistration.k8s.io/v1beta1** API version of APIService will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **apiregistration.k8s.io/v1** API version, available since v1.10.
 * All existing persisted objects are accessible via the new API
 * No notable changes
 
-#### TokenReview
+#### TokenReview {#tokenreview-v122}
 
 The **authentication.k8s.io/v1beta1** API version of TokenReview will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **authentication.k8s.io/v1** API version, available since v1.6.
 * No notable changes
 
-#### SubjectAccessReview
+#### SubjectAccessReview resources {#subjectaccessreview-resources-v122}
 
 The **authorization.k8s.io/v1beta1** API version of LocalSubjectAccessReview, SelfSubjectAccessReview, and SubjectAccessReview will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **authorization.k8s.io/v1** API version, available since v1.6.
 * Notable changes:
     * `spec.group` was renamed to `spec.groups` in v1 (fixes [#32709](https://github.com/kubernetes/kubernetes/issues/32709))
 
-#### CertificateSigningRequest
+#### CertificateSigningRequest {#certificatesigningrequest-v122}
 
 The **certificates.k8s.io/v1beta1** API version of CertificateSigningRequest will no longer be served in v1.22.
 
@@ -115,15 +123,15 @@ The **certificates.k8s.io/v1beta1** API version of CertificateSigningRequest wil
         * `status.conditions[*].status` is now required
         * `status.certificate` must be PEM-encoded, and contain only `CERTIFICATE` blocks
 
-#### Lease
+#### Lease {#lease-v122}
 
 The **coordination.k8s.io/v1beta1** API version of Lease will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **coordination.k8s.io/v1** API version, available since v1.14.
 * All existing persisted objects are accessible via the new API
 * No notable changes
 
-#### Ingress
+#### Ingress {#ingress-v122}
 
 The **extensions/v1beta1** and **networking.k8s.io/v1beta1** API versions of Ingress will no longer be served in v1.22.
 
@@ -136,31 +144,31 @@ The **extensions/v1beta1** and **networking.k8s.io/v1beta1** API versions of Ing
     * String backend `servicePort` fields are renamed to `service.port.name`
     * `pathType` is now required for each specified path. Options are `Prefix`, `Exact`, and `ImplementationSpecific`. To match the undefined `v1beta1` behavior, use `ImplementationSpecific`.
 
-#### IngressClass
+#### IngressClass {#ingressclass-v122}
 
 The **networking.k8s.io/v1beta1** API version of IngressClass will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **networking.k8s.io/v1** API version, available since v1.19.
 * All existing persisted objects are accessible via the new API
 * No notable changes
 
-#### RBAC
+#### RBAC resources {#rbac-resources-v122}
 
 The **rbac.authorization.k8s.io/v1beta1** API version of ClusterRole, ClusterRoleBinding, Role, and RoleBinding will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **networking.k8s.io/v1** API version, available since v1.8.
-* All existing persisted objects are accessible via the new API
+* All existing persisted objects are accessible via the new APIs
 * No notable changes
 
-#### PriorityClass
+#### PriorityClass {#priorityclass-v122}
 
 The **scheduling.k8s.io/v1beta1** API version of PriorityClass will no longer be served in v1.22.
 
 * Migrate manifests and API clients to use the **scheduling.k8s.io/v1** API version, available since v1.14.
 * All existing persisted objects are accessible via the new API
 * No notable changes
 
-#### Storage
+#### Storage resources {#storage-resources-v122}
 
 The **storage.k8s.io/v1beta1** API version of CSIDriver, CSINode, StorageClass, and VolumeAttachment will no longer be served in v1.22.
 
@@ -169,21 +177,21 @@ The **storage.k8s.io/v1beta1** API version of CSIDriver, CSINode, StorageClass,
   * CSINode is available in **storage.k8s.io/v1** since v1.17
   * StorageClass is available in **storage.k8s.io/v1** since v1.6
   * VolumeAttachment is available in **storage.k8s.io/v1** v1.13
-* All existing persisted objects are accessible via the new API
+* All existing persisted objects are accessible via the new APIs
 * No notable changes
 
 ### v1.16
 
 The **v1.16** release stopped serving the following deprecated API versions:
 
-#### NetworkPolicy
+#### NetworkPolicy {#networkpolicy-v116}
 
 The **extensions/v1beta1** API version of NetworkPolicy is no longer served as of v1.16.
 
 * Migrate manifests and API clients to use the **networking.k8s.io/v1** API version, available since v1.8.
 * All existing persisted objects are accessible via the new API
 
-#### DaemonSet
+#### DaemonSet {#daemonset-v116}
 
 The **extensions/v1beta1** and **apps/v1beta2** API versions of DaemonSet are no longer served as of v1.16.
 
@@ -194,7 +202,7 @@ The **extensions/v1beta1** and **apps/v1beta2** API versions of DaemonSet are no
     * `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
     * `spec.updateStrategy.type` now defaults to `RollingUpdate` (the default in `extensions/v1beta1` was `OnDelete`)
 
-#### Deployment
+#### Deployment {#deployment-v116}
 
 The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions of Deployment are no longer served as of v1.16.
 
@@ -207,7 +215,7 @@ The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions
     * `spec.revisionHistoryLimit` now defaults to `10` (the default in `apps/v1beta1` was `2`, the default in `extensions/v1beta1` was to retain all)
     * `maxSurge` and `maxUnavailable` now default to `25%` (the default in `extensions/v1beta1` was `1`)
 
-#### StatefulSet
+#### StatefulSet {#statefulset-v116}
 
 The **apps/v1beta1** and **apps/v1beta2** API versions of StatefulSet are no longer served as of v1.16.
 
@@ -217,7 +225,7 @@ The **apps/v1beta1** and **apps/v1beta2** API versions of StatefulSet are no lon
     * `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
     * `spec.updateStrategy.type` now defaults to `RollingUpdate` (the default in `apps/v1beta1` was `OnDelete`)
 
-#### ReplicaSet
+#### ReplicaSet {#replicaset-v116}
 
 The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions of ReplicaSet are no longer served as of v1.16.
 
@@ -226,17 +234,14 @@ The **extensions/v1beta1**, **apps/v1beta1**, and **apps/v1beta2** API versions
 * Notable changes:
     * `spec.selector` is now required and immutable after creation; use the existing template labels as the selector for seamless upgrades
 
-## What To Do
-
-Kubernetes 1.22 will be released later in 2021, so be sure to audit
-your configuration and integrations now!
+## What to do
 
 ### Test with deprecated APIs disabled
 
 You can test your clusters by starting an API server with specific API versions disabled
 to simulate upcoming removals. Add the following flag to the API server startup arguments:
 
-`--runtime-config=$group/$version=false`
+`--runtime-config=<group>/<version>=false`
 
 For example:
 
@@ -262,4 +267,4 @@ to locate use of deprecated APIs.
     `kubectl-convert -f ./my-deployment.yaml --output-version apps/v1`
 
     Note that this may use non-ideal default values. To learn more about a specific
-    resource, check the Kubernetes [api reference](https://kubernetes.io/docs/reference/#api-reference).
+    resource, check the Kubernetes [API reference](/docs/reference/kubernetes-api/).