diff --git a/content/en/docs/concepts/api-extension/custom-resources.md b/content/en/docs/concepts/api-extension/custom-resources.md index 44efe01a71..f65985e474 100644 --- a/content/en/docs/concepts/api-extension/custom-resources.md +++ b/content/en/docs/concepts/api-extension/custom-resources.md @@ -37,7 +37,7 @@ A *custom controller* is a controller that users can deploy and update on a runn When creating a new API, consider whether to [aggregate your API with the Kubernetes cluster APIs](/docs/concepts/api-extension/apiserver-aggregation/) or let your API stand alone. | Consider API aggregation if: | Prefer a stand-alone API if: | -|-|-| +| ---------------------------- | ---------------------------- | | Your API is [Declarative](#declarative-apis). | Your API does not fit the [Declarative](#declarative-apis) model. | | You want your new types to be readable and writable using `kubectl`.| `kubectl` support is not required | | You want to view your new types in a Kubernetes UI, such as dashboard, alongside built-in types. | Kubernetes UI support is not required. | @@ -49,6 +49,7 @@ When creating a new API, consider whether to [aggregate your API with the Kubern #### Declarative APIs In a Declarative API, typically: + - Your API consists of a relatively small number of relatively small objects (resources). - The objects define configuration of applications or infrastructure. - The objects are updated relatively infrequently. @@ -58,6 +59,7 @@ In a Declarative API, typically: Imperative APIs are not declarative. 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 objects to determine completion of the request. - You talk about Remote Procedure Calls (RPCs). @@ -145,7 +147,7 @@ Typically, CRDs are a good fit if: CRDs are easier to create than Aggregated APIs. | Custom Resource Definitions | Aggregated API | -|-|-| +| --------------------------- | -------------- | | Do not require programming. Users can choose any language for a CRD controller. | Requires programming in Go and building binary and image. Users can choose any language for a CRD controller. | | 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. | @@ -156,13 +158,13 @@ CRDs are easier to create than Aggregated APIs. 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. | Beta feature of CRDs in v1.9. Checks limited to what is supported by OpenAPI v3.0. | Yes, arbitrary validation checks | | Defaulting | See above | No, but can achieve the same effect with an Initializer (requires programming) | 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. | 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 | No, but can get some of the same effects with Initializers or Finalizers (requires programming) | Yes | -| Subresources | {::nomarkdown}{:/} | No but planned | Yes, any Subresource | +| Subresources | | No but planned | Yes, any Subresource | | 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?) | No but planned | Yes | @@ -172,7 +174,7 @@ Aggregated APIs offer more advanced API features and customization of other feat 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: | 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 | @@ -217,10 +219,11 @@ Aggregated API servers may or may not use the same authentication, authorization Kubernetes [client libraries](/docs/reference/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 - - 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). + +- 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). {{% /capture %}}