📖 Add examples and bundles section (#618)

* 📖 Add examples Signed-off-by: mudler <[email protected]> * 📖 Add Bundles docs Signed-off-by: mudler <[email protected]> * 📖 Update config reference for p2p block Signed-off-by: mudler <[email protected]> * 📖 Add Fedora and Debian images, update status Signed-off-by: mudler <[email protected]> * 📖 Add bundles and core sections Signed-off-by: mudler <[email protected]> * 📖 Rephrase Signed-off-by: mudler <[email protected]> * 📖 Rephrase Signed-off-by: mudler <[email protected]> * 📖 Add p2p samples Signed-off-by: mudler <[email protected]> * 📖 Rephrase Signed-off-by: mudler <[email protected]> * 📖 Rephrase Signed-off-by: mudler <[email protected]> * Update docs/content/en/docs/Advanced/bundles.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Examples/multi-node-p2p-ha-kubevip.md Co-authored-by: Mauro Morales <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Examples/bundles.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Examples/multi-node-p2p-ha-kubevip.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Examples/multi-node-p2p.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Examples/multi-node.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Examples/multi-node-p2p-ha.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Examples/single-node.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * Update docs/content/en/docs/Reference/configuration.md Co-authored-by: Dimitris Karakasilis <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> * 📖 Review Signed-off-by: mudler <[email protected]> * 📖 Review Signed-off-by: mudler <[email protected]> Signed-off-by: mudler <[email protected]> Signed-off-by: Ettore Di Giacinto <[email protected]> Co-authored-by: Dimitris Karakasilis <[email protected]> Co-authored-by: Mauro Morales <[email protected]>
kairos-io · Jan 11, 2023 · 1cb4996 · 1cb4996
1 parent 286efcf
commit 1cb4996
Show file tree

Hide file tree

Showing 18 changed files with 754 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -42,6 +42,7 @@ For comprehensive docs, tutorials, and examples see our [documentation](https://
 
 ## Project status
 
+- (Dec 28, 2022) announcing the release of Kairos 1.4, which includes self-coordinated automated HA deployment via p2p and with [KubeVIP](https://kube-vip.io/). Check out the [docs](https://kairos.io/docs/installation/p2p/) for more information on this exciting new feature! Support for Ubuntu, Debian, and Fedora is also added in the Kairos 1.4 release. Expanding the number of supported operating systems currently available to pick from!
 - (Sep 29, 2022) announcing Kairos 1.0 GA availability. Kairos is now backed by Spectro Cloud, which contributes to the project. Kairos will remain fully community-driven and has its own governance. See the [announcement](https://github.com/kairos-io/kairos/discussions/159)
 - (Sep 15, 2022) the c3OS project has a new name: Kairos! For full details, see https://github.com/c3os-io/c3os/issues/88 and https://github.com/c3os-io/c3os/discussions/84.
 

diff --git a/docs/content/en/docs/Advanced/bundles.md b/docs/content/en/docs/Advanced/bundles.md
@@ -0,0 +1,151 @@
+---
+title: "Bundles"
+linkTitle: "Bundles"
+weight: 5
+description: >
+    Bundles are a powerful feature of Kairos that allow you to customize and configure your operating system. This section explains how to use and build custom bundles.
+
+---
+
+Bundles are a powerful feature of Kairos that allow you to customize and configure your operating system, as well as your Kubernetes cluster. Whether you want to add custom logic, install additional packages, or make any other changes to your system, bundles make it easy to apply these changes after installation or before bootstrapping a node.
+
+Bundles are container images containing only files (and not full OS) that can be used to install new software or extend the cloud-init syntax. You can find community-supported bundles in the [community-bundles](https://github.com/kairos-io/community-bundles) repository.
+
+## Consuming Bundles
+
+To use a bundle in your Kairos configuration, you will need to specify the type of bundle and the target image in your cloud-config file.
+
+To apply a bundle before Kubernetes starts, you can include it in your config like this:
+
+```yaml
+#cloud-config
+
+bundles:
+- targets:
+  - run://<image>
+```
+
+Replace `<image>` with the URL or path to the bundle image. The prefix (e.g. `run://`) indicates the type of bundle being used.
+
+To install a bundle after installation instead (for those bundles that explicitly supports that), use the following:
+
+```yaml
+#cloud-config
+install:
+ bundles:
+ - targets:
+   - run://<image>
+```
+
+One of the benefits of using bundles is that they can also extend the cloud-config keywords available during installation. This means that by adding bundles to your configuration file, you can add new blocks of configuration options and customize your system even further.
+
+A full config using a bundle from [community-bundles](https://github.com/kairos-io/community-bundles) that configures `metalLB` might look like this:
+
+```yaml
+#cloud-config
+
+hostname: kairoslab-{{ trunc 4 .MachineID }}
+users:
+- name: kairos
+  ssh_authorized_keys:
+  # Add your github user here!
+  - github:mudler
+
+k3s:
+  enable: true
+  args:
+  - --disable=servicelb
+
+# Specify the bundle to use
+bundles:
+- targets:
+  - run://quay.io/kairos/community-bundles:metallb_latest
+
+# Specify metallb settings
+metallb:
+  version: 0.13.7
+  address_pool: 192.168.1.10-192.168.1.20
+```
+
+## Bundle types
+
+Bundles can carry also binaries that can be overlayed in the rootfs, either while [building images](/docs/advanced/build) or with [Live layering](https://kairos.io/docs/advanced/livelayering/).
+
+Kairos supports three types of bundles:
+
+- **Container**: This type is a bare container that simply contains files that need to be copied to the system. It is useful for copying over configuration files, scripts, or any other static content that you want to include on your system (prefixed with `container:` or `docker:`).
+
+- **Run**: This type is also a bare container, but it comes with a script that can be run during the installation phase to add custom logic. This is useful for performing any necessary setup or configuration tasks that need to be done before the cluster is fully deployed (prefixed with `run:`).
+
+- **Package**: This type is a [luet](https://luet.io) package that will be installed in the system. It requires you to specify a `luet` repository in order to work. Luet packages are a powerful way to manage dependencies and install software on your system (prefixed with `luet:`).
+
+
+{{% alert title="Note" %}}
+In the future, Kairos will also support a local type for use in airgap situations, where you can pre-add bundles to the image before deployment.
+{{% /alert %}}
+
+It's important to note that bundles do not have any special meaning in terms of immutability. They install files over paths that are mutable in the system, as they are simply overlaid during the boot process. This means that you can use bundles to make changes to your system at any time, even after it has been deployed.
+
+## Create bundles
+
+To build your own bundle, you will need to create a Dockerfile and any necessary files and scripts. A bundle is simply a container image that includes all the necessary assets to perform a specific task.
+
+To create a bundle, you will need to define a base image and copy over any necessary files and scripts to the image. For example, you might use the following Dockerfile to create a bundle image that deploys everything inside `assets` in the Kubernetes cluster:
+
+```Dockerfile
+FROM alpine
+COPY ./run.sh /
+COPY ./assets /assets
+```
+
+And the associated `run.sh` that installs the assets depending on a cloud-config keyword can be:
+
+```bash
+#!/bin/bash
+
+K3S_MANIFEST_DIR="/var/lib/rancher/k3s/server/manifests/"
+
+mkdir -p $K3S_MANIFEST_DIR
+
+# IF the user sets `example.enable` in the input cloud config, we install our assets
+if [ "$(kairos-agent config get example.enable | tr -d '\n')" == "true" ]; then
+  cp -rf assets/* $K3S_MANIFEST_DIR
+fi
+```
+
+This Dockerfile creates an image based on the Alpine base image, and copies over a script file and some assets to the image. 
+You can then add any additional instructions to the Dockerfile to install necessary packages, set environment variables, or perform any other tasks required by your bundle.
+
+Once you have created your Dockerfile and any necessary script files, you can build your bundle image by running docker build and specifying the path to your Dockerfile. 
+
+For example:
+
+```bash
+docker build -t <image> .
+```
+
+This command will build an image with the name you specify ( replace `<image>` accordingly ) based on the instructions in your Dockerfile.
+
+After building your bundle image, you will need to push it to a registry so that it can be accessed by Kairos. You can use a public registry like Docker Hub. To push your image to a registry, use the docker push command. For example:
+
+```bash
+docker push <image>
+```
+
+This will push the `<image>` to your specified registry.
+
+And use it with Kairos:
+
+```yaml
+#cloud-config
+
+bundles:
+- targets:
+  # e.g. run://quay.io/...:tag
+  - run://<image>
+
+example:
+  enable: true
+```
+
+See the [community-bundles repository](https://github.com/kairos-io/community-bundles) for further examples.
diff --git a/docs/content/en/docs/Advanced/customizing.md b/docs/content/en/docs/Advanced/customizing.md
@@ -45,7 +45,7 @@ c58930881bc4: Pushed
 ...
 ```
 
-You can use your custom image with the `kairos-agent upgrade` command, or with the [system-upgrade-controller in Kubernetes](/docs/upgrade/kubernetes). Here's how to use the `kairos-agent` command:
+You can use your custom image when [upgrading nodes manually](/docs/upgrade/manual), [with Kubernetes](/docs/upgrade/kubernetes) or [specifying it in the cloud-config during installation](/docs/examples/core). Here's how to do it manually with the `kairos-agent` command:
 
 ```
 node:/home/kairos # kairos-agent  upgrade --image docker.io/<your-org>/myos:0.1

diff --git a/docs/content/en/docs/Advanced/p2p.md b/docs/content/en/docs/Advanced/p2p.md
diff --git a/docs/content/en/docs/Examples/_index.md b/docs/content/en/docs/Examples/_index.md
@@ -5,3 +5,13 @@ weight: 5
 description: > 
     This section contains various examples, how-to and tutorial to use Kairos
 ---
+
+Welcome to the examples section of the Kairos documentation! Here, you will find a variety of examples that demonstrate how to use Kairos to create and manage Kubernetes clusters on bare metal.
+
+## Getting Started
+
+- [Quick Start Guide](/docs/getting-started): This guide will walk you through the process of installing Kairos and creating your first Kubernetes cluster on bare metal.
+
+## Troubleshooting
+
+- [Troubleshooting common issues](/docs/reference/troubleshooting): This page provides solutions to some common issues that you may encounter while using Kairos.
diff --git a/docs/content/en/docs/Examples/bundles.md b/docs/content/en/docs/Examples/bundles.md
@@ -0,0 +1,59 @@
+---
+title: "Bundles"
+linkTitle: "Bundles"
+weight: 4
+description: > 
+    This section describe examples on how to use a Kairos bundle to deploy MetalLB on top of K3s
+---
+
+Welcome to the guide on setting up MetalLB on a Kairos cluster with K3s! This tutorial will walk you through the steps of using a Kairos [bundle](/docs/advanced/bundles) to automatically configure MetalLB on your local network with an IP range of `192.168.1.10-192.168.1.20`. Check out the [MetalLB](/docs/examples/metallb) example to configure it without a [bundle](/docs/advanced/bundles).
+
+For those unfamiliar with [MetalLB](https://metallb.universe.tf/), it is an open-source load balancer implementation for bare metal Kubernetes clusters that utilizes standard routing protocols. When used with K3s on Kairos, it provides load balancing capabilities and helps manage IP addresses within a cluster. 
+
+
+## Prerequisites
+
+Before we begin, you will need to have the following:
+
+1. Kairos [provider-kairos](https://github.com/kairos-io/provider-kairos) artifacts which includes K3s
+1. A baremetal node to run the installation
+
+## Installation
+
+1. Follow the [Installation](/docs/installation) documentation for Kairos.
+1. Use the following cloud configuration file when setting up Kairos:
+
+```yaml
+#cloud-config
+
+hostname: metal-{{ trunc 4 .MachineID }}
+users:
+- name: kairos
+  # Change to your pass here
+  passwd: kairos
+  ssh_authorized_keys:
+  # Replace with your github user and un-comment the line below:
+  # - github:mudler
+
+k3s:
+  enabled: true
+  args:
+  - --disable=traefik,servicelb
+
+# Specify the bundle to use
+bundles:
+- targets:
+  - run://quay.io/kairos/community-bundles:metallb_latest
+
+# Specify metallb settings, available only with the bundle.
+metallb:
+  version: 0.13.7
+  address_pool: 192.168.1.10-192.168.1.20
+```
+
+There are a few key points to note in the configuration file:
+
+- The `metallb` block is provided by the MetalLB bundle and allows us to specify the version of MetalLB that we want to deploy, as well as the `address_pool` available for our services.
+- The `bundles` block enables the `run` [bundle](/docs/advanced/bundles) type. The bundle we are using is part of the [community-bundles](https://github.com/kairos-io/community-bundles) repository.
+
+And that's it! With these steps, you should now have MetalLB configured and ready to use on your Kairos cluster. If you have any questions or run into any issues, don't hesitate to check out the [bundle documentation](/docs/advanced/bundles) or reach out to the community for support.
diff --git a/docs/content/en/docs/Examples/core.md b/docs/content/en/docs/Examples/core.md
@@ -0,0 +1,60 @@
+---
+title: "Using Kairos Core Images as an Installer"
+linkTitle: "Using Kairos Core Images as an Installer"
+weight: 4
+description: > 
+    Core images serve as the foundation for creating downstream images or as an installer for deploying other images during the installation process. In this guide, we'll take a closer look at using Kairos core images as an installer to deploy other container images.
+---
+
+Kairos is a powerful, open-source meta-distribution that allows you to easily deploy and manage nodes on your Immutable infrastructure.
+
+One key feature of Kairos is the use of its core images, which are released as part of the [kairos-io/kairos](https://github.com/kairos-io/kairos) repository and can be found in the releases section. These core images serve as the foundation for creating [downstream images](/docs/advanced/customizing) or as an installer for deploying other images during the installation process. In this guide, we'll take a closer look at using Kairos core images as an installer to deploy other container images.
+
+## Getting started
+
+To begin using Kairos core images as an installer, you'll need to start by using the artifacts from the [Kairos core](https://github.com/kairos-io/kairos/releases) repository. These images do not include the Kubernetes engine, so you'll need to configure the container image you want to deploy in the `install.image` field of your cloud config file. A list of available images can be found in [our support matrix](/docs/reference/image_matrix).
+
+For example, let's say you want to use an image from the provider-kairos repository. Your cloud config file might look something like this:
+
+```yaml
+#cloud-config
+install:
+ # Here we specify the image that we want to deploy
+ image: "docker:quay.io/kairos/kairos-opensuse:v1.4.0-k3sv1.26.0-k3s1"
+```
+
+Once you've chosen your image, you can move on to the installation process by following the steps outlined in our [Installation](/docs/installation) documentation.
+
+For example, a full cloud-config might look like this:
+
+```yaml
+#cloud-config
+
+install:
+ device: "auto"
+ auto: true
+ reboot: true
+ # Here we specify the image that we want to deploy
+ image: "docker:quay.io/kairos/kairos-opensuse:v1.4.0-k3sv1.26.0-k3s1"
+
+hostname: "test"
+users:
+- name: "kairos"
+  passwd: "kairos"
+  ssh_authorized_keys:
+  - github:mudler
+
+k3s:
+  enable: true
+```
+
+## Configuring the installation
+
+As you move through the installation process, there are a few key points to keep in mind when configuring your cloud config file:
+
+- We set `install.image` to the container image that we want to deploy. This can be an image from [our support matrix](/docs/reference/image_matrix), a [custom image](/docs/advanced/customizing) or an [image from scratch](/docs/reference/build).
+- After the installation is complete, the configuration in the `k3s` block will take effect. This is because after the installation, the system will boot into the image specified in the `install.image` field, which in the example above is an image with the Kairos K3s provider, as such the configuration in the k3s block will become active.
+
+With these steps, you should now be able to use Kairos core images as an installer to deploy other container images. The process is straightforward and gives you the flexibility to customize your deployments and build custom images as needed.
+
+You can also refer our [troubleshoot](/docs/reference/troubleshooting) document if you are facing any issue while following the installation process.
diff --git a/docs/content/en/docs/Advanced/ha.md → docs/content/en/docs/Examples/ha.md b/docs/content/en/docs/Advanced/ha.md → docs/content/en/docs/Examples/ha.md
diff --git a/docs/content/en/docs/Examples/metallb.md b/docs/content/en/docs/Examples/metallb.md
@@ -1,20 +1,22 @@
 ---
 title: "MetalLB"
 linkTitle: "MetalLB"
-weight: 3
+weight: 4
 description: > 
     This section describe examples on how to deploy Kairos with k3s and MetalLB
 ---
 
-In the example below we will use a bare metal host to provision a Kairos node in the local network with K3s and MetalLB using the `192.168.1.10-192.168.1.20` IP range.
+Welcome to the guide on using MetalLB with Kairos and K3s on a bare metal host!
 
-[MetalLB](https://metallb.universe.tf/) is a load-balancer implementation for bare metal Kubernetes clusters, using standard routing protocols. Can be used with [k3s](https://k3s.io) in Kairos to provide Load Balancing for baremetal and manage IPs in a cluster.
+In this tutorial, we'll walk through the steps of setting up a Kairos node on your local network using the `192.168.1.10-192.168.1.20` IP range, with MetalLB and K3s.
 
-## Installation
+But first, let's talk a little bit about what [MetalLB](https://metallb.universe.tf/) and [K3s](https://k3s.io/) are. MetalLB is a load balancer implementation for bare metal Kubernetes clusters that uses standard routing protocols. It's particularly useful when used with K3s in Kairos, as it provides load balancing for bare metal clusters and helps manage IP addresses within the cluster. K3s is a lightweight Kubernetes distribution that is easy to install and maintain.
 
-Use the [provider-kairos](https://github.com/kairos-io/provider-kairos) artifacts which contains `k3s`.
+Now that you have an understanding of what we'll be working with, let's dive into the installation process.
 
-We will use the [k3s manifest method](/docs/reference/configuration#kubernetes-manifests) to deploy `MetaLB`.
+Check out the [bundle](/docs/examples/bundles) example to configure `MetalLB` with bundles. Bundles provides a streamlined way to publish and re-use configuration between nodes.
+
+To get started, you'll need to use the [provider-kairos](https://github.com/kairos-io/provider-kairos) artifacts, which include k3s. We'll be using the [k3s manifest method](/docs/reference/configuration#kubernetes-manifests) to deploy MetalLB.
 
 Follow the [Installation](/docs/installation) documentation, and use the following cloud config file with Kairos:
 
@@ -74,10 +76,12 @@ write_files:
           - default
 ```
 
-Notably:
+There are a few things to note in this configuration file:
+
+- In the `k3s` block, we use the `--disable` flag to disable `traefik` and `servicelb`, which are the default load balancers for k3s.
+- In the `write_files` block, we write manifests (in `/var/lib/rancher/k3s/server/manifests/` see [docs](/docs/reference/configuration#kubernetes-manifests)) to deploy MetalLB and configure it to use the `192.168.1.10-192.168.1.20` IP range. Make sure to choose an IP range that doesn't interfere with your local DHCP network.
 
-- we use the `k3s` block to disable `traefik` and `servicelb` (the default `k3s` load balancer)
-- we use `write_files` to write manifests to the default `k3s` manifest directory (`/var/lib/rancher/k3s/server/manifests/`) see [docs](/docs/reference/configuration#kubernetes-manifests) to deploy `MetalLB` and configure it with the `192.168.1.10-192.168.1.20` IP range. Make sure to pick up a range which doesn't interfere with your local DHCP network.
+And that's it! You should now have MetalLB and K3s set up on your Kairos node.
 
 ## Resources