{"id":13562098,"url":"https://github.com/digitalocean/digitalocean-cloud-controller-manager","last_synced_at":"2025-06-11T01:09:08.659Z","repository":{"id":23872494,"uuid":"94823705","full_name":"digitalocean/digitalocean-cloud-controller-manager","owner":"digitalocean","description":"Kubernetes cloud-controller-manager for DigitalOcean (beta)","archived":false,"fork":false,"pushed_at":"2025-05-26T14:53:25.000Z","size":53273,"stargazers_count":547,"open_issues_count":34,"forks_count":153,"subscribers_count":139,"default_branch":"master","last_synced_at":"2025-05-26T15:54:49.421Z","etag":null,"topics":["beta","cloud","cloud-providers","controller-manager","digitalocean","golang","hacktoberfest","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalocean.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-06-19T21:45:45.000Z","updated_at":"2025-05-22T14:58:26.000Z","dependencies_parsed_at":"2023-02-17T23:15:48.789Z","dependency_job_id":"92ccd6f5-5df2-4433-bba5-6e0bd05d6eb3","html_url":"https://github.com/digitalocean/digitalocean-cloud-controller-manager","commit_stats":{"total_commits":548,"total_committers":64,"mean_commits":8.5625,"dds":0.7846715328467153,"last_synced_commit":"c0e176f9bd3073b9deafd226d0ba13a78c2c2602"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fdigitalocean-cloud-controller-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fdigitalocean-cloud-controller-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fdigitalocean-cloud-controller-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fdigitalocean-cloud-controller-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalocean","download_url":"https://codeload.github.com/digitalocean/digitalocean-cloud-controller-manager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalocean%2Fdigitalocean-cloud-controller-manager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259178519,"owners_count":22817388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beta","cloud","cloud-providers","controller-manager","digitalocean","golang","hacktoberfest","kubernetes"],"created_at":"2024-08-01T13:01:04.527Z","updated_at":"2025-06-11T01:09:08.646Z","avatar_url":"https://github.com/digitalocean.png","language":"Go","readme":"# Kubernetes Cloud Controller Manager for DigitalOcean\n\n`digitalocean-cloud-controller-manager` is the Kubernetes cloud controller manager implementation for DigitalOcean. Read more about cloud controller managers [here](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/). Running `digitalocean-cloud-controller-manager` allows you to leverage many of the cloud provider features offered by DigitalOcean on your Kubernetes clusters.\n\n## Releases\n\nCloud Controller Manager follows [semantic versioning](https://semver.org/).\nAlthough the version is still below v1, the project is considered\nproduction-ready.\n\nBecause of the fast Kubernetes release cycles, CCM (Cloud Controller Manager)\nwill **only** support the version that is _also_ supported on [DigitalOcean Kubernetes\nproduct](https://www.digitalocean.com/products/kubernetes/). Any other releases\nwill be not officially supported by us.\n\n## Getting Started\n\nLearn more about running DigitalOcean cloud controller manager [here](docs/getting-started.md)!\n\n_Note that this CCM is installed by default on [DOKS](https://www.digitalocean.com/products/kubernetes/) (DigitalOcean Managed Kubernetes), you don't have to do it yourself._\n\n## Examples\n\nHere are some examples of how you could leverage `digitalocean-cloud-controller-manager`:\n\n* [loadbalancers](docs/controllers/services/examples/)\n* [node labels and addresses](docs/controllers/node/examples/)\n\n## Production notes\n\n### do not modify DO load-balancers manually\n\nWhen 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)).\n\nOther than that, the only safe place to make load-balancer configuration changes is through the Service object.\n\n### DO load-balancer entry port restrictions\n\nFor 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).\n\nThe solution is to change the service port to a different, non-conflicting one.\n\n## Development\n\n### Basics\n\n* Go: min `v1.17.x`\n\nThis project uses [Go modules](https://github.com/golang/go/wiki/Modules) for dependency management and employs vendoring. Please ensure to run `make vendor` after any dependency modifications.\n\nAfter making your code changes, run the tests and CI checks:\n\n```bash\nmake ci\n```\n\n### Run Locally\n\nIf you want to run `digitalocean-cloud-controller-manager` locally against a\nparticular cluster, keep your kubeconfig ready and start the binary in the main\npackage-hosted directory like this:\n\n```bash\ncd cloud-controller-manager/cmd/digitalocean-cloud-controller-manager\nREGION=fra1 DO_ACCESS_TOKEN=your_access_token go run main.go \\\n  --kubeconfig \u003cpath to your kubeconfig file\u003e                     \\\n  --leader-elect=false --v=5 --cloud-provider=digitalocean\n```\n\nThe `REGION` environment variable takes a valid DigitalOcean region.\nIt can be set to keep `digitalocean-cloud-controller-manager` from trying to access\nthe DigitalOcean metadata service which is only available on droplets.\nIf the REGION variable is set, then the DO Regions service will be used to validate the specified region.\nIt can also be set for local development purposes. Overall,\nwhich region you choose should not matter a lot as long as you pick one.\n\nYou might also need to provide your DigitalOcean access token in\n`DO_ACCESS_TOKEN` environment variable. The token does not need to be valid for\nthe cloud controller to start, but in that case, you will not be able to\nvalidate integration with DigitalOcean API.\n\nPlease note that if you use a Kubernetes cluster created on DigitalOcean, there\nwill be a cloud controller manager running in the cluster already, so your local\none will compete for API access with it.\n\n### Optional features\n\n#### Add Public Access Firewall\n\nYou can have `digitalocean-cloud-controller-manager` manage a DigitalOcean Firewall\nthat will dynamically adjust rules for accessing NodePorts: once a Service of type\n`NodePort` is created, the firewall controller will update the firewall to public\nallow access to just that NodePort. Likewise, access is automatically retracted\nif the Service gets deleted or changed to a different type.\n\nExample invocation:\n\n```bash\ncd cloud-controller-manager/cmd/digitalocean-cloud-controller-manager\nDO_ACCESS_TOKEN=\u003cyour_access_token\u003e                           \\\nPUBLIC_ACCESS_FIREWALL_NAME=firewall_name                     \\\nPUBLIC_ACCESS_FIREWALL_TAGS=worker-droplet                    \\\ndigitalocean-cloud-controller-manager                         \\\n  --kubeconfig \u003cpath to your kubeconfig file\u003e                 \\\n  --leader-elect=false --v=5 --cloud-provider=digitalocean\n```\n\nThe `PUBLIC_ACCESS_FIREWALL_NAME` environment variable defines the name of the\nfirewall. The firewall is created if no firewall by that name is found.\n\nThe `PUBLIC_ACCESS_FIREWALL_TAGS` environment variable refers to the tags\nassociated with the droplets that the firewall should apply to. Usually, this\nis a tag attached to the worker node droplets. Multiple tags are applied in\na logical OR fashion.\n\nIn some cases, firewall management for a particular Service may not be\ndesirable. One example is that a NodePort is supposed to be accessible over the\nVPC only. In such cases, the Service annotation\n`kubernetes.digitalocean.com/firewall-managed` can be used to selectively\nexclude a given Service from firewall management. If set to `\"false\"`, no\ninbound rules will be created for the Service, effectively disabling public\naccess to the NodePort. (Note the quotes that must be included with \"boolean\"\nannotation values.) The default behavior applies if the annotation is omitted,\nis set to `\"true`\", or contains an invalid value.\n\nNo firewall is managed if the environment variables are missing or left empty.\nOnce the firewall is created, no public access other than to the NodePorts is\nallowed. Users should create additional firewalls to further extend access.\n\n#### Expose Prometheus Metrics\n\nIf you are interested in exposing Prometheus metrics, you can pass in a metrics\nendpoint that will expose them. The command will look similar to this:\n\n```bash\ncd cloud-controller-manager/cmd/digitalocean-cloud-controller-manager\nDO_ACCESS_TOKEN=your_access_token                  \\\nMETRICS_ADDR=\u003chost\u003e:\u003cport\u003e                         \\\ndigitalocean-cloud-controller-manager              \\\n  --kubeconfig \u003cpath to your kubeconfig file\u003e      \\\n  --leader-elect=false --v=5 --cloud-provider=digitalocean\n```\n\nThe `METRICS_ADDR` environment variable takes a valid endpoint that you'd\nlike to use to serve your Prometheus metrics. To be valid it should be in the\nform `\u003chost\u003e:\u003cport\u003e`.\n\nAfter you have started up `digitalocean-cloud-controller-manager`, run the\nfollowing curl command to view the Prometheus metrics output:\n\n```bash\ncurl \u003chost\u003e:\u003cport\u003e/metrics\n```\n\n#### Admission Server\n\nThe admission server is an optional component aiming at reducing bad config changes for DO managed objects (LBs, etc).\nIf you want to know more about it, read the [docs](./docs/admission-server.md).\n\n### DO API rate limiting\n\nDO API usage is subject to [certain rate limits](https://docs.digitalocean.com/reference/api/api-reference/#section/Introduction/Rate-Limit). 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 the `DO_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.    \n\n### Run Containerized\n\nIf you want to test your changes in a containerized environment, create a new\nimage with the version set to `dev`:\n\n```bash\nVERSION=dev make publish\n```\n\nThis will create a binary with version `dev` and docker image pushed to\n`digitalocean/digitalocean-cloud-controller-manager:dev`.\n\n## Release a new version\n\n### Update Go and dependencies \n1. Update Go dependencies\n   ```shell\n   go get -u ./...\n   go mod tidy\n   go mod vendor\n   ```\n2. [Update Go version to latest GA version](./go.mod)\n\n### Github Action (preferred)\n\nTo create the docker image and generate the manifests, go to the actions page on GitHub and click \"Run Workflow\". \nSpecify the GitHub `\u003ctag\u003e` that you want to create, making sure it is prefixed with a `v`.\nRunning the workflow also requires that you temporarily turn off \"Require a pull request before merging\" setting in the master [branch protection rules settings](https://github.com/digitalocean/digitalocean-cloud-controller-manager/settings/branches). **Don't forget to turn it back on once the release is done!**\n\nThe workflow does the following:\n\n* Runs `make bump-version` with `\u003ctag\u003e`\n* Creates the ccm related manifests file as `\u003ctag\u003e.yaml`\n* Commits the manifest file under `releases/` directory in the repo\n* Creates release and tags the new commit with the `\u003ctag\u003e` specified when workflow is triggered\n* Logs in with dockerhub credentials specified as secrets\n* Builds the docker image `digitalocean/digitalocean-cloud-controller-manager:\u003ctag\u003e`\n* Pushes `digitalocean/digitalocean-cloud-controller-manager:\u003ctag\u003e` to dockerhub\n\n### Manual (deprecated)\n\nNOTE: this workflow is deprecated, please prefer the Github Action workflow described above.\n\nTo manually release a new version, first bump the version:\n\n```bash\nmake NEW_VERSION=v1.0.0 bump-version\n```\n\nMake sure everything looks good. Create a new branch with all changes:\n\n```bash\ngit checkout -b release-\u003cnew version\u003e origin/master\ngit commit -a -v\ngit push origin release-\u003cnew version\u003e\n```\n\nAfter it's merged to master, tag the commit and push it:\n\n```bash\ngit checkout master\ngit pull\ngit tag \u003cnew version\u003e\ngit push origin \u003cnew version\u003e\n```\n\nFinally, [create a Github\nrelease](https://github.com/digitalocean/digitalocean-cloud-controller-manager/releases/new) from\nmaster with the new version and publish it:\n\n```bash\nmake publish\n```\n\nThis will compile a binary containing the new version bundled in a docker image pushed to\n`digitalocean/digitalocean-cloud-controller-manager:\u003cnew version\u003e`\n\n## Contributing\n\nAt 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.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalocean%2Fdigitalocean-cloud-controller-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalocean%2Fdigitalocean-cloud-controller-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalocean%2Fdigitalocean-cloud-controller-manager/lists"}