diff --git a/_data/guides.yml b/_data/guides.yml index 0a06052579155..df61157d92143 100644 --- a/_data/guides.yml +++ b/_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 diff --git a/docs/concepts/overview/components.md b/docs/concepts/overview/components.md index 280b9b1f2cdf2..7873b2863c9a1 100644 --- a/docs/concepts/overview/components.md +++ b/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 diff --git a/docs/getting-started-guides/running-cloud-controller.md b/docs/getting-started-guides/running-cloud-controller.md new file mode 100644 index 0000000000000..72f30e05cd893 --- /dev/null +++ b/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"