API Versioning

Adding a new API version to a Pipelines CRD

1. Read the Kubernetes documentation on versioning CRDs, especially the section on specifying multiple versions

2. If needed, create a new folder for the new API version under pkg/apis/pipeline. Update codegen scripts in the "hack" folder to generate client code for the Go structs in the new folder. Example: #5055

   • Codegen scripts will not work correctly if there are no CRDs in the new folder, but you do not need to add the full Go definitions of the new CRDs.
   • Knative uses annotations on the Go structs to determine what code to generate. For example, you must annotate a struct with "// +k8s:openapi-gen=true" for OpenAPI schema generation.

3. Add Go struct types for the new API version. Example: #5125

   • Consider moving any logic unrelated to the API out of pkg/apis/pipeline so it's not duplicated in the new folder.
   • Once this code is merged, the code in pkg/apis/pipeline will need to be kept in sync between the two API versions until we are ready to serve the new API version to users.

4. Implement apis.Convertible for the old API version. Example: #5202

   • Knative uses this function to generate conversion code between API versions.
   • Prefer duplicating Go structs in the new type over using type aliases. Once we move to supporting a new API version, we don't want to make changes to the old one.
   • Before changing the stored version of the CRD to the newer version, you must implement conversion for deprecated fields. This is because resources that were created with earlier stored versions will use the current stored version when they're updated. Deprecated fields can be serialized to a CRD's annotations. Example: #5253

5. Add the new versions to the webhook and the CRD. Example: #5234

6. Switch the "storage" version of the CRD to the new API version, and update the reconciler code to use this API version. Example: #2577

7. Update examples and documentation to use the new API version.

8. Existing objects are persisted using the storage version at the time they were created. One way to upgrade them to the new stored version is to write a StorageVersionMigrator, although we have not previously done this.