https://github.com/linode/karpenter-provider-linode
Linode Karpenter provider
https://github.com/linode/karpenter-provider-linode
Last synced: 3 months ago
JSON representation
Linode Karpenter provider
- Host: GitHub
- URL: https://github.com/linode/karpenter-provider-linode
- Owner: linode
- License: apache-2.0
- Created: 2025-12-16T14:47:45.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-03-02T15:24:17.000Z (4 months ago)
- Last Synced: 2026-03-02T18:47:32.205Z (4 months ago)
- Language: Go
- Size: 897 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: code-of-conduct.md
- Security: .github/security-notice.md
Awesome Lists containing this project
README
# Karpenter Provider Linode
---
*PLEASE NOTE*: This project is considered ALPHA quality and should NOT be used for production, as it is currently in active development. Use at your own risk. APIs, configuration file formats, and functionality are all subject to change frequently. That said, please try it out in your development and test environments and let us know if it works. Contributions welcome! Thanks!
---
Table of contents:
- [Features Overview](#features-overview)
- [Installation](#installation)
- [Install utilities](#install-tools)
- [Create a cluster](#create-a-cluster)
- [Configure Helm chart values](#configure-helm-chart-values)
- [Install Karpenter](#install-karpenter)
- [Using Karpenter](#using-karpenter)
- [Create NodePool](#create-nodepool)
- [Scale up deployment](#scale-up-deployment)
- [Scale down deployment](#scale-down-deployment)
- [Delete Karpenter nodes manually](#delete-karpenter-nodes-manually)
- [Cleanup](#cleanup)
- [Delete the cluster](#delete-the-cluster)
- [Known issues](#known-issues)
## Features Overview
The LKE Karpenter Provider enables node autoprovisioning using [Karpenter](https://karpenter.sh/) on your LKE cluster.
Karpenter improves the efficiency and cost of running workloads on Kubernetes clusters by:
* **Watching** for pods that the Kubernetes scheduler has marked as unschedulable
* **Evaluating** scheduling constraints (resource requests, nodeselectors, affinities, tolerations, and topology spread constraints) requested by the pods
* **Provisioning** nodes that meet the requirements of the pods
* **Removing** the nodes when the nodes are no longer needed
## Provider Modes
This provider supports two operating modes:
1. **LKE Mode (Default)**: Creates LKE Node Pools for each provisioned node. This is the simplest method and recommended for most users.
2. **Instance Mode**: Creates standard Linode Instances. This offers granular control over instance settings (SSH keys, placement groups, etc.) but requires more manual configuration. This is currently in **development and not yet fully functional**.
See [Configuration Documentation](docs/CONFIGURATION.md) for full details on modes and available settings.
## Installation
### Install tools
Install these tools before proceeding:
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
* [Helm](https://helm.sh/docs/intro/install/)
### Create a cluster
1. Create a new LKE cluster with any amount of nodes in any region.
This can be easily done in [Linode Cloud Manager](https://cloud.linode.com/) or via the [Linode CLI](https://techdocs.akamai.com/cloud-computing/docs/getting-started-with-the-linode-cli).
2. Download the cluster's kubeconfig when ready.
### Configure Helm chart values
The Karpenter Helm chart requires specific configuration values to work with an LKE cluster.
1. Create a Linode PAT if you don't already have a `LINODE_TOKEN` env var set. Karpenter will use this for managing nodes in the LKE cluster.
2. Set the variables:
```bash
export CLUSTER_NAME=
export KUBECONFIG=
export KARPENTER_NAMESPACE=kube-system
export LINODE_TOKEN=
# Optional: specify region explicitly (auto-discovered in LKE mode if not set)
# export LINODE_REGION=
# Optional: Set mode directly (default is lke)
# export KARPENTER_MODE=lke
```
**Note**: In LKE mode (default), Karpenter automatically discovers the cluster region from the Linode API using the cluster name. You can optionally set `LINODE_REGION` to override this behavior.
### Install Karpenter
Use the configured environment variables to install Karpenter using Helm:
```bash
helm upgrade --install --namespace "${KARPENTER_NAMESPACE}" --create-namespace karpenter-crd charts/karpenter-crd
helm upgrade --install --namespace "${KARPENTER_NAMESPACE}" --create-namespace karpenter charts/karpenter \
--set settings.clusterName=${CLUSTER_NAME} \
--set apiToken=${LINODE_TOKEN} \
--wait
```
**Optional Configuration:**
- **Region**: Specify the region explicitly (only required for `instance` mode):
```bash
--set region=${LINODE_REGION}
```
- **Mode**: Choose the operating mode (default is `lke`):
- `lke`: Provisions nodes using LKE NodePools (recommended for LKE clusters)
- `instance`: Provisions nodes as direct Linode instances
```bash
--set settings.mode=lke
```
Check karpenter deployed successfully:
```bash
kubectl get pods --namespace "${KARPENTER_NAMESPACE}" -l app.kubernetes.io/name=karpenter
```
Check its logs:
```bash
kubectl logs -f -n "${KARPENTER_NAMESPACE}" -l app.kubernetes.io/name=karpenter -c controller
```
## Using Karpenter
### Create NodePool
A single Karpenter NodePool is capable of handling many different pod shapes. Karpenter makes scheduling and provisioning decisions based on pod attributes such as labels and affinity. In other words, Karpenter eliminates the need to manage many different node groups.
Create a default NodePool using the command below. (Additional examples available in the repository under [`examples/v1`](/examples/v1).) The `consolidationPolicy` set to `WhenUnderutilized` in the `disruption` block configures Karpenter to reduce cluster cost by removing and replacing nodes. As a result, consolidation will terminate any empty nodes on the cluster. This behavior can be disabled by setting consolidateAfter to `Never`, telling Karpenter that it should never consolidate nodes.
Note: This NodePool will create capacity as long as the sum of all created capacity is less than the specified limit.
```bash
cat <