Skip to content

Commit

Permalink
📖 Misc improvements to docs (#792)
Browse files Browse the repository at this point in the history 
* Sort list of supported distributions in the matrix

Signed-off-by: Mauro Morales <mauro.morales@spectrocloud.com>

* Add support matrix to FAQ and rephrasing

Signed-off-by: Mauro Morales <mauro.morales@spectrocloud.com>

* Extend qrcode page

- Add alert to let the user know that only standard images provide this
  functionality
- Change script to download agent to get the latest version
- Rephrasing

Signed-off-by: Mauro Morales <mauro.morales@spectrocloud.com>

* Rephrasing of Immutable page

Signed-off-by: Mauro Morales <mauro.morales@spectrocloud.com>

* Modify qrcode note

Signed-off-by: Mauro Morales <mauro.morales@spectrocloud.com>

---------

Signed-off-by: Mauro Morales <mauro.morales@spectrocloud.com>
  • Loading branch information
@mauromorales
mauromorales committed Jan 31, 2023
1 parent 1f66ce7 commit 5c97cdc
Show file tree
Hide file tree
Showing 4 changed files with 53 additions and 46 deletions.
39 changes: 20 additions & 19 deletions docs/content/en/docs/Architecture/immutable.md
View file
Expand Up @@ -6,11 +6,11 @@ date: 2022-11-13
description: >
---

Kairos adopts an immutable layout and derivatives created with its toolkit inherits the same immutability aspects.
Kairos adopts an immutable layout and derivatives created with its toolkit, inherit the same immutability attributes.

An immutable OS is a carefully engineered system which boots in a restricted, permissionless mode, where certain paths of the system are not writable. For instance, after installation it's not possible to install additional packages in the system, and any configuration change is discarded after reboot.
An immutable OS is a carefully engineered system which boots in a restricted, permissionless mode, where certain paths of the system are not writable. For instance, after installation it's not possible to add additional packages to the system, and any configuration change is discarded after reboot.

A running Linux-based OS system will look like with the following paths:
A running Linux-based OS system will have the following paths:

```
/usr/local - persistent ( partition label COS_PERSISTENT)
Expand All @@ -24,37 +24,38 @@ A running Linux-based OS system will look like with the following paths:

## Benefits of using an Immutable System

There are many reasons why you would like to use an immutable system, and this is genuinely, a good question. There are various perspectives, one is from a security standpoint. It is far more secure than traditional systems—most of attack vectors relies on writing on the system or either installing persistent tools after a vector has been exploited.
There are many reasons why you would like to use an immutable system, in this article we'll present two of them.

From a maintenance perspective, configuration management tools like Chef, Puppet, or the likes are not needed as immutable systems and have only a configuration entry point, every other configuration is cleaned up automatically after a reboot.
1. From a security standpoint, it's far more secure than traditional systems. This is because most attack vectors rely on writing on the system, or installing persistent tools after a vector has been exploited.
2. From a maintenance perspective, configuration management tools like Chef, Puppet, or the likes aren't needed because immutable systems only have one configuration entry point. Every other configuration is cleaned up automatically after a reboot.

The benefit of rolling out the same system over a set of machines are obvious:
The benefit of rolling out the same system over a set of machines are the following:

- No snowflakes - All the machines ships the same image, configuration settings, and behavior. This allows to have a predictable infrastructure, predictable upgrades, and homogeneous configurations across your cluster.
- Configuration is driven via cloud-init. There is only one source of truth for the configuration, and that happens at bootstrap time. Anything else is handled afterwards—natively via Kubernetes, so no configuration management software is required.
- Reduced attack surface - Immutable systems cannot be modified or tampered at runtime. This enhances the security of a running OS, as changes on the system are not allowed.
- **No snowflakes** - All the machines are based on the same image, configuration settings and behavior. This allows to have a predictable infrastructure, predictable upgrades, and homogeneous configurations across your cluster.
- **Configuration is driven via cloud-init** - There is only one source of truth for the configuration, and that happens at bootstrap time. Anything else is handled afterwards—natively via Kubernetes, so no configuration management software is required.
- **Reduced attack surface** - Immutable systems cannot be modified or tampered at runtime. This enhances the security of a running OS, as changes on the system are not allowed.

Tools like Chef, Puppet, and Ansible share the same underlying issues when it comes to configuration management: nodes can have different version matrices of software and OS, which makes your set of nodes dishomogeneous and difficult to maintain and orchestrate from day 1 to day 2.
Tools like Chef, Puppet, and Ansible share the same underlying issues when it comes to configuration management. That is, nodes can have different version matrices of software and OS, which makes your set of nodes inhomogeneous and difficult to maintain and orchestrate from day 1 to day 2.

Kairos tackles the issue from another angle, as can turn _any_ distribution to an "immutable" system, distributed as a standard container image, which gets provisioned to the devices as declared. This allows to treat OSes with the same repeatable portability as containers for apps, removing snowflakes in your cluster. Container registries can be used either internally or externally to the cluster to propagate upgrades with customized versions of the OS (kernel, packages, and so on).
Kairos tackles the issue from different angle, as can turn _any_ distribution to an "immutable" system, distributed as a standard container image, which gets provisioned to the devices as declared. This allows to treat OSes with the same repeatable portability as containers for apps, removing snowflakes in your cluster. Container registries can be used either internally or externally to the cluster to propagate upgrades with customized versions of the OS (kernel, packages, and so on).

## Design

Kairos after installation will create the following partitions:

- A state partition that stores the container images which are going to be booted (active and passive, stored in `.img` format which are loopback mounted)
- A recovery partition that stores the container images used for recovery (in `.squashfs` format)
- A OEM partition (optional) that stores user configuration and cloud-config files
- A persistent partition to keep the data across reboot
- A state partition that stores the container images, which are going to be booted (active and passive, stored in `.img` format which are loopback mounted)
- A recovery partition that stores the container images, used for recovery (in `.squashfs` format)
- An OEM partition (optional) that stores user configuration and cloud-config files
- A persistent partition to keep the data across reboots

![Kairos-installation-partitioning](https://user-images.githubusercontent.com/2420543/195111190-3bdfb917-312a-40f4-b0bc-4a65a701c06b.png)

The persistent partition is mounted on boot to `/usr/local` and additional paths are mount-bind to it. Those configuration aspects are defined in a [cloud-config](https://github.com/kairos-io/kairos/blob/a1a9bef4dff30e0718fa4d2697f075ce37c7ed90/overlay/files/system/oem/11_persistency.yaml#L11) file. It is possible to override such configuration by providing it in the cloud-config provided during installation.
The persistent partition is mounted during boot on `/usr/local`, and additional paths are mount-bind to it. Those configuration aspects are defined in a [cloud-config](https://github.com/kairos-io/kairos/blob/a1a9bef4dff30e0718fa4d2697f075ce37c7ed90/overlay/files/system/oem/11_persistency.yaml#L11) file. It is possible to override such configuration, via a custom cloud-config, during installation.

The Recovery system allows to perform emergency tasks in case of failure of the active and passive images, and a fallback mechanism will take place in case of failures such as boots the partitions in this sequence: “A -> B -> Recovery”.
The Recovery system allows to perform emergency tasks, in case of failure from the active and passive images. Furthermore a fallback mechanism will take place, so that in case of failures the booting sequence will be as follows: “A -> B -> Recovery”.

The upgrade happens in a transition image and take place only after all the necessary steps are completed. An upgrade of the ‘A/B’ partitions can be done by [with Kubernetes](/upgrade/kubernetes) or [manually](/upgrade/manual). The upgrade will create a new pristine image that will be selected as active for the next reboot, the old one will be flagged as passive. If we are performing the same from the passive system, only the active is subject to changes.
The upgrade happens in a transition image and takes place only after all the necessary steps are completed. An upgrade of the ‘A/B’ partitions can be done [with Kubernetes](/upgrade/kubernetes) or [manually](/upgrade/manual). The upgrade will create a new pristine image, that will be selected as active for the next reboot, the old one will be flagged as passive. If we are performing the same from the passive system, only the active is subject to changes.

### Kernel and Initrd

The Kernel and Initrd are loaded from the system images and expected to be present in the container that are pulled down and used for upgrades. Differently from standard approaches, Kairos focuses on having static Initrds which are generated while constructing images consumed for upgrades - in opposite to generate Initramfs locally on the node. Indeed, a typical setup have kernels and initrd in a special boot partition dedicated for boot files - in Kairos instead the Kernel and Initrd are being loaded from the images, which are chainloaded from the bootloader (GRUB). This is a design choice to keep the entire OS stack confined as a single layer which gets pulled and swapped atomically during upgrades.
The Kernel and Initrd are loaded from the system images and are expected to be present in the container, that is pulled down and used for upgrades. Differently from standard approaches, Kairos focuses on having static Initrds, which are generated while building images used for upgrades - in opposite of generating Initramfs locally on the node. A typical setup has kernels and initrd in a special boot partition dedicated for boot files - in Kairos instead the Kernel and Initrd are being loaded from the images, which are chainloaded from the bootloader (GRUB). This is a design choice to keep the entire OS stack confined as a single layer which gets pulled and swapped atomically during upgrades.
17 changes: 12 additions & 5 deletions docs/content/en/docs/Installation/qrcode.md
View file
Expand Up @@ -7,15 +7,20 @@ description: >
Use the QR code displayed at boot to drive the installation
---

{{% alert title="Warning" %}}
You will need a Standard Kairos OS image in order to use QR Code feature.
{{% /alert %}}

By default Kairos will display a QR code after booting the ISO to install the machine:

![livecd](https://user-images.githubusercontent.com/2420543/189219806-29b4deed-b4a1-4704-b558-7a60ae31caf2.gif)


To trigger the installation process via QR code, you need to use the Kairos CLI and provide a cloud-config, as described in the [Getting started guide](/docs/getting-started). You can also see some examples of cloud config in our [Examples section](/docs/examples). The CLI is currently available only for Linux and Windows. It can be downloaded from the release artifact:
To trigger the installation process via QR code, you need to use the Kairos CLI and provide a Cloud Config, as described in the [Getting started guide](/docs/getting-started). You can also see some Cloud Config examples in our [Examples section](/docs/examples). The CLI is currently available only for Linux and Windows. It can be downloaded from the release artifact:

```bash
curl -L https://github.com/kairos-io/provider-kairos/releases/download/v1.0.0/kairos-cli-v1.0.0-Linux-x86_64.tar.gz -o - | tar -xvzf - -C .
VERSION=$(wget -q -O- https://api.github.com/repos/kairos-io/provider-kairos/releases/latest | jq -r '.tag_name')
curl -L https://github.com/kairos-io/provider-kairos/releases/download/${VERSION}/kairos-cli-${VERSION}-Linux-x86_64.tar.gz -o - | tar -xvzf - -C .
```

The CLI allows to register a node with a screenshot, an image, or a token. During pairing, the configuration is sent over, and the node will continue the installation process.
Expand All @@ -26,11 +31,13 @@ In a terminal window from your desktop/workstation, run:
kairos register --reboot --device /dev/sda --config config.yaml
```

**Note**:

- By default, the CLI will automatically take a screenshot to get the QR code. Make sure it fits into the screen. Alternatively, an image path or a token can be supplied via arguments (e.g. `kairos register /img/path` or `kairos register <token>`).
- The `--reboot` flag will make the node reboot automatically after the installation is completed.
- The `--device` flag determines the specific drive where Kairos will be installed. Replace `/dev/sda` with your drive. Any existing data will be overwritten, so please be cautious.
- The `--config` flag is used to specify the config file used by the installation process.

{{% alert title="Note" %}}
By default, the CLI will automatically take a screenshot to get the QR code. Make sure it fits into the screen. Alternatively, an image path or a token can be supplied via arguments (e.g. `kairos register /img/path` or `kairos register <token>`).
{{% /alert %}}

After a few minutes, the configuration is distributed to the node and the installation starts. At the end of the installation, the system is automatically rebooted.

18 changes: 9 additions & 9 deletions docs/content/en/docs/Reference/faq.md
View file
Expand Up @@ -8,28 +8,28 @@ description: >

## What is the difference between Kairos compared to Talos/Sidero Metal and Flatcar?

Kairos is distro-agnostic by design. Currently, you can pick among Alpine, openSUSE, or Ubuntu based images, but we are working on CRDs to let assemble OSes from other bases in a Kubernetes native way.
Kairos is distro-agnostic by design. Currently, you can pick among a list from the [supported matrix](/docs/reference/image_matrix/#image-flavors), but we are working on CRDs to let assemble OSes from other bases in a Kubernetes native way.

The key difference is that the OS is a distributed as a standard container—similarly how apps are distributed with container registries. You can also use `docker run` locally and inspect the OS, and similarly, push customizations by pointing nodes to a new image.
The key difference, is that the OS is distributed as a standard container, similar to how apps are distributed with container registries. You can also use `docker run` locally and inspect the OS, and similarly, push customizations by pointing nodes to a new image.

Kairos is also quite easy to get setup with. The P2P capabilities allows also to nodes to self-coordinates, so setting up multi-nodes cluster becomes quite cheap.
Also, Kairos is easy to setup. The P2P capabilities allow nodes to self-coordinate, simplifying the setting up of a multi-node cluster.

## What would be the difference between Kairos and Fedora Coreos?

Kairos is distribution agnostic. It supports openSUSE, Alpine, and Ubuntu. And, we plan to support Fedora, Almalinux, and Rockylinux too. In addition, we plan to have K3s automatically deploy Kubernetes (even by self-coordinating nodes).
Kairos is distribution agnostic. It supports all the distributions in the [supported matrix](/docs/reference/image_matrix/#image-flavors). In addition, we plan to have K3s automatically deploy Kubernetes (even by self-coordinating nodes).

It is OCI-based, and the system is based from a container image. That allows to run it also locally with `docker run` to inspect it, as well to customize and upgrade your nodes by just pointing at it. Think of it like containers apps, but bootable.
Additionally, Kairos is OCI-based, and the system is based from a container image. This makes it possible to also run it locally with `docker run` to inspect it, as well to customize and upgrade your nodes by just pointing at it. Think of it like containers apps, but bootable.

## If the OS is a container, what is running the container runtime beneath?

There is no real container runtime. The container is used to construct an image internally that is then used to boot the system in an A/B fashion, so there is no overhead at all. The system being booted is actually a snapshot of the container.
There is no real container runtime. The container is used to construct an image internally, that is then used to boot the system in an A/B fashion, so there is no overhead at all. The system being booted is actually a snapshot of the container.

## Does this let the OS "containers" install extra kernel extensions/drivers?

Every container/OS ships its own kernels and drivers in a single image, so you can customize that down the road quite easily. As every release is a standard container, you can customize just by creating your own Dockerfile and point your nodes at it. You can also use the CRDs that allows you to do that natively inside Kubernetes to automatize that process even further.
Every container/OS ships its own kernels and drivers within a single image, so you can customize that down the road quite easily. Since every release is a standard container, you can customize it just by writing your own Dockerfile and point your nodes at it. You can also use the CRDs, that allow you to do that natively inside Kubernetes to automate the process even further.

Kairos also supports live overlaying, but that doesn't apply to kernel modules. However, that is somewhat discouraged, as it introduces snowflakes in your clusters unless you have a management cluster.
Kairos also supports live overlaying, but that doesn't apply to kernel modules. However, that is somewhat discouraged, as it introduces snowflakes in your clusters unless you have a management cluster.

## How is the P2P mesh formed? Is there an external service for discovery?

The P2P mesh is optional and uses internally libp2p. You can use your own discovery bootstrap server or use the default already baked in the library, as well you can limit and scope that only to local networks. For machines behinds a NAT, nodes operate automatically as relay servers (hops) when they are detected to be capable of it. You can limit that to specific nodes or to let automatic discovery handle that.
The P2P mesh is optional and internally uses libp2p. You can use your own discovery bootstrap server or use the default already baked in the library. Furthermore you can limit and scope that only to local networks. For machines behinds a NAT, nodes operate automatically as relay servers (hops) when they are detected to be capable of it. You can limit that to specific nodes, or let automatic discovery handle it.

0 comments on commit 5c97cdc

Please sign in to comment.