From cbcaf636506e138542e1580098d29057b9558b69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Floure?= <timothee.floure@posteo.net>
Date: Sun, 26 Jan 2020 12:04:37 +0100
Subject: [PATCH] Update VM images documentation (upstream images,
 uncloud-init)

---
 docs/source/{admin-guide => admin-guide.rst} | 39 ++----------
 docs/source/index.rst                        |  5 +-
 docs/source/vm-images.rst                    | 66 ++++++++++++++++++++
 3 files changed, 74 insertions(+), 36 deletions(-)
 rename docs/source/{admin-guide => admin-guide.rst} (72%)
 create mode 100644 docs/source/vm-images.rst

diff --git a/docs/source/admin-guide b/docs/source/admin-guide.rst
similarity index 72%
rename from docs/source/admin-guide
rename to docs/source/admin-guide.rst
index ec6597d..b62808d 100644
--- a/docs/source/admin-guide
+++ b/docs/source/admin-guide.rst
@@ -56,40 +56,13 @@ To start host we created earlier, execute the following command
 
     ucloud host ungleich.ch
 
-Create OS Image
----------------
+File & image scanners
+--------------------------
 
-Create ucloud-init ready OS image (Optional)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This step is optional if you just want to test ucloud. However, sooner or later
-you want to create OS images with ucloud-init to properly
-contexualize VMs.
-
-1. Start a VM with OS image on which you want to install ucloud-init
-2. Execute the following command on the started VM
-
-   .. code-block:: sh
-
-    apk add git
-    git clone https://code.ungleich.ch/ucloud/ucloud-init.git
-    cd ucloud-init
-    sh ./install.sh
-3. Congratulations. Your image is now ucloud-init ready.
-
-
-Upload Sample OS Image
-~~~~~~~~~~~~~~~~~~~~~~
-Execute the following to get the sample OS image file.
-
-.. code-block:: sh
-
-    mkdir /var/www/admin
-    (cd /var/www/admin && wget https://cloud.ungleich.ch/s/qTb5dFYW5ii8KsD/download)
-
-Run File Scanner and Image Scanner
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Currently, our uploaded file *alpine-untouched.qcow2* is not tracked by ucloud. We can only make
-images from tracked files. So, we need to track the file by running File Scanner
+Let's assume we have uploaded an *alpine-uploaded.qcow2* disk images to our
+uncloud server. Currently, our *alpine-untouched.qcow2* is not tracked by
+ucloud. We can only make images from tracked files. So, we need to track the
+file by running File Scanner
 
 .. code-block:: sh
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index b31cff3..fad1f88 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -11,14 +11,13 @@ Welcome to ucloud's documentation!
    :caption: Contents:
 
    introduction
-   user-guide
    setup-install
+   vm-images
+   user-guide
    admin-guide
-   user-guide/how-to-create-an-os-image-for-ucloud
    troubleshooting
    hacking
 
-
 Indices and tables
 ==================
 
diff --git a/docs/source/vm-images.rst b/docs/source/vm-images.rst
new file mode 100644
index 0000000..4b2758a
--- /dev/null
+++ b/docs/source/vm-images.rst
@@ -0,0 +1,66 @@
+VM images
+==================================
+
+Overview
+---------
+
+ucloud tries to be least invasise towards VMs and only require
+strictly necessary changes for running in a virtualised
+environment. This includes configurations for:
+
+* Configuring the network
+* Managing access via ssh keys
+* Resizing the attached disk(s)
+
+Upstream images
+---------------
+
+The 'official' uncloud images are defined in the `uncloud/images
+<https://code.ungleich.ch/uncloud/images>`_ repository.
+
+How to make you own Uncloud images
+----------------------------------
+
+.. note::
+  It is fairly easy to create your own images for uncloud, as the common
+  operations (which are detailed below) can be automatically handled by the
+  `uncloud/uncloud-init <https://code.ungleich.ch/uncloud/uncloud-init>`_ tool.
+
+Network configuration
+~~~~~~~~~~~~~~~~~~~~~
+All VMs in ucloud are required to support IPv6. The primary network
+configuration is always done using SLAAC. A VM thus needs only to be
+configured to
+
+* accept router advertisements on all network interfaces
+* use the router advertisements to configure the network interfaces
+* accept the DNS entries from the router advertisements
+
+
+Configuring SSH keys
+~~~~~~~~~~~~~~~~~~~~
+
+To be able to access the VM, ucloud support provisioning SSH keys.
+
+To accept ssh keys in your VM, request the URL
+*http://metadata/ssh_keys*. Add the content to the appropriate user's
+**authorized_keys** file. Below you find sample code to accomplish
+this task:
+
+.. code-block:: sh
+
+    tmp=$(mktemp)
+    curl -s http://metadata/ssk_keys > "$tmp"
+    touch ~/.ssh/authorized_keys # ensure it exists
+    cat ~/.ssh/authorized_keys >> "$tmp"
+    sort "$tmp" | uniq > ~/.ssh/authorized_keys
+
+
+Disk resize
+~~~~~~~~~~~
+In virtualised environments, the disk sizes might grow. The operating
+system should detect disks that are bigger than the existing partition
+table and resize accordingly. This task is os specific.
+
+ucloud does not support shrinking disks due to the complexity and
+intra OS dependencies.