From 21df2367bb3d5fb7648360c572a89563311e02b7 Mon Sep 17 00:00:00 2001
From: Nico Schottelius <nico@nico-notebook.schottelius.org>
Date: Sun, 17 Nov 2019 18:49:40 +0100
Subject: [PATCH] [doc] Add guide on how to create VMs for ucloud

---
 docs/Makefile                                 |  1 -
 docs/source/index.rst                         |  1 +
 .../how-to-create-an-os-image-for-ucloud.rst  | 53 +++++++++++++++++++
 3 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 docs/source/usage/how-to-create-an-os-image-for-ucloud.rst

diff --git a/docs/Makefile b/docs/Makefile
index 80cc2bb..89a98ea 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -16,4 +16,3 @@ publish: build
 
 build:
 	$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)"
-
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 8f96640..b4dd510 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -14,6 +14,7 @@ Welcome to ucloud's documentation!
    introduction/installation
    usage/usage-for-admins
    usage/usage-for-users
+   usage/how-to-create-an-os-image-for-ucloud
 
 
 Indices and tables
diff --git a/docs/source/usage/how-to-create-an-os-image-for-ucloud.rst b/docs/source/usage/how-to-create-an-os-image-for-ucloud.rst
new file mode 100644
index 0000000..dad5f41
--- /dev/null
+++ b/docs/source/usage/how-to-create-an-os-image-for-ucloud.rst
@@ -0,0 +1,53 @@
+How to create VM images for ucloud
+==================================
+
+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)
+
+
+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.