Installing the Linode CCM on an Unmanaged Kubernetes Cluster

The Linode Cloud Controller Manager (CCM) provides a way for Kubernetes clusters to access additional Linode services. Linode’s CCM provides access to Linode’s load balancing service, Linode NodeBalancers.

NodeBalancers provide your Kubernetes cluster with a reliable way of exposing resources to the public internet. The Linode CCM handles the creation and deletion of the NodeBalancer, and, along with other Master Plane components, correctly identifies the resources, and their networking, that the NodeBalancer will route traffic to. Whenever a Kubernetes Service of the LoadBalancer type is created, your Kubernetes cluster will create a Linode NodeBalancer service with the help of the Linode CCM.

Note

This guide will show you how to manually install the Linode CCM on an unmanaged Kubernetes cluster. This guide exists to support special use cases. For example, if you would like to experiment with various elements of a Kubernetes control plane.

If you would like to use Kubernetes for production scenarios and make use of Linode NodeBalancers to expose your cluster’s resources, it is recommended that you use the Linode Kubernetes Engine to deploy your cluster. An LKE cluster’s control plane has the Linode CCM preinstalled and does not require any of the steps included in this guide.

Similarly, if you would like to deploy an unmanaged Kubernetes cluster on Linode, the best way to accomplish that is using Terraform and the Linode K8s module. The Linode K8s module will also include the Linode CCM preinstalled on the Kubernetes master’s control plane and does not require any of the steps included in this guide.

If you have used the Linode Kubernetes Engine (LKE) or the Linode Terraform K8s module to deploy your cluster, you should instead refer to the Getting Started with Load Balancing on a Linode Kubernetes Engine (LKE) Cluster guide for steps on adding and configuring NodeBalancers on your Kubernetes cluster.

You will manually install the Linode CCM on your unmanaged Kubernetes cluster. This will include:

• Updating your Kubernetes cluster’s configuration to use the CCM for Node scheduling.
• Using a helper script to create a manifest file that will install the Linode CCM and supporting resources on your cluster.
• Updating the Linode CCM running on your cluster with its latest upstream changes.

1. Deploy a new unmanaged Kubernetes cluster. You can deploy an unmanaged Kubernetes cluster on Linode by following the Getting Started with Kubernetes: Use kubeadm to Deploy a Cluster on Linode

   Note

   It is recommended that you install the Linode CCM on a new Kubernetes cluster, as there are a number of issues that prevent the CCM from running on Nodes that are in the “Ready” state.

2. Ensure you have kubectl installed on your local computer and you can access your Kubernetes cluster with it.

3. Install Git on your local computer.

4. Generate a Linode APIv4 token.

In order to run the Linode Cloud Controller Manager:

• You must start kubelet with the --cloud-provider=external flag.
• kube-apiserver and kube-controller-manager must NOT supply the --cloud-provider flag.

These configurations will change the behavior of your cluster and how it interacts with its Nodes. For more details, visit the upstream Cloud Controller documentation.

The Linode CCM’s GitHub repository provides a helper script that creates a Kubernetes manifest file that you can use to install the CCM on your cluster. These steps should be run on your local computer and were tested on a macOS.

Note

You will need your Linode APIv4 token to complete the steps in this section.

1. Clone the Linode CCM’s GitHub repository.

    git clone git@github.com:linode/linode-cloud-controller-manager.git
   

2. Move into the CCM repository’s deploy directory.

    cd linode-cloud-controller-manager/deploy/
   

3. Run the generate-manifest.sh script. Ensure you replace $LINODE_API_TOKEN with your own Linode APIv4 token and us-east with the Linode region where your cluster resides. To view a list of regions, you can use the Linode CLI, or you can view the Regions API endpoint.

    ./generate-manifest.sh $LINODE_API_TOKEN us-east
   

   After running the script, you should have a new manifest file in the repo’s deploy directory, ccm-linode.yaml.

4. Apply the manifest file to your cluster in order to install the Linode CCM and the required supporting resources.

    kubectl create -f ccm-linode.yaml
   

   Note

   You can create your own ccm-linode.yaml manifest file by editing the contents of the ccm-linode-template.yaml file and changing the values of the data.apiToken and data.region fields with your own desired values. This template file is located in the deploy directory of the Linode CCM repository.

The easiest way to update the Linode CCM is to edit the DaemonSet that creates the Linode CCM Pod. To do so:

1. Run the edit command to make changes to the CCM Daemonset.

    kubectl edit ds -n kube-system ccm-linode
   

2. The CCM Daemonset manifest will appear in vim. Press i to enter insert mode. Navigate to spec.template.spec.image and change the field’s value to the desired version tag. For instance, if you had the following image:

    image: linode/linode-cloud-controller-manager:v0.2.2
   

   You could update the image to v0.2.3 by changing the image tag:

    image: linode/linode-cloud-controller-manager:v0.2.3
   

   For a complete list of CCM version tags, visit the CCM DockerHub page.

   Caution

   The CCM Daemonset manifest may list latest as the image version tag. This may or may not be pointed at the latest version. To ensure the latest version, it is recommended to first check the CCM DockerHub page, then use the most recent release.

3. Press escape to exit insert mode, then type :wq and press enter to save your changes. A new Pod will be created with the new image, and the old Pod will be deleted.

Now that you have the Linode CCM installed on your Kubernetes cluster, you can learn how to add and configure Linode NodeBalancers on your cluster.