Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Publish CRD OpenAPI Documentation #12910

Merged
merged 2 commits into from
Mar 15, 2019
Merged

Publish CRD OpenAPI Documentation #12910

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
27c721f
add documentation for CustomResourcePublishOpenAPI
roycaihw Feb 28, 2019
bdc6e7c
address comments
roycaihw Mar 15, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions ...ocs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -347,6 +347,58 @@ kubectl create -f my-crontab.yaml
crontab "my-new-cron-object" created
```

### Publish Validation Schema in OpenAPI v2

{{< feature-state state="alpha" for_kubernetes_version="1.14" >}}

Starting with Kubernetes 1.14, [custom resource validation schema](#validation) can be published as part
of [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions) from
Kubernetes API server.
roycaihw marked this conversation as resolved.
Show resolved Hide resolved

[kubectl](/docs/reference/kubectl/overview) consumes the published schema to perform client-side validation
(`kubectl create` and `kubectl apply`), schema explanation (`kubectl explain`) on custom resources.
The published schema can be consumed for other purposes. The feature is Alpha in 1.14 and disabled by default.
You can enable the feature using the `CustomResourcePublishOpenAPI` feature gate on the
[kube-apiserver](/docs/admin/kube-apiserver):

```
--feature-gates=CustomResourcePublishOpenAPI=true
```

Custom resource validation schema will be converted to OpenAPI v2 schema, and
show up in `definitions` and `paths` fields in the [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions).
The following modifications are applied during the conversion to keep backwards compatiblity with
kubectl in previous 1.13 version. These modifications prevent kubectl from being over-strict and rejecting
valid OpenAPI schemas that it doesn't understand. The conversion won't modify the validation schema defined in CRD,
and therefore won't affect [validation](#validation) in the API server.

1. The following fields are removed as they aren't supported by OpenAPI v2 (in future versions OpenAPI v3 will be used without these restrictions)
- The fields `oneOf`, `anyOf` and `not` are removed
2. The following fields are removed as they aren't allowed by kubectl in
previous 1.13 version
- For a schema with a `$ref`
- the fields `properties` and `type` are removed
- if the `$ref` is outside of the `definitions`, the field `$ref` is removed
- For a schema of a primitive data type (which means the field `type` has two elements: one type and one format)
- if any one of the two elements is `null`, the field `type` is removed
- otherwise, the fields `type` and `properties` are removed
- For a schema of more than two types
- the fields `type` and `properties` are removed
- For a schema of `null` type
- the field `type` is removed
- For a schema of `array` type
- if the schema doesn't have exactly one item, the fields `type` and `items` are
removed
- For a schema with no type specified
- the field `properties` is removed
3. The following fields are removed as they aren't supported by the OpenAPI protobuf implementation
Copy link
Contributor

@cody-clark cody-clark Mar 15, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is hard to read or scan. I'll approve this once the nits and lists are fixed, but I'd like to come up with a plan to organize this info better after the release.

I threw something together that kind of does, but it doesn't render the best on k8s.io because the inline code backticks are the same color as the alternating table cells.

Thoughts? Other ideas?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cody-clark thanks for the suggestion. The table looks much better!

I'm not super concerned about the color, as long as we can tell the difference between code and the rest part of the sentence (bold can do the trick)

I'm concerned about the expressiveness of the table. e.g

  • For a schema with a $ref (the $ref field in the schema object is defined)
  • For a schema of null type (the type field in the schema object is defined and the value is null)

reads differently from

Schema with
$ref
null

I'll think more about how to use table to arrange this section

- The fields `id`, `schema`, `definitions`, `additionalItems`, `dependencies`,
and `patternProperties` are removed
- For a schema with a `externalDocs`
- if the `externalDocs` has `url` defined, the field `externalDocs` is removed
- For a schema with `items` defined
- if the field `items` has multiple schemas, the field `items` is removed

### Additional printer columns

Starting with Kubernetes 1.11, kubectl uses server-side printing. The server decides which
Expand Down