Bug 1798482: Add CRD generator documentation to Readme #573

damemi · 2020-01-22T18:07:08Z

Adds information, links, and steps to set up and use the crd schema generator

Fixes #572
/cc @dhellmann

dhellmann

This seems very clear. Thank you!

damemi · 2020-01-22T21:17:26Z

cc @smarterclayton @sttts could you please review?

sttts · 2020-01-29T09:47:11Z

README.md

+
+## generating CRD schemas
+
+Since Kubernetes 1.16, every CRD created in `apiextensions.k8s.io/v1` is required to have a [structural OpenAPIV3 schema](https://kubernetes.io/blog/2019/06/20/crd-structural-schema/). The schemas provide server-side validation for fields, as well as providing the descriptions for `oc explain`. Structural requirements build on that to provide enhanced security in objects' persistence in etcd. As we host many of our CRDs in this repo along with their corresponding Go types we also require them to have schemas. However, the following instructions apply for CRDs that are not hosted here as well.


Structural requirements build on that to provide enhanced security in objects' persistence in etcd

Not sure I can follow. You mean: "Moreover, schemas ensure structural consistency of data in etcd. Without anything can be stored in a resource which can have security implications."

sttts · 2020-01-29T09:48:04Z

README.md

+
+These schemas are often very long and complex, and should not be written by hand. For OpenShift, we provide Makefile targets in [library-go's alpha-build-machinery](https://github.com/openshift/library-go/tree/master/alpha-build-machinery) which generate the schema.
+
+If you make a change to a CRD type in this repo, simply calling `make update-codegen-crds` should regenerate all CRDs. If yours is not updated, ensure that the path to its API is included in our [calls to the Makefile targets](https://github.com/openshift/api/blob/release-4.5/Makefile#L17-L29).


regenerate all CRD schemas and update the manifests.

sttts · 2020-01-29T09:48:46Z

README.md

+
+Since Kubernetes 1.16, every CRD created in `apiextensions.k8s.io/v1` is required to have a [structural OpenAPIV3 schema](https://kubernetes.io/blog/2019/06/20/crd-structural-schema/). The schemas provide server-side validation for fields, as well as providing the descriptions for `oc explain`. Structural requirements build on that to provide enhanced security in objects' persistence in etcd. As we host many of our CRDs in this repo along with their corresponding Go types we also require them to have schemas. However, the following instructions apply for CRDs that are not hosted here as well.
+
+These schemas are often very long and complex, and should not be written by hand. For OpenShift, we provide Makefile targets in [library-go's alpha-build-machinery](https://github.com/openshift/library-go/tree/master/alpha-build-machinery) which generate the schema.


would reference controller-tools as well as the tool behind all of this.

damemi · 2020-01-29T15:06:39Z

@sttts thanks for your review, I've added the changes you suggested

sttts · 2020-01-30T09:27:07Z

/lgtm
/approve

openshift-ci-robot · 2020-01-30T09:27:30Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: damemi, sttts

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [sttts]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

openshift-ci-robot · 2020-02-05T13:18:36Z

@damemi: This pull request references Bugzilla bug 1798482, which is valid. The bug has been moved to the POST state. The bug has been updated to refer to the pull request using the external bug tracker.

Details

In response to this:

Bug 1798482: Add CRD generator documentation to Readme

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

openshift-ci-robot · 2020-02-05T13:30:48Z

@damemi: All pull requests linked via external trackers have merged. Bugzilla bug 1798482 has been moved to the MODIFIED state.

Details

In response to this:

Bug 1798482: Add CRD generator documentation to Readme

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

In particular, to get openshift/api#585: config: disable IPv6DualStack feature flag so we don't launch kube-controller-manager with that (still-broken) feature Also includes: openshift/api#557: create the IBMCLoudPlatform type for the ingress operator try2 openshift/api#570: Clarify image config doc openshift/api#569: Enable overriding service account issuer for bound tokens openshift/api#527: Add kubebuilder annotations to the network types openshift/api#574: add deprecaction notice for build pipeline strategy openshift/api#582: config/v1/types_proxy: Clarify trustedCA semantics openshift/api#583: Clarify FROM behavior in builds openshift/api#573: Add CRD generator documentation to Readme openshift/api#576: Remove Description from CLI output to improve its display openshift/api#589: Add missing enum validations openshift/api#583: operator/ingress: add dnsrecord type

openshift-ci-robot requested a review from dhellmann January 22, 2020 18:07

openshift-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Jan 22, 2020

dhellmann reviewed Jan 22, 2020

View reviewed changes

sttts reviewed Jan 29, 2020

View reviewed changes

Add CRD generator documentation to Readme

7433396

damemi force-pushed the document-crd-gen branch from 1a46271 to 7433396 Compare January 29, 2020 15:06

openshift-ci-robot assigned sttts Jan 30, 2020

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Jan 30, 2020

openshift-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jan 30, 2020

damemi changed the title ~~Add CRD generator documentation to Readme~~ Bug 1798482: Add CRD generator documentation to Readme Feb 5, 2020

openshift-ci-robot added the bugzilla/valid-bug Indicates that a referenced Bugzilla bug is valid for the branch this PR is targeting. label Feb 5, 2020

openshift-merge-robot merged commit 34f0ec8 into openshift:master Feb 5, 2020

danwinship mentioned this pull request Mar 2, 2020

Bug 1809368: bump openshift/api to remove IPv6DualStack feature flag openshift/cluster-kube-controller-manager-operator#355

Closed

soltysh mentioned this pull request Mar 4, 2020

Bug 1809368: bump openshift/api to remove IPv6DualStack feature flag openshift/cluster-kube-controller-manager-operator#359

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bug 1798482: Add CRD generator documentation to Readme #573

Bug 1798482: Add CRD generator documentation to Readme #573

Uh oh!

damemi commented Jan 22, 2020

Uh oh!

dhellmann left a comment

Uh oh!

damemi commented Jan 22, 2020

Uh oh!

sttts Jan 29, 2020

Uh oh!

sttts Jan 29, 2020

Uh oh!

sttts Jan 29, 2020

Uh oh!

damemi commented Jan 29, 2020

Uh oh!

sttts commented Jan 30, 2020

Uh oh!

openshift-ci-robot commented Jan 30, 2020

Uh oh!

openshift-ci-robot commented Feb 5, 2020

Uh oh!

openshift-ci-robot commented Feb 5, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		## generating CRD schemas

		Since Kubernetes 1.16, every CRD created in `apiextensions.k8s.io/v1` is required to have a [structural OpenAPIV3 schema](https://kubernetes.io/blog/2019/06/20/crd-structural-schema/). The schemas provide server-side validation for fields, as well as providing the descriptions for `oc explain`. Structural requirements build on that to provide enhanced security in objects' persistence in etcd. As we host many of our CRDs in this repo along with their corresponding Go types we also require them to have schemas. However, the following instructions apply for CRDs that are not hosted here as well.


		These schemas are often very long and complex, and should not be written by hand. For OpenShift, we provide Makefile targets in [library-go's alpha-build-machinery](https://github.com/openshift/library-go/tree/master/alpha-build-machinery) which generate the schema.

		If you make a change to a CRD type in this repo, simply calling `make update-codegen-crds` should regenerate all CRDs. If yours is not updated, ensure that the path to its API is included in our [calls to the Makefile targets](https://github.com/openshift/api/blob/release-4.5/Makefile#L17-L29).

Bug 1798482: Add CRD generator documentation to Readme #573

Bug 1798482: Add CRD generator documentation to Readme #573

Uh oh!

Conversation

damemi commented Jan 22, 2020

Uh oh!

dhellmann left a comment

Choose a reason for hiding this comment

Uh oh!

damemi commented Jan 22, 2020

Uh oh!

sttts Jan 29, 2020

Choose a reason for hiding this comment

Uh oh!

sttts Jan 29, 2020

Choose a reason for hiding this comment

Uh oh!

sttts Jan 29, 2020

Choose a reason for hiding this comment

Uh oh!

damemi commented Jan 29, 2020

Uh oh!

sttts commented Jan 30, 2020

Uh oh!

openshift-ci-robot commented Jan 30, 2020

Uh oh!

openshift-ci-robot commented Feb 5, 2020

Uh oh!

openshift-ci-robot commented Feb 5, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants