Repository files navigation

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

Cloud Controller Manager followssemantic versioning.Although the version is still below v1, the project is consideredproduction-ready.

Because of the fast Kubernetes release cycles, CCM (Cloud Controller Manager)willonly support the version that isalso supported onDigitalOcean Kubernetesproduct. Any other releaseswill be not officially supported by us.

Learn more about running DigitalOcean cloud controller managerhere!

Note that this CCM is installed by default onDOKS (DigitalOcean Managed Kubernetes), you don't have to do it yourself.

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

• loadbalancers
• node labels and addresses

When you are creating load-balancers through CCM (viaLoadBalancer-typed Services),it is very important that youmust 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 alsothe documentation on load-balancer ID annotations).

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

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 a422 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.

• Go: minv1.17.x

This project usesGo modules for dependency management and employs vendoring. Please ensure to runmake vendor after any dependency modifications.

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

make ci

If you want to rundigitalocean-cloud-controller-manager locally against aparticular cluster, keep your kubeconfig ready and start the binary in the mainpackage-hosted directory like this:

cd cloud-controller-manager/cmd/digitalocean-cloud-controller-managerREGION=fra1 DO_ACCESS_TOKEN=your_access_token go run main.go \  --kubeconfig<path to your kubeconfig file>                     \  --leader-elect=false --v=5 --cloud-provider=digitalocean

TheREGION environment variable takes a valid DigitalOcean region.It can be set to keepdigitalocean-cloud-controller-manager from trying to accessthe 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 inDO_ACCESS_TOKEN environment variable. The token does not need to be valid forthe cloud controller to start, but in that case, you will not be able tovalidate integration with DigitalOcean API.

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

You can havedigitalocean-cloud-controller-manager manage a DigitalOcean Firewallthat will dynamically adjust rules for accessing NodePorts: once a Service of typeNodePort is created, the firewall controller will update the firewall to publicallow access to just that NodePort. Likewise, access is automatically retractedif the Service gets deleted or changed to a different type.

Example invocation:

cd cloud-controller-manager/cmd/digitalocean-cloud-controller-managerDO_ACCESS_TOKEN=<your_access_token>                           \PUBLIC_ACCESS_FIREWALL_NAME=firewall_name                     \PUBLIC_ACCESS_FIREWALL_TAGS=worker-droplet                    \digitalocean-cloud-controller-manager                         \  --kubeconfig<path to your kubeconfig file>                 \  --leader-elect=false --v=5 --cloud-provider=digitalocean

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

ThePUBLIC_ACCESS_FIREWALL_TAGS environment variable refers to the tagsassociated with the droplets that the firewall should apply to. Usually, thisis a tag attached to the worker node droplets. Multiple tags are applied ina logical OR fashion.

In some cases, firewall management for a particular Service may not bedesirable. One example is that a NodePort is supposed to be accessible over theVPC only. In such cases, the Service annotationkubernetes.digitalocean.com/firewall-managed can be used to selectivelyexclude a given Service from firewall management. If set to"false", noinbound rules will be created for the Service, effectively disabling publicaccess 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 NodePorts isallowed. Users should create additional firewalls to further extend access.

If you are interested in exposing Prometheus metrics, you can pass in a metricsendpoint that will expose them. The command will look similar to this:

cd cloud-controller-manager/cmd/digitalocean-cloud-controller-managerDO_ACCESS_TOKEN=your_access_token                  \METRICS_ADDR=<host>:<port>                         \digitalocean-cloud-controller-manager              \  --kubeconfig<path to your kubeconfig file>      \  --leader-elect=false --v=5 --cloud-provider=digitalocean

TheMETRICS_ADDR environment variable takes a valid endpoint that you'dlike to use to serve your Prometheus metrics. To be valid it should be in theform<host>:<port>.

After you have started updigitalocean-cloud-controller-manager, run thefollowing curl command to view the Prometheus metrics output:

curl<host>:<port>/metrics

The admission server is an optional component aiming at reducing bad config changes for DO managed objects (LBs, etc).If you want to know more about it, read thedocs.

DO API usage is subject tocertain rate limits. In order to protect against running out of quota for extremely heavy regular usage or pathological cases (e.g., bugs or API thrashing due to an interfering third-party controller), a custom rate limit can be configured via theDO_API_RATE_LIMIT_QPS environment variable. It accepts a float value, e.g.,DO_API_RATE_LIMIT_QPS=3.5 to restrict API usage to 3.5 queries per second.

If you want to test your changes in a containerized environment, create a newimage with the version set todev:

VERSION=dev make publish

This will create a binary with versiondev and docker image pushed todigitalocean/digitalocean-cloud-controller-manager:dev.

1. Update Go dependencies

   go get -u ./...go mod tidygo mod vendor

2. Update Go version to latest GA version

To create the docker image and generate the manifests, go to the actions page on GitHub and click "Run Workflow".Specify the GitHub<tag> that you want to create, making sure it is prefixed with av.Running the workflow also requires that you temporarily turn off "Require a pull request before merging" setting in the masterbranch protection rules settings.Don't forget to turn it back on once the release is done!

The workflow does the following:

• Runsmake bump-version with<tag>
• Creates the ccm related manifests file as<tag>.yaml
• Commits the manifest file underreleases/ directory in the repo
• Creates release and tags the new commit with the<tag> specified when workflow is triggered
• Logs in with dockerhub credentials specified as secrets
• Builds the docker imagedigitalocean/digitalocean-cloud-controller-manager:<tag>
• Pushesdigitalocean/digitalocean-cloud-controller-manager:<tag> to dockerhub

NOTE: this workflow is deprecated, please prefer the Github Action workflow described above.

To manually release a new version, first bump the version:

make NEW_VERSION=v1.0.0 bump-version

Make sure everything looks good. Create a new branch with all changes:

git checkout -b release-<new version> origin/mastergit commit -a -vgit push origin release-<new version>

After it's merged to master, tag the commit and push it:

git checkout mastergit pullgit tag<new version>git push origin<new version>

Finally,create a Githubrelease frommaster with the new version and publish it:

make publish

This will compile a binary containing the new version bundled in a docker image pushed todigitalocean/digitalocean-cloud-controller-manager:<new version>

At DigitalOcean we value and love our community! If you have any issues or would like to contribute, feel free to open an issue/PR and cc any of the maintainers below.