file:///home/josie/development/cherry/cloud-provider-cherry/README.md {"mtime":1706008892366,"ctime":1706008892363,"size":28608,"etag":"3bq2ki0s6tnq","orphaned":false,"typeId":""}
# Kubernetes Cloud Controller Manager for Cherry Servers

[![GitHub release](https://img.shields.io/github/release/cherryservers/cloud-provider-cherry/all.svg?style=flat-square)](https://github.com/cherryservers/cloud-provider-cherry/releases)
[![Go Report Card](https://goreportcard.com/badge/github.com/cherryservers/cloud-provider-cherry)](https://goreportcard.com/report/github.com/cherryservers/cloud-provider-cherry)
![Continuous Integration](https://github.com/cherryservers/cloud-provider-cherry/workflows/Continuous%20Integration/badge.svg)
[![Docker Pulls](https://img.shields.io/docker/pulls/cherryservers/cloud-provider-cherry.svg)](https://hub.docker.com/r/cherryservers/cloud-provider-cherry/)
![Cherry Servers Maintained](https://img.shields.io/badge/stability-maintained-green.svg)


`cloud-provider-cherry` is the Kubernetes CCM implementation for Cherry Servers. Read more about the CCM in [the official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/).

This repository is **Maintained**!

## Requirements

At the current state of Kubernetes, running the CCM requires a few things.
Please read through the requirements carefully as they are critical to running the CCM on a Kubernetes cluster.

### Compatibility with Kubernetes

The CCM is released with a specific semantic version that correlates with the Kubernetes upstream
version. 

* The major and minor versions are equivalent to the compatible upstream release.
* The patch version is reserved for internal releases of the CCM.

Currently, for a given cloud provider release version, compatibility is guaranteed only between
that major/minor release and the corresponding Kubernetes major/minor version. That means
you need to upgrade the cloud provider components every time you upgrade Kubernetes major or minor
version.

This is based on, but not identical to, [the external cloud provider versioning KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cloud-provider/1771-versioning-policy-for-external-cloud-providers).

For example, any version 1.28.X of the CCM, for any `X`, should be compatible with 1.28.Y, for any `Y` of Kubernetes.

However, other versions may work as well. For example, CCM 1.28.X may work with 1.29.Y, but it is not guaranteed.

## Deployment

**TL;DR**

1. Set Kubernetes binary arguments correctly
1. Get your Cherry Servers project ID and secret API token
1. Deploy your Cherry Servers project ID and secret API token to your cluster in a [secret](https://kubernetes.io/docs/concepts/configuration/secret/)
1. Deploy the CCM
1. Deploy the load balancer (optional)

### Kubernetes Binary Arguments

Control plane binaries in your cluster must start with the correct flags:

* `kubelet`: All kubelets in your cluster **MUST** set the flag `--cloud-provider=external`. This must be done for _every_ kubelet. Note that [k3s](https://k3s.io) sets its own CCM by default. If you want to use the CCM with k3s, you must disable the k3s CCM and enable this one, as `--disable-cloud-controller --kubelet-arg cloud-provider=external`.
* `kube-apiserver` and `kube-controller-manager` must **NOT** set the flag `--cloud-provider`. They then will use no cloud provider natively, leaving room for the Cherry Servers CCM.

**WARNING**: setting the kubelet flag `--cloud-provider=external` will taint all nodes in a cluster with `node.cloudprovider.kubernetes.io/uninitialized`.
The CCM itself will untaint those nodes when it initializes them.
Any pod that does not tolerate that taint will be unscheduled until the CCM is running.

You **must** set the kubelet flag the first time you run the kubelet. Stopping the kubelet, adding it after,
and then restarting it will not work.

#### Kubernetes node names must match the device name

[By default, the kubelet will name nodes based on the node's hostname.Cherry Servers device hostnames are set based on the name of the device.