diff --git a/_data/guides.yml b/_data/guides.yml index c19dd9a1d5..8ce2dcaa5d 100644 --- a/_data/guides.yml +++ b/_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 diff --git a/docs/concepts/overview/components.md b/docs/concepts/overview/components.md index 280b9b1f2c..070f9c9af8 100644 --- a/docs/concepts/overview/components.md +++ b/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 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 0000000000..3f3b94dd7c --- /dev/null +++ b/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`.