Document how to make changes to APIs (e.g. v1 to v2)

[joelanford]

Type of question

Are you asking about community best practices, how to implement a specific feature, or about general context and help around the operator-sdk?

General context and help around the operator-sdk

Question

What did you do?
UX report from @awgreene:

Question/concern for the sdk team regarding api versioning with multiple CRDs.
The marketplace manages two CRDs, CatalogSourceConfig and OperatorSource, both of which have the same group. I want to update the CatalogSourceConfig from v1 to v2. I did this with the following sdk command:

operator-sdk add api --api-version=operators.coreos.com/v2 --kind=CatalogSourceConfig

Which resulted in the following dir structure:

marketplace-operator/pkgs/apis/operator/v1 <--- Current OperatorSource version
marketplace-operator/pkgs/apis/operator/v2 <--- Current CatalogSourceConfig version

This resulted in the need to update all the aliases for the CatalogSourceConfig object, see [0], a rather large update. It seems like a similar change would be needed for any version upgrades. This provides a tedious user experience when upgrading an API and I wanted to hear your thoughts.

[0] https://github.com/operator-framework/operator-marketplace/pull/203/files (edited)

What did you expect to see?
A document describing best practices, tips, gotchas, and any other helpful information about making various API changes in an existing SDK project.

What did you see instead? Under which circumstances?
There's not currently any documentation about the best way to do this.

Environment

• operator-sdk version:

operator-sdk version: v0.8.1, commit: 33b3bfe10176f8647f5354516fff29dea42b6342

• Kubernetes version information:

Client Version: version.Info{Major:"1", Minor:"11", GitVersion:"v1.11.3", GitCommit:"a4529464e4629c21224b3d52edfe0ea91b072862", GitTreeState:"clean", BuildDate:"2018-09-09T18:02:47Z", GoVersion:"go1.10.3", Compiler:"gc", Platform:"linux/amd64"}
Server Version: version.Info{Major:"1", Minor:"13", GitVersion:"v1.13.5", GitCommit:"2166946f41b36dea2c4626f90a77706f426cdea2", GitTreeState:"clean", BuildDate:"2019-03-25T15:19:22Z", GoVersion:"go1.11.5", Compiler:"gc", Platform:"linux/amd64"}

• Kubernetes cluster kind: Minikube

[joelanford]

As discussed on Slack, there are likely too many different combinations of scenarios that would make it difficult for the SDK to support a subcommand-based solution for API migrations. For example:

• Is it a group, version, or kind change? Or some combination of those?
• Are all of the group or version types/functions moving, or just a subset?
• If just a subset, what subset? And are there internal types/functions that now need to be exported and accessible from a shared package?
• Are there backwards-compatibility concerns that require original packages to be unchanged?

Because of the complexity, the guidance so far is that operator developers should make manual changes that align with their specific migration scenario.

However, I think we should document some of these scenarios and include a walkthrough guide that has examples of some of the main changes that would need to be made. For example, we could document a complex example that would be similar to @awgreene's that includes a migration of a subset of types and functions to a higher version number, which involves:

1. Creating a new API with operator-sdk add api.
2. Copying existing types and functions into the new API version package and making any necessary API changes
3. Running sed to fix imports and package references
4. Extracting common code used by both old and new functions into a common shared package.
5. Updating controllers to use new API
6. Documenting strategies for converting CRs between their supported versions (e.g. one-shot migration, as part of operator reconciliation, or with CRD conversion webhooks)

[hasbro17]

Related: #1240 walk through CRD version upgrade with conversion webhooks.