add docs about cloud-controller-manager

_data/guides.yml

@@ -112,6 +112,7 @@ toc:
       - docs/getting-started-guides/rackspace.md
       - docs/getting-started-guides/kops.md
       - docs/getting-started-guides/kargo.md
+      - docs/getting-started-guides/running-cloud-controller.md
     - title: On-Premise VMs
       section:
       - docs/getting-started-guides/coreos/index.md

docs/concepts/overview/components.md

@@ -54,6 +54,26 @@ These controllers include:
 * Service Account & Token Controllers: Create default accounts and API access tokens for new namespaces.
 * ... and others.
 
+### cloud-controller-manager
+
+cloud-controller-manager is a binary that runs controllers which interact with
+the underlying cloudproviders. This binary was introduced in kubernetes release 1.6 as a alpha feature. This binary exclusively 
+runs cloud specific controller loops only. Since this binary runs the cloudprovider specific controllers, these controller loops 
+need to be turned off in the kube-controller-manager. This can be done by setting the `--cloud-provider` flag to "external" when starting the
+kube-controller-manager. 
+
+This binary was introduced to allow cloud vendors and kubernetes core to evolve independent of each other. In the current model, kubernetes is 
+dependent on cloudprovider specific code to function. This code is a part of the core of kubernetes. In the future, cloud vendor specific code 
+will be maintained by the cloud vendor themselves and linked to the cloud-controller-manager while running kubernetes. 
+
+The following controller have cloudprovider dependencies:
+
+* Node Controller: Responsible for checking cloudprovider to determine if a node has been deleted in the cloud after it stops responding
+* Route Controller: Responsible for setting up routes in the underlying cloud infrastructure
+* Service Controller: Responsible for creating, updating and deleting cloudprovider loadbalancers
+* Volume Controller: Responsible for creating, attaching, and mounting volumes. These also interact with the cloudprovider
+  to orchestrate volumes
+
 ### kube-scheduler
 
 [kube-scheduler](/docs/admin/kube-scheduler) watches newly created pods that have no node assigned, and

docs/getting-started-guides/running-cloud-controller.md

@@ -0,0 +1,37 @@
+---
+assignees:
+- thockin 
+title: Building and Running cloud-controller-manager
+---
+
+Release 1.6 of Kubernetes ships with a new binary known as cloud-controller-manager. This is a daemon that embeds cloud
+specific control loops in kubernetes. These cloud specific control loops were originally in the kube-controller-manager. However,
+cloudproviders move at a different pace and schedule compared to the kubernetes project, and this binary allows the cloudprovider vendors
+and kubernetes core to evolve independently. 
+
+The cloud-controller-manager is designed to be linked with any cloudprovider that satisifies the [cloudprovider.Interface](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/cloud.go). 
+In the future, cloud vendors would be expected to link code(that satisfies the above interface) to this project and compile cloud-controller-manager for their own clouds. They
+would also be responsible for maintaining and evolving their code.
+
+* TOC
+{:toc}
+
+### Building cloud-controller-manager for your cloud
+
+In order to build cloud-controller-manager for your cloud, you need to follow these steps:
+
+* Write a cloudprovider that satisfies the [cloudprovider.Interface](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/cloud.go).
+* Link the cloudprovider to cloud-controller-manager
+
+The methods in [cloudprovider.Interface](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/cloud.go) are self-explanatory. All of the
+[existing providers](https://github.com/kubernetes/kubernetes/tree/master/pkg/cloudprovider/providers) satisfy this interface. If your cloud is already a part
+of the existing providers, then you do not need to write a new provider. You can directly skip to the step of linking you cloudprovider to the cloud-controller-manager.
+
+Once you have the code ready, you need to import that code into the cloud-controller-manager. There is a sample cloud-controller-manager with the rancher cloud for your 
+reference [here](https://github.com/rancher/rancher-cloud-controller-manager). The import is the only step required to link your cloudprovider to the cloud-controller-manager.
+
+### Running cloud-controller-manager
+
+The cloud-controller-manager can be added to your existing kubernetes cluster as a Master component. All other master components, except kube-controller-manager can be run without any changes.
+The kube-controller-manager should not run any cloud specific controllers, since the cloud-controller-manager takes over this responsibility. In order to prevent the kube-controller-manager from
+running cloud specific controllers, you need to set the `--cloud-provider` flag in kube-controller-manager to "external"