Merge pull request #19459 from AliMirlou/patch-1

Minor refactor and typo fix of Custom Resources topic

content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md

@@ -19,7 +19,7 @@ methods for adding custom resources and how to choose between them.
 ## Custom resources
 
 A *resource* is an endpoint in the [Kubernetes API](/docs/reference/using-api/api-overview/) that stores a collection of
-[API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a certain kind. For example, the built-in *pods* resource contains a collection of Pod objects.
+[API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a certain kind; for example, the built-in *pods* resource contains a collection of Pod objects.
 
 A *custom resource* is an extension of the Kubernetes API that is not necessarily available in a default
 Kubernetes installation. It represents a customization of a particular Kubernetes installation. However,
@@ -81,7 +81,7 @@ Signs that your API might not be declarative include:
  - The client says "do this", and then gets a synchronous response back when it is done.
  - The client says "do this", and then gets an operation ID back, and has to check a separate Operation object to determine completion of the request.
  - You talk about Remote Procedure Calls (RPCs).
- - Directly storing large amounts of data (e.g. > a few kB per object, or >1000s of objects).
+ - Directly storing large amounts of data; for example, > a few kB per object, or > 1000s of objects.
  - High bandwidth access (10s of requests per second sustained) needed.
  - Store end-user data (such as images, PII, etc.) or other large-scale data processed by applications.
  - The natural operations on the objects are not CRUD-y.
@@ -105,7 +105,7 @@ Use a [secret](/docs/concepts/configuration/secret/) for sensitive data, which i
 Use a custom resource (CRD or Aggregated API) if most of the following apply:
 
 * You want to use Kubernetes client libraries and CLIs to create and update the new resource.
-* You want top-level support from kubectl (for example: `kubectl get my-object object-name`).
+* You want top-level support from `kubectl`; for example, `kubectl get my-object object-name`.
 * You want to build new automation that watches for updates on the new object, and then CRUD other objects, or vice versa.
 * You want to write automation that handles updates to the object.
 * You want to use Kubernetes API conventions like `.spec`, `.status`, and `.metadata`.
@@ -120,9 +120,9 @@ Kubernetes provides two ways to add custom resources to your cluster:
 
 Kubernetes provides these two options to meet the needs of different users, so that neither ease of use nor flexibility is compromised.
 
-Aggregated APIs are subordinate APIServers that sit behind the primary API server, which acts as a proxy. This arrangement is called [API Aggregation](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) (AA). To users, it simply appears that the Kubernetes API is extended.
+Aggregated APIs are subordinate API servers that sit behind the primary API server, which acts as a proxy. This arrangement is called [API Aggregation](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) (AA). To users, it simply appears that the Kubernetes API is extended.
 
-CRDs allow users to create new types of resources without adding another APIserver. You do not need to understand API Aggregation to use CRDs.
+CRDs allow users to create new types of resources without adding another API server. You do not need to understand API Aggregation to use CRDs.
 
 Regardless of how they are installed, the new resources are referred to as Custom Resources to distinguish them from built-in Kubernetes resources (like pods).
 
@@ -168,42 +168,42 @@ CRDs are easier to create than Aggregated APIs.
 | CRDs                        | Aggregated API |
 | --------------------------- | -------------- |
 | Do not require programming. Users can choose any language for a CRD controller. | Requires programming in Go and building binary and image. |
-| No additional service to run; CRs are handled by API Server. | An additional service to create and that could fail. |
-| No ongoing support once the CRD is created. Any bug fixes are picked up as part of normal Kubernetes Master upgrades. | May need to periodically pickup bug fixes from upstream and rebuild and update the Aggregated APIserver. |
-| No need to handle multiple versions of your API. For example: when you control the client for this resource, you can upgrade it in sync with the API. | You need to handle multiple versions of your API, for example: when developing an extension to share with the world. |
+| No additional service to run; CRDs are handled by API server. | An additional service to create and that could fail. |
+| No ongoing support once the CRD is created. Any bug fixes are picked up as part of normal Kubernetes Master upgrades. | May need to periodically pickup bug fixes from upstream and rebuild and update the Aggregated API server. |
+| No need to handle multiple versions of your API; for example, when you control the client for this resource, you can upgrade it in sync with the API. | You need to handle multiple versions of your API; for example, when developing an extension to share with the world. |
 
 ### Advanced features and flexibility
 
-Aggregated APIs offer more advanced API features and customization of other features, for example: the storage layer.
+Aggregated APIs offer more advanced API features and customization of other features; for example, the storage layer.
 
 | Feature | Description | CRDs | Aggregated API |
 | ------- | ----------- | ---- | -------------- |
 | Validation | Help users prevent errors and allow you to evolve your API independently of your clients. These features are most useful when there are many clients who can't all update at the same time. | Yes.  Most validation can be specified in the CRD using [OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation).  Any other validations supported by addition of a [Validating Webhook](/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook-alpha-in-1-8-beta-in-1-9). | Yes, arbitrary validation checks |
-| Defaulting | See above | Yes, either via [OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#defaulting) `default` keyword (GA in 1.17), or via a [Mutating Webhook](/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) (though this will not be run when reading from etcd for old objects) | Yes |
+| Defaulting | See above | Yes, either via [OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#defaulting) `default` keyword (GA in 1.17), or via a [Mutating Webhook](/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) (though this will not be run when reading from etcd for old objects). | Yes |
 | Multi-versioning | Allows serving the same object through two API versions. Can help ease API changes like renaming fields. Less important if you control your client versions. | [Yes](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning) | Yes |
-| Custom Storage | If you need storage with a different performance mode (for example, time-series database instead of key-value store) or isolation for security (for example, encryption secrets or different | No | Yes |
+| Custom Storage | If you need storage with a different performance mode (for example, time-series database instead of key-value store) or isolation for security (for example, encryption secrets or different) | No | Yes |
 | Custom Business Logic | Perform arbitrary checks or actions when creating, reading, updating or deleting an object | Yes, using [Webhooks](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks). | Yes |
 | Scale Subresource | Allows systems like HorizontalPodAutoscaler and PodDisruptionBudget interact with your new resource | [Yes](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#scale-subresource)  | Yes |
 | Status Subresource | Allows fine-grained access control where user writes the spec section and the controller writes the status section. Allows incrementing object Generation on custom resource data mutation (requires separate spec and status sections in the resource) | [Yes](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#status-subresource) | Yes |
 | Other Subresources | Add operations other than CRUD, such as "logs" or "exec". | No | Yes |
 | strategic-merge-patch | The new endpoints support PATCH with `Content-Type: application/strategic-merge-patch+json`. Useful for updating objects that may be modified both locally, and by the server. For more information, see ["Update API Objects in Place Using kubectl patch"](/docs/tasks/run-application/update-api-object-kubectl-patch/) | No | Yes |
 | Protocol Buffers | The new resource supports clients that want to use Protocol Buffers | No | Yes |
-| OpenAPI Schema | Is there an OpenAPI (swagger) schema for the types that can be dynamically fetched from the server? Is the user protected from misspelling field names by ensuring only allowed fields are set? Are types enforced (in other words, don't put an `int` in a `string` field?) | Yes, based on the [OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation) schema (GA in 1.16) | Yes |
+| OpenAPI Schema | Is there an OpenAPI (swagger) schema for the types that can be dynamically fetched from the server? Is the user protected from misspelling field names by ensuring only allowed fields are set? Are types enforced (in other words, don't put an `int` in a `string` field?) | Yes, based on the [OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation) schema (GA in 1.16). | Yes |
 
 ### Common Features
 
-When you create a custom resource, either via a CRDs or an AA, you get many features for your API, compared to implementing it outside the Kubernetes platform:
+When you create a custom resource, either via a CRD or an AA, you get many features for your API, compared to implementing it outside the Kubernetes platform:
 
 | Feature | What it does |
 | ------- | ------------ |
 | CRUD | The new endpoints support CRUD basic operations via HTTP and `kubectl` |
 | Watch | The new endpoints support Kubernetes Watch operations via HTTP |
-| Discovery | Clients like kubectl and dashboard automatically offer list, display, and field edit operations on your resources |
+| Discovery | Clients like `kubectl` and dashboard automatically offer list, display, and field edit operations on your resources |
 | json-patch | The new endpoints support PATCH with `Content-Type: application/json-patch+json` |
 | merge-patch | The new endpoints support PATCH with `Content-Type: application/merge-patch+json` |
 | HTTPS | The new endpoints uses HTTPS |
-| Built-in Authentication | Access to the extension uses the core apiserver (aggregation layer) for authentication |
-| Built-in Authorization | Access to the extension can reuse the authorization used by the core apiserver (e.g. RBAC) |
+| Built-in Authentication | Access to the extension uses the core API server (aggregation layer) for authentication |
+| Built-in Authorization | Access to the extension can reuse the authorization used by the core API server; for example, RBAC. |
 | Finalizers | Block deletion of extension resources until external cleanup happens. |
 | Admission Webhooks | Set default values and validate extension resources during any create/update/delete operation. |
 | UI/CLI Display | Kubectl, dashboard can display extension resources. |
@@ -219,7 +219,7 @@ There are several points to be aware of before adding a custom resource to your
 
 While creating a CRD does not automatically add any new points of failure (for example, by causing third party code to run on your API server), packages (for example, Charts) or other installation bundles often include CRDs as well as a Deployment of third-party code that implements the business logic for a new custom resource.
 
-Installing an Aggregated APIserver always involves running a new Deployment.
+Installing an Aggregated API server always involves running a new Deployment.
 
 ### Storage
 
@@ -229,19 +229,19 @@ Aggregated API servers may use the same storage as the main API server, in which
 
 ### Authentication, authorization, and auditing
 
-CRDs always use the same authentication, authorization, and audit logging as the built-in resources of your API Server.
+CRDs always use the same authentication, authorization, and audit logging as the built-in resources of your API server.
 
 If you use RBAC for authorization, most RBAC roles will not grant access to the new resources (except the cluster-admin role or any role created with wildcard rules). You'll need to explicitly grant access to the new resources. CRDs and Aggregated APIs often come bundled with new role definitions for the types they add.
 
 Aggregated API servers may or may not use the same authentication, authorization, and auditing as the primary API server.
 
 ## Accessing a custom resource
 
-Kubernetes [client libraries](/docs/reference/using-api/client-libraries/) can be used to access custom resources. Not all client libraries support custom resources. The go and python client libraries do.
+Kubernetes [client libraries](/docs/reference/using-api/client-libraries/) can be used to access custom resources. Not all client libraries support custom resources. The _Go_ and _Python_ client libraries do.
 
 When you add a custom resource, you can access it using:
 
-- kubectl
+- `kubectl`
 - The kubernetes dynamic client.
 - A REST client that you write.
 - A client generated using [Kubernetes client generation tools](https://github.com/kubernetes/code-generator) (generating one is an advanced undertaking, but some projects may provide a client along with the CRD or AA).