Merge pull request #2900 from wlan0/master

add docs about cloud-controller-manager

_data/guides.yml

@@ -113,6 +113,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,22 @@ 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 that interact with the underlying cloud providers. The `cloud-controller-manager` binary is an alpha feature introduced in Kubernetes release 1.6. 
+
+`cloud-controller-manager` runs cloud provider-specific controller loops only. As such, you must disable these controller loops in the `kube-controller-manager`. You can disable the controller loops by setting the `--cloud-provider` flag to `external` when starting the kube-controller-manager. 
+
+`cloud-controller-manager` allows cloud vendors and kubernetes core to evolve independent of each other. In prior releases, the core Kubernetes code was dependent upon cloud provider-specific code for functionality. In future releases, code specific to cloud vendors should be maintained by the cloud vendor themselves, and linked to `cloud-controller-manager` while running Kubernetes.
+
+The following controllers have cloud provider dependencies:
+
+* Node Controller: For checking the cloud provider to determine if a node has been deleted in the cloud after it stops responding
+* Route Controller: For setting up routes in the underlying cloud infrastructure
+* Service Controller: For creating, updating and deleting cloud provider load balancers
+* Volume Controller: For creating, attaching, and mounting volumes, and interacting with the cloud provider
+  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,32 @@
+---
+assignees:
+- thockin 
+title: Building and Running cloud-controller-manager
+---
+
+Kubernetes version 1.6 contains a new binary called as `cloud-controller-manager`. `cloud-controller-manager` is a daemon that embeds cloud-specific control loops in Kubernetes. These cloud-specific control loops were originally in the kube-controller-manager. However, cloud providers move at a different pace and schedule compared to the Kubernetes project, and abstracting the provider-specific code to the `cloud-controller-manager` binary allows cloud provider vendors to evolve independently from the core Kubernetes code.
+
+The `cloud-controller-manager` can be linked to any cloud provider that satisifies the [cloudprovider.Interface](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/cloud.go). 
+In future Kubernetes releases, cloud vendors should link code that satisfies the above interface to the `cloud-controller-manager` project and compile `cloud-controller-manager` for their own clouds. Cloud providers would also be responsible for maintaining and evolving their code.
+
+* TOC
+{:toc}
+
+### Building cloud-controller-manager for your cloud
+
+To build cloud-controller-manager for your cloud, 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, you do not need to write a new provider; you can proceed directly with linking your cloud provider to the `cloud-controller-manager`.
+
+Once your code is ready, you must import that code into `cloud-controller-manager`. See the [rancher cloud sample](https://github.com/rancher/rancher-cloud-controller-manager) for a reference example. The import step in the sample is the only step required to link your cloud provider to the `cloud-controller-manager`.
+
+### Running cloud-controller-manager
+
+To run `cloud-controller-manager`, add it 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. To prevent the `kube-controller-manager` from running cloud-specific controllers, you must set the `--cloud-provider` flag in `kube-controller-manager` to `external`.