Plan and document how to migrate clusters to some form of CRD

[carolynvs]

Once we've figured out how to move forward towards CRDs, see #1088 and #987, we must plan and document how to migrate v1beta1 clusters to whatever we end up with.

[MHBauer]

There's two CRD flows being conflated here:

1. The existing issues are for CRD as a backing store, behind the existing APIServer, and requiring no changes in the controller code. The migration between these two stores wouldn't be done by our code, but by a separate tool.
2. Native CRD model, would eliminate the need for the APIServer at all, and would mean that the Controller natively speaks CRD rather than our existing objects. I think we may need to provide code to do this, but I'm not sure it would be live, and probably best implemented as a one-time tool to switch the data formats.

Either way, I think this is best done by a separate tool, and noton startup of either apiserver or controller. (Idea: we hack the apiserver to run the tool, and not serve it's API, and the controller only ever speaks CRD after the cutover. This is provided for a few versions until the ability settles, with the tool always available)

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[mszostok]

work is done in: #2633

[MHBauer]

@mszostok Is this the appropriate documentation? Up to date? https://github.com/kubernetes-sigs/service-catalog/blob/master/docs/migration-apiserver-to-crds.md

[mszostok]

@MHBauer yep, there is also a new Preparation section which was added later when we noticed that some of our users were problems with migration because of the unhealthy cluster state.