digitalocean/digitalocean-cloud-controller-manager

digitalocean/digitalocean-cloud-controller-manager

Description: Kubernetes cloud-controller-manager for DigitalOcean (beta)

Language: Go

License: Apache-2.0

Stars: 569

Forks: 151

Open issues: 41

Created: 2017-06-19T21:45:45Z

Pushed: 2026-05-06T05:57:53Z

Default branch: master

Fork: no

Archived: no

README:

Kubernetes Cloud Controller Manager for DigitalOcean

digitalocean-cloud-controller-manager is the Kubernetes cloud controller manager implementation for DigitalOcean. Read more about cloud controller managers here. Running digitalocean-cloud-controller-manager allows you to leverage many of the cloud provider features offered by DigitalOcean on your Kubernetes clusters.

Releases

Cloud Controller Manager follows semantic versioning. Although the version is still below v1, the project is considered production-ready.

Because of the fast Kubernetes release cycles, CCM (Cloud Controller Manager) will only support the version that is _also_ supported on DigitalOcean Kubernetes product. Any other releases will be not officially supported by us.

Getting Started

Learn more about running DigitalOcean cloud controller manager [here](docs/getting-started.md)!

_Note that this CCM is installed by default on DOKS (DigitalOcean Managed Kubernetes), you don't have to do it yourself._

Examples

Here are some examples of how you could leverage digitalocean-cloud-controller-manager:

• [loadbalancers](docs/controllers/services/examples/)
• [node labels and addresses](docs/controllers/node/examples/)

Production notes

do not modify DO load-balancers manually

When you are creating load-balancers through CCM (via LoadBalancer-typed Services),it is very important that you must not change the DO load-balancer configuration manually. Such changes will eventually be reverted by the reconciliation loop built into CCM. There is one exception in load-balancer name which can be changed (see also [the documentation on load-balancer ID annotations](/docs/getting-started.md#load-balancer-id-annotations)).

Other than that, the only safe place to make load-balancer configuration changes is through the Service object.

DO load-balancer entry port restrictions

For technical reasons, the ports 50053, 50054, and 50055 cannot be used as load-balancer entry ports (i.e., the port that the load-balancer listens on for requests). Trying to use one of the affected ports as a service port causes a _422 entry port is invalid_ HTTP error response to be returned by the DO API (and surfaced as a Kubernetes event).

The solution is to change the service port to a different, non-conflicting one.

Development

Basics

• Go: min v1.17.x

This project uses Go modules for dependency management and employs vendoring. Please ensure to run make vendor after any dependency modifications.

After making your code changes, run the tests and CI checks:

make ci

Run Locally

If you want to run digitalocean-cloud-controller-manager locally against a particular cluster, keep your kubeconfig ready and start the binary in the main package-hosted directory like this:

cd cloud-controller-manager/cmd/digitalocean-cloud-controller-manager
REGION=fra1 DO_ACCESS_TOKEN=your_access_token go run main.go \
--kubeconfig \
--leader-elect=false --v=5 --cloud-provider=digitalocean

The REGION environment variable takes a valid DigitalOcean region. It can be set to keep digitalocean-cloud-controller-manager from trying to access the DigitalOcean metadata service which is only available on droplets. If the REGION variable is set, then the DO Regions service will be used to validate the specified region. It can also be set for local development purposes. Overall, which region you choose should not matter a lot as long as you pick one.

You might also need to provide your DigitalOcean access token in DO_ACCESS_TOKEN environment variable. The token does not need to be valid for the cloud controller to start, but in that case, you will not be able to validate integration with DigitalOcean API.

Please note that if you use a Kubernetes cluster created on DigitalOcean, there will be a cloud controller manager running in the cluster already, so your local one will compete for API access with it.

Optional features

Add Public Access Firewall

You can have digitalocean-cloud-controller-manager manage a DigitalOcean Firewall that will dynamically adjust rules for accessing NodePorts: once a Service of type NodePort is created, the firewall controller will update the firewall to public allow access to just that NodePort. Likewise, access is automatically retracted if the Service gets deleted or changed to a different type.

Example invocation:

cd cloud-controller-manager/cmd/digitalocean-cloud-controller-manager
DO_ACCESS_TOKEN= \
PUBLIC_ACCESS_FIREWALL_NAME=firewall_name \
PUBLIC_ACCESS_FIREWALL_TAGS=worker-droplet \
digitalocean-cloud-controller-manager \
--kubeconfig \
--leader-elect=false --v=5 --cloud-provider=digitalocean

The PUBLIC_ACCESS_FIREWALL_NAME environment variable defines the name of the firewall. The firewall is created if no firewall by that name is found.

The PUBLIC_ACCESS_FIREWALL_TAGS environment variable refers to the tags associated with the droplets that the firewall should apply to. Usually, this is a tag attached to the worker node droplets. Multiple tags are applied in a logical OR fashion.

In some cases, firewall management for a particular Service may not be desirable. One example is that a NodePort is supposed to be accessible over the VPC only. In such cases, the Service annotation kubernetes.digitalocean.com/firewall-managed can be used to selectively exclude a given Service from firewall management. If set to "false", no inbound rules will be created for the Service, effectively disabling public access to the NodePort. (Note the quotes that must be included with "boolean" annotation values.) The default behavior applies if the annotation is omitted, is set to "true", or contains an invalid value.

No firewall is managed if the environment variables are missing or left empty. Once the firewall is created, no public access other than to the…