Skip to content

Commit

Permalink
Add conversion doc (#473)
Browse files Browse the repository at this point in the history
Signed-off-by: Prajyot-Parab <[email protected]>
  • Loading branch information
Prajyot-Parab authored Dec 9, 2021
1 parent 277daf8 commit f55b82e
Show file tree
Hide file tree
Showing 3 changed files with 28 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
- [Creating a cluster](./topics/powervs/creating-a-cluster.md)
- [Developer Guide](./developer/index.md)
- [Rapid iterative development with Tilt](./developer/tilt.md)
- [Guide for API conversions](./developer/conversion.md)
- [Release Process](./developer/release.md)
- [Troubleshooting](./user/troubleshooting.md)
- [Reference](./reference/reference.md)
26 changes: 26 additions & 0 deletions docs/book/src/developer/conversion.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Guide for API conversions

## Introduction
The purpose of this document is to help/assist contributors with future API conversions using conversion-gen tool.

## Prerequisites
1. Create a new API version.
```shell
kubebuilder create api --group <group> --version <version> --kind <kind>
```
2. Copy over existing types, and make the required changes.
3. Mark a storage version, add marker `+kubebuilder:storageversion` to concerned version package.

**_NOTE:_** [Refer for more detailed information about prerequisites.](https://kubebuilder.io/multiversion-tutorial/api-changes.html#changing-things-up)

## Conversion flow
1. In each “spoke” version package, add marker `+k8s:conversion-gen` directive pointing to the “hub” version package. It must be in `doc.go`. [Refer](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/blob/main/api/v1alpha4/doc.go)
2. In “hub” version package, create `doc.go` file without any marker. [Refer](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/blob/main/api/v1beta1/doc.go)
3. In “spoke” version package, add a var `localSchemeBuilder = &SchemeBuilder.SchemeBuilder` in `groupversion_info.go` so the auto-generated code would compile. [Refer]( https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/blob/e55357a520089abc6ac2a9ca91a5b9cf0606bbbc/api/v1alpha4/groupversion_info.go#L37)
4. In “hub” version package, create a `conversion.go` to implement the “hub” methods. [Refer](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/blob/main/api/v1beta1/conversion.go)
5. Run target `make generate-go-conversions-core`, this will generate `zz_generated.conversion.go` in the spoke version package.
6. In "spoke" version package, update `{kind}_conversion.go` to implement Convertible for each type. When `conversion-gen` stops generating methods because of incompatibilities or we need to override the behavior, we stick them in this source file. Our “spoke” versions need to implement the Convertible interface. Namely, they’ll need ConvertTo and ConvertFrom methods to convert to/from the hub version. [Refer](https://github.com/kubernetes-sigs/cluster-api-provider-ibmcloud/blob/main/api/v1alpha4/ibmpowervs_conversion.go)

## References
- [What are hubs and spokes?](https://book.kubebuilder.io/multiversion-tutorial/conversion-concepts.html)
- [Sample Tutorial](https://book.kubebuilder.io/multiversion-tutorial/tutorial.html)
1 change: 1 addition & 0 deletions docs/book/src/developer/index.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Developer Guide

- [Rapid iterative development with Tilt](/developer/tilt.html)
- [Guide for API conversions](/developer/conversion.html)
- [Release process](/developer/release.html)

0 comments on commit f55b82e

Please sign in to comment.