keps/sig-cloud-provider: add recommended directory structure for provider docs

1 files changed, 55 insertions, 29 deletions

diff --git a/keps/sig-cloud-provider/0019-cloud-provider-documentation.md b/keps/sig-cloud-provider/0019-cloud-provider-documentation.md
index 9580df0e..a0d72413 100644
--- a/keps/sig-cloud-provider/0019-cloud-provider-documentation.md
+++ b/keps/sig-cloud-provider/0019-cloud-provider-documentation.md
@@ -66,47 +66,73 @@ SIG-Docs is not expected to produce or maintain any of this documentation.
 
 ### Proposal
 
-#### Goal 1:
-Produce a common document that describes how to configure any in-tree cloud provider that can be reused by tools such as kubeadm, to create minimum viable Kubernetes clusters.
+#### In-Tree Documetation
+Produce common documentation that describes how to configure any in-tree cloud provider that can be reused by tools such as kubeadm, to create minimum viable Kubernetes clusters.
 
 Kubernetes documentation lists details of current cloud-provider [here](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/). Additional documentation [(1),](https://kubernetes.io/docs/concepts/services-networking/service/) [(2)](https://kubernetes.io/docs/tasks/administer-cluster/developing-cloud-controller-manager/) that link to cloud-provider code currently remains detached and poorly maintained.
 
 #### Requirement 1:
-Provide validated manifests for kube-controller-manager, kubelet and kube-apiserver by cloud-provider to enable a Kubernetes administrator to run cloud-provider=<providername> in-tree with kube-controller-manager as is feasible today. This is only relevant to environments where a Kubernetes administrator/user has (or) wants access to the control plane. Environments such as Amazon EKS, Google’s GKE, Azure’s AKS and other such platforms are out of context here.
+Provide validated manifests for kube-controller-manager, kubelet and kube-apiserver to enable a Kubernetes administrator to run cloud-provider=<providername> in-tree as is feasible today. Example manifests should be in the following directories:
 
-* Add --cloud-provider=<providername> to the kube-apiserver, kube-controller-manager and every kubelet. These manifests should be regularly updated and listed at this location: https://github.com/kubernetes/kubernetes/tree/master/pkg/cloudprovider/providers/aws/docs/
-  * Example of an [apiserver manifest](https://gist.github.com/d-nishi/1109fec153930e8de04a1bf160cacffb)
-  * Example of [kube-controller-manager](https://gist.github.com/d-nishi/a41691cdf50239986d1e725af4d20033)
-  * Example of a [systemd service for kubelet](https://gist.github.com/d-nishi/289cb82367580eb0cb129c9f967d903d) and [kubelet config](https://gist.github.com/d-nishi/d7f9a1b59c0441d476646dc7cce7e811)
-* Run in-tree cloud-controller-manager as a [daemon-set](https://gist.github.com/d-nishi/38e3b7051029b5d1a1772f3862f62ce9)/deployment/replicaset/static pod on the cluster.
+* kubernetes/kubernetes/pkg/cloudprovider/myprovider/docs/example-manifests/
+   * [kube-apiserver.manifest](https://gist.github.com/d-nishi/1109fec153930e8de04a1bf160cacffb)
+   * [kube-controller-manager.manifest](https://gist.github.com/d-nishi/a41691cdf50239986d1e725af4d20033)
+   * [kubelet.manifest](https://gist.github.com/d-nishi/289cb82367580eb0cb129c9f967d903d) with [kubelet flags](https://gist.github.com/d-nishi/d7f9a1b59c0441d476646dc7cce7e811)
+
+The examples above are from a cluster running on AWS.
 
 #### Requirement 2:
-Provide validated/tested descriptions with examples of controller features (annotations or tags) that are cloud-provider dependent that can be reused by any Kubernetes administrator to run `cloud-provider-<providername>` in-tree with `kube-controller-manager` as is described in the code <cloudprovider.go> Example: aws.go
-These manifests should be regularly tested and updated post testing in the relevant provider location E.g.: https://github.com/kubernetes/kubernetes/tree/master/pkg/cloudprovider/providers/aws/docs/
-* Node Controller (or) NodeName
-* Service Controller (or) LoadBalancer
-* Volume Controller (or) persistent volume labels controller
-* Other provider-specific-Controller e.g. Route controller for GCP.
-
-#### Goal 2:
+Provide validated/tested descriptions with examples of controller features (annotations or labels) that are cloud-provider dependent that can be reused by any Kubernetes administrator to run `cloud-provider-<providername>` in-tree with `kube-controller-manager` as is described in the code <cloudprovider.go> Example: aws.go
+These manifests should be regularly tested and updated post testing in the relevant provider location:
+
+
+* kubernetes/kubernetes/pkg/cloudprovider/myprovider/docs/controllers/
+  * node/
+    * annotations.md - outlines what annotations the controller sets or reads from a node resource
+    * labels.md - outlines what labels the controller sets or read from a node resource
+    * README.md - outlines the purpose of this controller
+  * service/
+    * annotations.md - outlines what annotations the controller sets or reads when managing a load balancer
+    * labels.md - outlines what labels the controller sets or read when managing a load balancer
+    * README.md - outlines the purpose of this controller
+  * persistentvolumelabel/
+    * annotations.md - outlines what annotations the controller sets or read when managing persistent volumes
+    * labels.md - outlines what labels the controller sets when managing persistent volumes (previously known as PersistentVolumeLabel admission controller)
+    * README.md - outlines the purpose of this controller
+  * ...
+
+#### Out-of-Tree Documetation
 Provide a common document that describes how to configure a Kubernetes cluster on any out-of-tree cloud provider.
 
 #### Requirement 1:
-Provide validated manifests for kube-controller-manager, kubelet, kube-apiserver and cloud-controller-manager by cloud-provider. The following examples are from provisioning a cluster on DigitalOcean using kops.
-* Set --cloud-provider=external flag from kube-apiserver, kube-controller-manager and kubelet. Remove this flag from the manifest when the flag is deprecated in a future release.
-  * Example of [apiserver manifest](https://gist.github.com/andrewsykim/a7938e185d45e1c0ef760c375005fdef)
-  * Example of [kube-controller-manager manifest](https://gist.github.com/andrewsykim/56ee2da95ade8386d3123e982d72aca9)
-  * Example of [kubelet manifest](https://gist.github.com/andrewsykim/ac954b1657eb0e6a2e95af516594e2bd)
-* Run out-of-tree cloud-controller-manager as a daemon-set/deployment/replicaset/static pod on the cluster.
-  * Example of [cloud controller manager DaemonSet](https://gist.github.com/andrewsykim/26e22e36471c1774e3626a70d2b7465f)
+
+Provide validated manifests for kube-controller-manager, kubelet, kube-apiserver and cloud-controller-manager to enable a Kubernetes administrator to run cloud-provider=<providername> out-of-tree as is feasible today. Example manifests should be in the following directories:
+
+* /path/to/out-of-tree-provider/docs/example-manifests/
+   * [apiserver manifest](https://gist.github.com/andrewsykim/a7938e185d45e1c0ef760c375005fdef)
+   * [kube-controller-manager manifest](https://gist.github.com/andrewsykim/56ee2da95ade8386d3123e982d72aca9)
+   * [kubelet manifest](https://gist.github.com/andrewsykim/ac954b1657eb0e6a2e95af516594e2bd)
+   * [cloud controller manager DaemonSet](https://gist.github.com/andrewsykim/26e22e36471c1774e3626a70d2b7465f)
+
+The following examples are from provisioning a cluster on DigitalOcean using kops.
 
 #### Requirement 2:
-List out the latest annotations or tags that are cloud-provider dependent and will be used by the Kubernetes administrator to run `cloud-provider-<providername>` in-tree with `kube-controller-manager` as is described in the code <cloudprovider.go> Eg. aws.go
-These manifests should be regularly tested and updated in the relevant provider location E.g.: https://github.com/kubernetes/cloud-provider-aws/docs/
-* Node Controller (or) NodeName
-* Service Controller (or) LoadBalancer
-* Volume Controller (or) persistent volume labels controller
-* Other provider-specific-Controller e.g. Route controller for GCP
+List out the latest annotations or tags that are cloud-provider dependent and will be used by the Kubernetes administrator to run `cloud-provider-<providername>` out-of-tree with `cloud-controller-manager`. These manifests should be regularly tested and updated in the relevant provider location:
+
+* /path/to/out-of-tree-provider/docs/controllers/
+  * node/
+    * annotations.md - outlines what annotations the controller sets or reads from a node resource
+    * labels.md - outlines what labels the controller sets or read from a node resource
+    * README.md - outlines the purpose of this controller
+  * service/
+    * annotations.md - outlines what annotations the controller sets or reads when managing a load balancer
+    * labels.md - outlines what labels the controller sets or read when managing a load balancer
+    * README.md - outlines the purpose of this controller
+  * persistentvolumelabel/
+    * annotations.md - outlines what annotations the controller sets or read when managing persistent volumes
+    * labels.md - outlines what labels the controller sets when managing persistent volumes (previously known as PersistentVolumeLabel admission controller)
+    * README.md - outlines the purpose of this controller
+  * Other provider-specific-Controller e.g. Route controller for GCP
 
 ### User Stories [optional]