From f95ed32c100ac272cfc8f9f683747135cfe05ee4 Mon Sep 17 00:00:00 2001
From: mudler <mudler@c3os.io>
Date: Mon, 9 Jan 2023 22:10:58 +0100
Subject: [PATCH] :book: Add bundles and core sections

Signed-off-by: mudler <mudler@c3os.io>
---
 docs/content/en/docs/Examples/bundles.md      | 52 +++++++++++++++++++
 docs/content/en/docs/Examples/core.md         | 50 ++++++++++++++++++
 .../en/docs/Reference/configuration.md        |  2 +
 3 files changed, 104 insertions(+)
 create mode 100644 docs/content/en/docs/Examples/bundles.md
 create mode 100644 docs/content/en/docs/Examples/core.md

diff --git a/docs/content/en/docs/Examples/bundles.md b/docs/content/en/docs/Examples/bundles.md
new file mode 100644
index 000000000..e24fe0a8b
--- /dev/null
+++ b/docs/content/en/docs/Examples/bundles.md
@@ -0,0 +1,52 @@
+---
+title: "Bundles"
+linkTitle: "Bundles"
+weight: 4
+description: > 
+    This section describe examples on how to use Kairos bundles to apply custom configurations
+---
+
+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. Instead of doing it manually as in the [MetalLB](/docs/examples/metallb) example, we will use a bundle to set up MetalLB automatically. See also the [bundle](/docs/advanced/bundles) documentation section to learn how to build bundles and how to use them. This section provides a simple example that uses a pre-configured bundle to setup `MetalLB`.
+
+[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.
+
+## Installation
+
+Use the [provider-kairos](https://github.com/kairos-io/provider-kairos) artifacts which contains `k3s`.
+
+We will use the MetalLB community [bundle](/docs/advanced/bundles) to deploy `MetaLB`.
+
+Follow the [Installation](/docs/installation) documentation, and use the following cloud config file with Kairos:
+
+```yaml
+#cloud-config
+
+hostname: metal-{{ trunc 4 .MachineID }}
+users:
+- name: kairos
+  # Change to your pass here
+  passwd: kairos
+  ssh_authorized_keys:
+  # Add your github user here!
+  - 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
+```
+
+Notably:
+
+- we use the `metallb` block that is provided by the metallb bundle and set the `MetalLB` versin that we want to deploy and the `address_pool` available for our services.
+- we use the `bundles` block to enable the `run` [bundle](/docs/advanced/bundles) type. The bundle used is part of [community-bundles](https://github.com/kairos-io/community-bundles)
diff --git a/docs/content/en/docs/Examples/core.md b/docs/content/en/docs/Examples/core.md
new file mode 100644
index 000000000..f9a9a75a1
--- /dev/null
+++ b/docs/content/en/docs/Examples/core.md
@@ -0,0 +1,50 @@
+---
+title: "Using core images"
+linkTitle: "Using core images"
+weight: 4
+description: > 
+    This section provides examples on how to use Kairos core images
+---
+
+Kairos core images are part of the [assets released](https://github.com/kairos-io/kairos/releases) by the [kairos-io/kairos](https://github.com/kairos-io/kairos) repository. The images don't include k3s - such images can be used either as base for customizing and creating downstream images, or either as installer to pull during installation and deploy other images. This examples show how to use core images standalone as installer to deploy other images. To use the image as base for customization, see [customizing](/docs/advanced/customizing).
+
+## Installation
+
+Use the [Kairos core](https://github.com/kairos-io/kairos/releases) artifacts which doesn't contain any Kubernetes engine, the only configuration section that needs to be applied is the portion about the container image:
+
+```yaml
+#cloud-config
+install:
+ # Here we specify the image that we want to deploy
+ image: "docker:<image>"
+```
+
+You can pick an `<image>` from [our support matrix](/docs/reference/image_matrix), in the example below we will use an image from [provider-kairos](https://github.com/kairos-io/provider-kairos).
+
+Follow the [Installation](/docs/installation) documentation, and use the following cloud config file:
+
+```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
+```
+
+Notably:
+
+- we set `install.image` to the container image that we want to deploy. That can be a [custom image](/docs/advanced/customizing) or an [image from scratch](/docs/reference/build)
+- we use the `k3s` block as we normally would do on a provider-kairos image. This is because after installation we would boot in the image specified in the `install.image` field, and thus the configuration would take effect
\ No newline at end of file
diff --git a/docs/content/en/docs/Reference/configuration.md b/docs/content/en/docs/Reference/configuration.md
index 3f4739cc3..ca7764641 100644
--- a/docs/content/en/docs/Reference/configuration.md
+++ b/docs/content/en/docs/Reference/configuration.md
@@ -32,6 +32,8 @@ install:
   poweroff: true
   # Set to true when installing without Pairing
   auto: true
+  # Use a different container image for the installation
+  image: "docker:.."
   # Add bundles in runtime
   bundles:
     - ...