Lightweight Kubernetes
 
 
 
 
Go to file
Brad Davidson 0a728b8ff9 Convert remaining http handlers over to use util.SendError
Signed-off-by: Brad Davidson <brad.davidson@rancher.com>
(cherry picked from commit f8e0648304)
Signed-off-by: Brad Davidson <brad.davidson@rancher.com>
2024-05-31 09:16:55 -07:00
.github Match setup-go caching key in GitHub Actions (#9890) 2024-04-15 09:52:24 -07:00
cmd Add certificate expiry check and warnings 2024-03-28 12:05:21 -07:00
conformance chore: Update sonobuoy image versions (#8910) 2024-01-02 10:59:39 -05:00
contrib add missing kernel config check 2024-05-31 09:16:55 -07:00
docs Add certificate expiry check and warnings 2024-03-28 12:05:21 -07:00
hack Add new CRD for etcd snapshots 2023-10-12 15:04:45 -07:00
manifests Update local-path-provisioner helper script 2024-05-31 09:16:55 -07:00
package Add /etc/passwd and /etc/group to k3s docker image 2024-03-27 16:41:46 -07:00
pkg Convert remaining http handlers over to use util.SendError 2024-05-31 09:16:55 -07:00
scripts Updating the script binary_size_check to complete the command name by adding .exe extension to the k3s binary name to make it available to run stat command 2024-05-31 09:16:55 -07:00
tests Improve tailscale test & add extra log in e2e tests 2024-05-28 22:24:09 +02:00
updatecli Add quotes to avoid useless updatecli updates 2024-04-08 19:49:29 +02:00
.dockerignore Faster K3s Binary Build Option (#7805) 2023-06-27 10:28:23 -07:00
.drone.yml Set correct release channel for e2e upgrade test (#10106) 2024-05-15 15:57:07 -07:00
.droneignore Update install.sh sha256sum (#8885) 2023-11-16 09:40:52 -08:00
.gitignore Add make commands to terraform automation and fix external dbs related issue (#7159) 2023-04-06 12:17:13 -03:00
.golangci.json Update to v1.28.0-k3s1 (#8199) 2023-08-23 00:09:31 +03:00
ADOPTERS.md Adding PITS and Getdeck Beiboot as adopters thanks to Schille and Miworfi for the additions (#7524) 2023-05-10 11:54:01 -07:00
BUILDING.md [master] changing package to k3s-io (#4846) 2022-03-02 15:47:27 -08:00
CODEOWNERS Update CODEOWNERS for k3s-io move 2020-12-10 08:52:22 -08:00
CODE_OF_CONDUCT.md chore: Update Code of Conduct to Redirect to CNCF CoC (#9104) 2024-01-02 11:44:46 -05:00
CONTRIBUTING.md Testing ADR (#9562) 2024-02-29 15:36:11 -08:00
DCO Simplify CONTRIBUTING.md 2020-06-23 10:41:15 -07:00
Dockerfile.dapper Update to v1.29.4 (#9960) 2024-04-16 19:57:56 -03:00
Dockerfile.local Update to v1.29.4 (#9960) 2024-04-16 19:57:56 -03:00
Dockerfile.manifest Update to v1.29.4 (#9960) 2024-04-16 19:57:56 -03:00
Dockerfile.test Bump spegel version 2024-05-31 09:16:55 -07:00
LICENSE Initial Commit 2019-01-01 01:23:01 -07:00
MAINTAINERS Remove Nikolai from MAINTAINERS list (#7088) 2023-03-14 14:33:06 -04:00
Makefile Faster K3s Binary Build Option (#7805) 2023-06-27 10:28:23 -07:00
README.md General updates to README (#8786) 2023-11-15 09:45:29 -08:00
ROADMAP.md General updates to README (#8786) 2023-11-15 09:45:29 -08:00
channel.yaml update stable channel to v1.29.4+k3s1 (#10031) 2024-04-29 09:58:06 -03:00
docker-compose.yml fix: agent volume in example docker compose (#9838) 2024-04-04 10:36:47 -07:00
go.mod Bump klipper-helm image for tls secret support 2024-05-31 09:16:55 -07:00
go.sum Bump klipper-helm image for tls secret support 2024-05-31 09:16:55 -07:00
install.sh Correct formatting of GH PR sha256sum artifact (#9472) 2024-03-01 08:45:01 -08:00
install.sh.sha256sum Correct formatting of GH PR sha256sum artifact (#9472) 2024-03-01 08:45:01 -08:00
k3s-rootless.service k3s-rootless.service: use fuse-overlayfs snapshotter 2021-06-01 13:13:21 -07:00
k3s.service Add 2>dev/null when checking nm-cloud systemd unit 2024-01-03 09:36:11 +01:00
main.go Add proctitle package with linux and windows constraints 2024-05-31 09:16:55 -07:00

README.md

K3s - Lightweight Kubernetes

Lightweight Kubernetes. Production ready, easy to install, half the memory, all in a binary less than 100 MB.

Great for:

  • Edge
  • IoT
  • CI
  • Development
  • ARM
  • Embedding k8s
  • Situations where a PhD in k8s clusterology is infeasible

What is this?

K3s is a fully conformant production-ready Kubernetes distribution with the following changes:

  1. It is packaged as a single binary.
  2. It adds support for sqlite3 as the default storage backend. Etcd3, MySQL, and Postgres are also supported.
  3. It wraps Kubernetes and other components in a single, simple launcher.
  4. It is secure by default with reasonable defaults for lightweight environments.
  5. It has minimal to no OS dependencies (just a sane kernel and cgroup mounts needed).
  6. It eliminates the need to expose a port on Kubernetes worker nodes for the kubelet API by exposing this API to the Kubernetes control plane nodes over a websocket tunnel.

K3s bundles the following technologies together into a single cohesive distribution:

These technologies can be disabled or swapped out for technologies of your choice.

Additionally, K3s simplifies Kubernetes operations by maintaining functionality for:

  • Managing the TLS certificates of Kubernetes components
  • Managing the connection between worker and server nodes
  • Auto-deploying Kubernetes resources from local manifests in realtime as they are changed.
  • Managing an embedded etcd cluster

Current Status

FOSSA Status Nightly CI Build Status Integration Test Coverage Unit Test Coverage

What's with the name?

We wanted an installation of Kubernetes that was half the size in terms of memory footprint. Kubernetes is a 10 letter word stylized as k8s. So something half as big as Kubernetes would be a 5 letter word stylized as K3s. There is neither a long-form of K3s nor official pronunciation.

Is this a fork?

No, it's a distribution. A fork implies continued divergence from the original. This is not K3s's goal or practice. K3s explicitly intends not to change any core Kubernetes functionality. We seek to remain as close to upstream Kubernetes as possible. However, we maintain a small set of patches (well under 1000 lines) important to K3s's use case and deployment model. We maintain patches for other components as well. When possible, we contribute these changes back to the upstream projects, for example, with SELinux support in containerd. This is a common practice amongst software distributions.

K3s is a distribution because it packages additional components and services necessary for a fully functional cluster that go beyond vanilla Kubernetes. These are opinionated choices on technologies for components like ingress, storage class, network policy, service load balancer, and even container runtime. These choices and technologies are touched on in more detail in the What is this? section.

How is this lightweight or smaller than upstream Kubernetes?

There are two major ways that K3s is lighter weight than upstream Kubernetes:

  1. The memory footprint to run it is smaller
  2. The binary, which contains all the non-containerized components needed to run a cluster, is smaller

The memory footprint is reduced primarily by running many components inside of a single process. This eliminates significant overhead that would otherwise be duplicated for each component.

The binary is smaller by removing third-party storage drivers and cloud providers, explained in more detail below.

What have you removed from upstream Kubernetes?

This is a common point of confusion because it has changed over time. Early versions of K3s had much more removed than the current version. K3s currently removes two things:

  1. In-tree storage drivers
  2. In-tree cloud provider

Both of these have out-of-tree alternatives in the form of CSI and CCM, which work in K3s and which upstream is moving towards.

We remove these to achieve a smaller binary size. They can be removed while remaining conformant because neither affects core Kubernetes functionality. They are also dependent on third-party cloud or data center technologies/services, which may not be available in many K3s' use cases.

What's next?

Check out our roadmap to see what we have planned moving forward.

Release cadence

K3s maintains pace with upstream Kubernetes releases. Our goal is to release patch releases within one week, and new minors within 30 days.

Our release versioning reflects the version of upstream Kubernetes that is being released. For example, the K3s release v1.27.4+k3s1 maps to the v1.27.4 Kubernetes release. We add a postfix in the form of +k3s<number> to allow us to make additional releases using the same version of upstream Kubernetes while remaining semver compliant. For example, if we discovered a high severity bug in v1.27.4+k3s1 and needed to release an immediate fix for it, we would release v1.27.4+k3s2.

Documentation

Please see the official docs site for complete documentation.

Quick-Start - Install Script

The install.sh script provides a convenient way to download K3s and add a service to systemd or openrc.

To install k3s as a service, run:

curl -sfL https://get.k3s.io | sh -

A kubeconfig file is written to /etc/rancher/k3s/k3s.yaml and the service is automatically started or restarted. The install script will install K3s and additional utilities, such as kubectl, crictl, k3s-killall.sh, and k3s-uninstall.sh, for example:

sudo kubectl get nodes

K3S_TOKEN is created at /var/lib/rancher/k3s/server/node-token on your server. To install on worker nodes, pass K3S_URL along with K3S_TOKEN environment variables, for example:

curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh -

Manual Download

  1. Download k3s from latest release, x86_64, armhf, arm64 and s390x are supported.
  2. Run the server.
sudo k3s server &
# Kubeconfig is written to /etc/rancher/k3s/k3s.yaml
sudo k3s kubectl get nodes

# On a different node run the below. NODE_TOKEN comes from
# /var/lib/rancher/k3s/server/node-token on your server
sudo k3s agent --server https://myserver:6443 --token ${NODE_TOKEN}

Contributing

Please check out our contributing guide if you're interested in contributing to K3s.

Security

Security issues in K3s can be reported by sending an email to security@k3s.io. Please do not file issues about security issues.