mirror of https://github.com/kubernetes/kops.git
30 lines
1.8 KiB
Markdown
30 lines
1.8 KiB
Markdown
# API machinery
|
|
|
|
kOps uses the Kubernetes API machinery. It is well designed, and very powerful, but you have to
|
|
jump through some hoops to use it.
|
|
|
|
Recommended reading: [kubernetes API convention doc](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) and [kubernetes API changes doc](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md).
|
|
|
|
The kOps APIs live in [pkg/apis/kops](https://github.com/kubernetes/kops/tree/master/pkg/apis/kops), both in
|
|
that directory directly (the unversioned API) and in the versioned subdirectories (`v1alpha2`, `v1alpha3`).
|
|
|
|
## Updating the generated API code
|
|
|
|
To generate the API code simply run `make apimachinery && make crds && make` to update the generated API machinery code (conversion functions). Note
|
|
that `make apimachinery` and `make crds` (currently) only update the autogenerated code; it does not trigger a rebuild, hence the
|
|
need for `&& make`.
|
|
|
|
## Adding a field
|
|
|
|
The most common task you will do will be to add a new field. This is relatively straightforward, because
|
|
it is backwards compatible (you have to make sure that the field is optional).
|
|
|
|
* Add the field to pkg/apis/kops, and then also to each versioned copy: pkg/apis/kops/v1alpha2, pkg/apis/kops/v1alpha3, etc
|
|
* Run the apimachinery update as above (`make apimachinery && make crds && make`)
|
|
* You likely want to update the validation logic
|
|
* You likely want to update the defaulting logic
|
|
|
|
Currently, the apimachinery code we check in is relatively stable. However, when the generated code is large,
|
|
it is often considered good manners to your code reviewer to split a PR into multiple commits: one with the
|
|
actual changes, and then a second commit with the autogenerated code.
|