1# api
2The canonical location of the OpenShift API definition. This repo holds the API type definitions and serialization code used by [openshift/client-go](https://github.com/openshift/client-go)
3
4## defining new APIs
5
6When defining a new API, please follow [the OpenShift API
7conventions](https://github.com/openshift/enhancements/blob/master/CONVENTIONS.md#api),
8and then follow the instructions below to regenerate CRDs (if necessary) and
9submit a pull request with your new API definitions and generated files.
10
11### required labels
12
13In addition to the standard `lgtm` and `approved` labels this repository requires either:
14
15`bugzilla/valid-bug` - applied if your PR references a valid bugzilla bug
16
17OR
18
19`qe-approved`, `docs-approved`, and `px-approved` - these labels can be applied by anyone in the openshift org via the `/label` command.
20
21Who should apply these qe/docs/px labels?
22- For a no-FF team who is merging a feature before code freeze, they need to get those labels applied to their api repo PR by the appropriate teams (i.e. qe, docs, px)
23- For a FF(traditional) team who is merging a feature before FF, they can self-apply the labels(via /label commands), they are basically irrelevant for those teams
24- For a FF team who is merging a feature after FF, the PR should be rejected barring an exception
25
26Why are these labels needed?
27
28We need a way for no-FF teams to be able to merge post-FF that does not require a BZ. For non-shared repos that mechanism is the
29qe/docs/px-approved labels. We are expanding that mechanism to shared repos because the alternative would be that no-FF teams would
30put a dummy `bugzilla/valid-bug` label on their feature PRs in order to be able to merge them after feature freeze. Since most
31individuals can't apply a `bugzilla/valid-bug` label to a PR, this introduces additional obstacles on those PRs. Conversely, anyone
32can apply the docs/qe/px-approved labels, so "FF" teams that need to apply these labels to merge can do so w/o needing to involve
33anyone additional.
34
35Does this mean feature-freeze teams can use the no-FF process to merge code?
36
37No, signing a team up to be a no-FF team includes some basic education on the process and includes ensuring the associated QE+Docs
38participants are aware the team is moving to that model. If you'd like to sign your team up, please speak with Gina Hargan who will
39be happy to help on-board your team.
40
41## generating CRD schemas
42
43Since 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`. Moreover, schemas ensure structural consistency of data in etcd. Without it anything can be stored in a resource which can have security implications. 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.
44
45These schemas are often very long and complex, and should not be written by hand. For OpenShift, we provide Makefile targets in [build-machinery-go](https://github.com/openshift/build-machinery-go/) which generate the schema, built on upstream's [controller-gen](https://github.com/kubernetes-sigs/controller-tools) tool.
46
47If you make a change to a CRD type in this repo, simply calling `make update-codegen-crds` should regenerate all CRDs and update the manifests. 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).
48
49To add this generator to another repo:
501. Vendor `github.com/openshift/build-machinery-go`
51
522. Update your `Makefile` to include the following:
53```
54include $(addprefix ./vendor/github.com/openshift/build-machinery-go/make/, \
55 targets/openshift/crd-schema-gen.mk \
56)
57
58$(call add-crd-gen,<TARGET_NAME>,<API_DIRECTORY>,<CRD_MANIFESTS>,<MANIFEST_OUTPUT>)
59```
60The parameters for the call are:
61
621. `TARGET_NAME`: The name of your generated Make target. This can be anything, as long as it does not conflict with another make target. Recommended to be your api name.
632. `API_DIRECTORY`: The location of your API. For example if your Go types are located under `pkg/apis/myoperator/v1/types.go`, this should be `./pkg/apis/myoperator/v1`.
643. `CRD_MANIFESTS`: The directory your CRDs are located in. For example, if that is `manifests/my_operator.crd.yaml` then it should be `./manifests`
654. `MANIFEST_OUTPUT`: This should most likely be the same as `CRD_MANIFESTS`, and is only provided for flexibility to output generated code to a different directory.
66
67You can include as many calls to different APIs as necessary, or if you have multiple APIs under the same directory (eg, `v1` and `v2beta1`) you can use 1 call to the parent directory pointing to your API.
68
69After this, calling `make update-codegen-crds` should generate a new structural OpenAPIV3 schema for your CRDs.
70
71**Notes**
72- This will not generate entire CRDs, only their OpenAPIV3 schemas. If you do not already have a CRD, you will get no output from the generator.
73- Ensure that your API is correctly declared for the generator to pick it up. That means, in your `doc.go`, include the following:
74 1. `// +groupName=<API_GROUP_NAME>`, this should match the `group` in your CRD `spec`
75 2. `// +kubebuilder:validation:Optional`, this tells the operator that fields should be optional unless explicitly marked with `// +kubebuilder:validation:Required`
76
77For more information on the API markers to add to your Go types, see the [Kubebuilder book](https://book.kubebuilder.io/reference/markers.html)
78
79### Post-schema-generation Patches
80
81Schema generation features might be limited or fall behind what CRD schemas supports in the latest Kubernetes version.
82To work around this, there are two patch mechanisms implemented by the `add-crd-gen` target. Basic idea is that you
83place a patch file next to the CRD yaml manifest with either `yaml-merge-patch` or `yaml-patch` as extension,
84but with the same base name. The `update-codegen-crds` Makefile target will apply these **after** calling
85kubebuilder's controller-gen:
86
87- `yaml-merge-patch`: these are applied via `yq m -x <yaml-file> <patch-file>` compare https://mikefarah.gitbook.io/yq/commands/merge#overwrite-values.
88- `yaml-patch`: these are applied via `yaml-patch -o <patch-file> < <yaml-file>` using https://github.com/krishicks/yaml-patch.
View as plain text