Schedule APIs for deprecation/removal

[joeduffy]

From time to time, APIs are deprecated and then eventually removed. For example, coming soon: https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/. I don't believe we do anything special for such APIs today, however it would be nice to use language-level deprecation annotations to warn users in advance, before they finally go missing due to actual removal of support. I'm unsure whether this can be data-driven based on OpenAPI metadata, however clearly that would be ideal.

[lblackstone]

Unfortunately it doesn't look like the OpenAPI spec includes the info we'd need to do this automatically. It is fairly uncommon for k8s to remove apiVersions, so we could add these notices in manually if it's important.

That said, I'm now wondering if we'll need to do further work in the provider to make sure that existing resources can migrate smoothly. Opened #671 to track that investigation.