Browse Source

(docs) Update README.md

Fixed various issues in README.md.

This incorporates #2141, which should be closed because there are other spelling fixes in this PR.

- correct spelling
- correct grammar
- remove verbiage for stronger intent and clarity
- formatting consistency (e.g., spacing, numbered lists, etc.)

Signed-off-by: Vladislav Doster <mvdoster@gmail.com>
pull/3549/head
vlad doster 4 years ago committed by Brad Davidson
parent
commit
a5cff7e143
  1. 39
      README.md

39
README.md

@ -25,7 +25,6 @@ K3s is a [fully conformant](https://github.com/cncf/k8s-conformance/pulls?q=is%3
1. It has minimal to no OS dependencies (just a sane kernel and cgroup mounts needed). 1. It has minimal to no OS dependencies (just a sane kernel and cgroup mounts needed).
1. 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. 1. 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: K3s bundles the following technologies together into a single cohesive distribution:
* [Containerd](https://containerd.io/) & [runc](https://github.com/opencontainers/runc) * [Containerd](https://containerd.io/) & [runc](https://github.com/opencontainers/runc)
@ -33,7 +32,7 @@ K3s bundles the following technologies together into a single cohesive distribut
* [CoreDNS](https://coredns.io/) * [CoreDNS](https://coredns.io/)
* [Metrics Server](https://github.com/kubernetes-sigs/metrics-server) * [Metrics Server](https://github.com/kubernetes-sigs/metrics-server)
* [Traefik](https://containo.us/traefik/) for ingress * [Traefik](https://containo.us/traefik/) for ingress
* [Klipper-lb](https://github.com/k3s-io/klipper-lb) as an embedded service loadbalancer provider * [Klipper-lb](https://github.com/k3s-io/klipper-lb) as an embedded service load balancer provider
* [Kube-router](https://www.kube-router.io/) for network policy * [Kube-router](https://www.kube-router.io/) for network policy
* [Helm-controller](https://github.com/k3s-io/helm-controller) to allow for CRD-driven deployment of helm manifests * [Helm-controller](https://github.com/k3s-io/helm-controller) to allow for CRD-driven deployment of helm manifests
* [Kine](https://github.com/k3s-io/kine) as a datastore shim that allows etcd to be replaced with other databases * [Kine](https://github.com/k3s-io/kine) as a datastore shim that allows etcd to be replaced with other databases
@ -44,55 +43,59 @@ These technologies can be disabled or swapped out for technologies of your choic
Additionally, K3s simplifies Kubernetes operations by maintaining functionality for: Additionally, K3s simplifies Kubernetes operations by maintaining functionality for:
* Managing the TLS certificates of Kubernetes componenents * Managing the TLS certificates of Kubernetes components
* Managing the connection between worker and server nodes * Managing the connection between worker and server nodes
* Auto-deploying Kubernetes resources from local manifests, in realtime as they are changed. * Auto-deploying Kubernetes resources from local manifests in realtime as they are changed.
* Managing an embedded etcd cluster (work in progress) * Managing an embedded etcd cluster (work in progress)
What's with the name? What's with the name?
-------------------- --------------------
We wanted an installation of Kubernetes that was half the size in terms of memory footprint. Kubernetes is a 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 10 letter word stylized as k8s. So something half as big as Kubernetes would be a 5 letter word stylized as
K3s. There is no long form of K3s and no official pronunciation. K3s. There is neither a long-form of K3s nor official pronunciation.
Is this a fork? 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 to not change any core Kubernetes functionality. We seek to remain as close to upstream Kubernetes as possible. We do maintain a small set of patches (well under 1000 lines) important to K3s's usecase 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](https://github.com/containerd/cri/pull/1487/commits/24209b91bf361e131478d15cfea1ab05694dc3eb). 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?](#what-is-this) section. 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](https://github.com/containerd/cri/pull/1487/commits/24209b91bf361e131478d15cfea1ab05694dc3eb). 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?](#what-is-this) section.
How is this lightweight or smaller than upstream Kubernetes? How is this lightweight or smaller than upstream Kubernetes?
--- ---
There are two major ways that K3s is lighter weight 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 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 1. 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 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, which is explained in more detail below. 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? 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 current version. K3s currently removes two things:
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 1. In-tree storage drivers
2. In-tree cloud provider 1. In-tree cloud provider
Both of these have out-of-tree alternatives in the form of [CSI](https://github.com/container-storage-interface/spec/blob/master/spec.md) and [CCM](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/), which work in K3s and which upstream is moving towards. Both of these have out-of-tree alternatives in the form of [CSI](https://github.com/container-storage-interface/spec/blob/master/spec.md) and [CCM](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/), 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 affect core Kubernetes functionality. They are also dependent on third-party cloud or data center technologies/services, which may not be available in many of K3s's usecases. 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? What's next?
--- ---
Check out our [roadmap](ROADMAP.md) to see what we have planned moving forward. Check out our [roadmap](ROADMAP.md) to see what we have planned moving forward.
Release cadence Release cadence
--- ---
K3s maintains pace with upstream Kubernetes releases. Our goal is to release patch releases on the same day as upstream and minor releases within a few days. K3s maintains pace with upstream Kubernetes releases. Our goal is to release patch releases on the same day as upstream and minor releases within a few days.
Our release versioning reflects the version of upstream Kubernetes that is being released. For example, the K3s release [v1.18.6+k3s1](https://github.com/k3s-io/k3s/releases/tag/v1.18.6%2Bk3s1) maps to the `v1.18.6` 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](https://semver.org/) compliant. For example, if we discovered a high severity bug in `v1.18.6+k3s1` and needed to release an immediate fix for it, we would release `v1.18.6+k3s2`. Our release versioning reflects the version of upstream Kubernetes that is being released. For example, the K3s release [v1.18.6+k3s1](https://github.com/k3s-io/k3s/releases/tag/v1.18.6%2Bk3s1) maps to the `v1.18.6` 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](https://semver.org/) compliant. For example, if we discovered a high severity bug in `v1.18.6+k3s1` and needed to release an immediate fix for it, we would release `v1.18.6+k3s2`.
Documentation Documentation
------------- -------------
@ -104,7 +107,7 @@ Quick-Start - Install Script
The `install.sh` script provides a convenient way to download K3s and add a service to systemd or openrc. 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 just run: To install k3s as a service, run:
```bash ```bash
curl -sfL https://get.k3s.io | sh - curl -sfL https://get.k3s.io | sh -
@ -118,7 +121,7 @@ sudo kubectl get nodes
``` ```
`K3S_TOKEN` is created at `/var/lib/rancher/k3s/server/node-token` on your server. `K3S_TOKEN` is created at `/var/lib/rancher/k3s/server/node-token` on your server.
To install on worker nodes we should pass `K3S_URL` along with To install on worker nodes, pass `K3S_URL` along with
`K3S_TOKEN` or `K3S_CLUSTER_SECRET` environment variables, for example: `K3S_TOKEN` or `K3S_CLUSTER_SECRET` environment variables, for example:
```bash ```bash
@ -129,7 +132,7 @@ Manual Download
--------------- ---------------
1. Download `k3s` from latest [release](https://github.com/k3s-io/k3s/releases/latest), x86_64, armhf, and arm64 are supported. 1. Download `k3s` from latest [release](https://github.com/k3s-io/k3s/releases/latest), x86_64, armhf, and arm64 are supported.
2. Run server. 1. Run the server.
```bash ```bash
sudo k3s server & sudo k3s server &

Loading…
Cancel
Save