From bb4baf407e14b483f365fd7711def285e96370a6 Mon Sep 17 00:00:00 2001
From: "Alex Ellis (OpenFaaS Ltd)" <alexellis2@gmail.com>
Date: Fri, 27 Oct 2023 12:22:01 +0100
Subject: [PATCH] Add notes to README for k3sup plan

Signed-off-by: Alex Ellis (OpenFaaS Ltd) <alexellis2@gmail.com>
---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/README.md b/README.md
index 26de909..3f1b49d 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@ How do you say it? Ketchup, as in tomato.
     - [Merging clusters into your KUBECONFIG](#merging-clusters-into-your-kubeconfig)
     - [😸 Join some agents to your Kubernetes server](#-join-some-agents-to-your-kubernetes-server)
     - [Use your hardware authentication / 2FA or SSH Agent](#use-your-hardware-authentication--2fa-or-ssh-agent)
+    - [K3sup plan for automation](#k3sup-plan-for-automation)
     - [Create a multi-master (HA) setup with external SQL](#create-a-multi-master-ha-setup-with-external-sql)
     - [Create a multi-master (HA) setup with embedded etcd](#create-a-multi-master-ha-setup-with-embedded-etcd)
     - [👨‍💻 Micro-tutorial for Raspberry Pi (2, 3, or 4) 🥧](#-micro-tutorial-for-raspberry-pi-2-3-or-4-)
@@ -285,6 +286,60 @@ Now run any `k3sup` command, and your SSH key will be requested from the ssh-age
 
 You can also specify an SSH key with `--ssh-key` if you want to use a specific key-pair.
 
+### K3sup plan for automation
+
+A new command was added to k3sup to help with automating large amounts of nodes.
+
+`k3sup plan` reads a JSON input file containing hosts, and will generate an installation command for a number of servers and agents.
+
+Example input file:
+
+```json
+[
+  {
+    "hostname": "node-a-1",
+    "ip": "192.168.129.138"
+  },
+  {
+    "hostname": "node-a-2",
+    "ip": "192.168.129.128"
+  },
+  {
+    "hostname": "node-a-3",
+    "ip": "192.168.129.131"
+  },
+  {
+    "hostname": "node-a-4",
+    "ip": "192.168.129.130"
+  },
+  {
+    "hostname": "node-a-5",
+    "ip": "192.168.129.127"
+  }
+]
+```
+
+The following will create 1x primary server, with 2x additional servers within a HA etcd cluster, the last two nodes will be added as agents:
+
+```bash
+k3sup plan \
+  devices.json \
+  --user ubuntu \
+  --servers 3 \
+  --background > bootstrap.sh
+```
+
+Then make the file executable and run it:
+
+```bash
+chmod +x bootstrap.sh
+./bootstrap.sh
+```
+
+Watch a demo with dozens of Firecracker VMs: [Testing Kubernetes at Scale with bare-metal](https://youtu.be/o4UxRw-Cc8c)
+
+The initial version of `k3sup plan` has a reduced set of flags such as `--k3s-extra-args`, but contributions are welcomed from users and sponsors.
+
 ### Create a multi-master (HA) setup with external SQL
 
 The easiest way to test out k3s' multi-master (HA) mode with external storage, is to set up a Mysql server using DigitalOcean's managed service.