Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify readme #407

Merged
merged 5 commits into from
Nov 17, 2020
Merged

Clarify readme #407

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0910dec
Improve README
ncopa Nov 16, 2020
753ca56
Move build and smoke test to the bottom of README
ncopa Nov 16, 2020
745f064
Tell where to find the admin.conf in README
ncopa Nov 16, 2020
9a4b8f2
Use docker image from docker hub
ncopa Nov 17, 2020
52e3f58
Add quick start to README
ncopa Nov 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 57 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,26 @@

![k0s logo](k0s-logo-full-color.svg)

k0s is yet another Kubernetes distro. Yes. But we do some of the things pretty different from other distros out there.
k0s is an all-inclusive Kubernetes distribution with all the required bells and whistles preconfigured to make building a Kubernetes clusters a matter of just copying an executable to every host and running it.

## Key Features

- Packaged as a single static binary
- Self-hosted, isolated control plane
- Variety of storage backends: etcd, SQLite, MySQL (or any compatible), PostgreSQL
- Elastic control-plane
- Vanilla upstream Kubernetes
- Supports custom container runtimes (containerd is the default)
- Supports custom Container Network Interface (CNI) plugins (calico is the default)
- Supports x86_64 and arm64

## Quick start

```
curl -sSLf get.k0s.sh | sh
k0s server --enable-worker
```

k0s is a single binary all-inclusive Kubernetes distribution with all the required bells and whistles preconfigured to make building a Kubernetes clusters a matter of just copying an executable to every host and running it.

![k0s demo](k0s_demo.gif)

Expand All @@ -30,18 +47,9 @@ _We have seen Kubernetes with cumbersome lifecycle management, high minimum syst
**→** k0s Kubernetes is designed to be lightweight at its core. It comes with a tool to automate cluster lifecycle management. It works on any host OS and infrastructure, and may be extended to work with any use cases such as edge, IoT, telco, public clouds, private data centers, and hybrid & hyper converged cloud applications without sacrificing the pure Kubernetes compliance or amazing developer experience.


Some of the high level goals of the project:
- Packaged as a single binary
- Self-hosted, isolated control plane
- Variety of storage backends: etcd, SQLite, MySQL (or any compatible), PostgreSQL
- Elastic control-plane
- Vanilla upstream Kubernetes

See more in [architecture docs](docs/architecture.md)

## Features
## Other Features

- One static binary
- Kubernetes 1.19
- Containerd 1.4
- Control plane storage options:
Expand All @@ -61,6 +69,8 @@ See more in [architecture docs](docs/architecture.md)
- Metrics-server 0.3
- Custom roles\profiles for worker nodes

See more in [architecture docs](docs/architecture.md)

## Status

We're still on the 0.x.y release versions, so things are not yet 100% stable. That includes both stability of different APIs and config structures as well as the stability of k0s itself. While we do have some basic smoke testing happening we're still lacking more longer running stability testing for k0s based clusters. And of course we only test some known configuration combinations.
Expand All @@ -75,38 +85,6 @@ While some Kubernetes distros package everything and the kitchen sink in, k0s tr

With strong enough arguments we might take in new addons but in general those should be something that are essential for the "core" of k0s.

## Build

`k0s` can be built in 3 different ways:

Fetch official binaries (except `kine` and `konnectivity-server`, which are built from source):
```
make EMBEDDED_BINS_BUILDMODE=fetch
```

Build Kubernetes components from source as static binaries (requires docker):
```
make EMBEDDED_BINS_BUILDMODE=docker
```

Build k0s without any embedded binaries (requires that Kubernetes
binaries are pre-installed on the runtime system):
```
make EMBEDDED_BINS_BUILDMODE=none
```

Builds can be done in parallel:
```
make -j$(nproc)
```

## Smoke test

To run a smoke test after build:
```
make check-basic
```

## Cluster bootstrapping

Move the built `k0s` binary to each of the nodes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest adding this too:

curl -SsLf get.k0s.sh

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't comment on the line below but I'd also give an example with enable-worker

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need --enable-worker example in the readme when we have it in the FAQ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking it is most likely how someone is going to try k0s

Expand All @@ -128,6 +106,8 @@ Join a new worker node to the cluster by running:
k0s worker "superlongtokenfrompreviousphase"
```

The client config (for kubectl or lens) can be found in `/var/lib/k0s/pki/admin.conf` on the controller. Replace `localhost` with the public IP address for the control plane.

ncopa marked this conversation as resolved.
Show resolved Hide resolved
For more detailed description see [creating cluster documentation](docs/create-cluster.md).

### k0s-in-docker
Expand All @@ -136,7 +116,7 @@ For more detailed description see [creating cluster documentation](docs/create-c

To run a single node controller+worker combo, just run it in docker with:
```
docker run -d --name k0s-controller --hostname controller --privileged -v /var/lib/k0s -p 6443:6443 docker.pkg.github.com/k0sproject/k0s/k0s:<version>
docker run -d --name k0s-controller --hostname controller --privileged -v /var/lib/k0s -p 6443:6443 k0sproject/k0s
```

Replace `<version>` with a released version number, we build the image for all tagged releases.
Expand All @@ -147,3 +127,35 @@ Just grab the kubeconfig with `docker exec k0s-controller cat /var/lib/k0s/pki/a

Read more details at [running k0s in Docker](docs/k0s-in-docker.md).

## Build

`k0s` can be built in 3 different ways:

Fetch official binaries (except `kine` and `konnectivity-server`, which are built from source):
```
make EMBEDDED_BINS_BUILDMODE=fetch
```

Build Kubernetes components from source as static binaries (requires docker):
```
make EMBEDDED_BINS_BUILDMODE=docker
```

Build k0s without any embedded binaries (requires that Kubernetes
binaries are pre-installed on the runtime system):
```
make EMBEDDED_BINS_BUILDMODE=none
```

Builds can be done in parallel:
```
make -j$(nproc)
```

## Smoke test

To run a smoke test after build:
```
make check-basic
```