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

In this Guide

Instructions are shown for manually installing the Linode CCM on your unmanaged Kubernetes cluster. This includes:

• Updating your Kubernetes cluster’s configuration to use the CCM for Node scheduling.

• Two options for installing the Linode CCM:

  • Using a Helm chart

  • Using a helper script to create a manifest file

• Updating the Linode CCM running on your cluster with its latest upstream changes.

Before You Begin

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. Generate a Linode APIv4 token. This is required for both methods of installing the Linode CCM in this guide.

Running the Linode Cloud Controller Manager

Update Your Cluster Configuration

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.

Install Linode CCM using Helm

Installing the Linode CCM using Helm is the preferred method. Helm chart contents are available in deploy/chart directory of the linode-cloud-controller-manager GitHub repository.

1. Install Helm

2. Install the ccm-linode repo.

   helm repo add ccm-linode https://linode.github.io/linode-cloud-controller-manager/
   helm repo update ccm-linode

3. Deploy the ccm-linode Helm chart.

   export LINODE_API_TOKEN=YOUR_LINODE_API_TOKEN
   export REGION=YOUR_LINODE_REGION
   helm install ccm-linode --set apiToken=$LINODE_API_TOKEN,region=$REGION ccm-linode/ccm-linode

For advanced configuration, one can specify their own values.yaml file when installing the Helm chart.

Install Linode CCM using Generated Manifest

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

1. Install Git on your local computer.

2. Clone the Linode CCM’s GitHub repository.

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

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

   cd linode-cloud-controller-manager/deploy/

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

5. 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.
   Note

   Helm can also be used to render the ccm-linode Helm chart and apply it manually.

   cd linode-cloud-controller-manager/
   helm template --set apiToken=$LINODE_API_TOKEN,region=$REGION deploy/chart/

Updating the Linode CCM

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:

   1	image: linode/linode-cloud-controller-manager:v0.4.12

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

   1	image: linode/linode-cloud-controller-manager:v0.4.20

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

   Important

   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.

Next Steps

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.