summaryrefslogtreecommitdiff
path: root/doc/rtd
diff options
context:
space:
mode:
authorChad Smith <chad.smith@canonical.com>2020-01-16 15:36:37 -0700
committerGitHub <noreply@github.com>2020-01-16 15:36:37 -0700
commit02fdd98e6908d12f8e78eae8a7a013c2832985b1 (patch)
tree28c38c845e1ec251b5095f88396fc1ee7275547a /doc/rtd
parent651e24066ba4b9464c7843553f60d17a459cf06e (diff)
downloadvyos-cloud-init-02fdd98e6908d12f8e78eae8a7a013c2832985b1.tar.gz
vyos-cloud-init-02fdd98e6908d12f8e78eae8a7a013c2832985b1.zip
docs: add proposed SRU testing procedure (#167)
Co-Authored-By: Daniel Watkins <daniel@daniel-watkins.co.uk>
Diffstat (limited to 'doc/rtd')
-rw-r--r--doc/rtd/topics/debugging.rst101
1 files changed, 101 insertions, 0 deletions
diff --git a/doc/rtd/topics/debugging.rst b/doc/rtd/topics/debugging.rst
index afcf2679..0d416f32 100644
--- a/doc/rtd/topics/debugging.rst
+++ b/doc/rtd/topics/debugging.rst
@@ -163,3 +163,104 @@ commandline:
Inspect cloud-init.log for output of what operations were performed as a
result.
+
+.. _proposed_sru_testing:
+
+Stable Release Updates (SRU) testing for cloud-init
+===================================================
+Once an Ubuntu release is stable (i.e. after it is released), updates for it
+must follow a special procedure called a "stable release update" (or `SRU`_).
+
+The cloud-init project has a specific process it follows when validating
+a cloud-init SRU, documented in the `CloudinitUpdates`_ wiki page.
+
+Generally an SRU test of cloud-init performs the following:
+
+ * Install a pre-release version of cloud-init from the
+ **-proposed** APT pocket (e.g. **bionic-proposed**)
+ * Upgrade cloud-init and attempt a clean run of cloud-init to assert the new
+ version of cloud-init works properly the specific platform and Ubuntu series
+ * Check for tracebacks or errors in behavior
+
+
+Manual SRU verification procedure
+---------------------------------
+Below are steps to manually test a pre-release version of cloud-init
+from **-proposed**
+
+.. note::
+ For each Ubuntu SRU, the Ubuntu Server team manually validates the new version of cloud-init
+ on these platforms: **Amazon EC2, Azure, GCE, OpenStack, Oracle,
+ Softlayer (IBM), LXD, KVM**
+
+1. Launch a VM on your favorite platform, providing this cloud-config
+ user-data and replacing `<YOUR_LAUNCHPAD_USERNAME>` with your username:
+
+.. code-block:: yaml
+
+ ## template: jinja
+ #cloud-config
+ ssh_import_id: [<YOUR_LAUNCHPAD_USERNAME>]
+ hostname: SRU-worked-{{v1.cloud_name}}
+
+2. Wait for current cloud-init to complete, replace `<YOUR_VM_IP>` with the IP
+ address of the VM that you launched in step 1:
+
+.. code-block:: bash
+
+ CI_VM_IP=<YOUR_VM_IP>
+ # Make note of the datasource cloud-init detected in --long output.
+ # In step 5, you will use this to confirm the same datasource is detected after upgrade.
+ ssh ubuntu@$CI_VM_IP -- cloud-init status --wait --long
+
+3. Set up the **-proposed** pocket on your VM and upgrade to the **-proposed**
+ cloud-init:
+
+.. code-block:: bash
+
+ # Create a script that will add the -proposed pocket to APT's sources
+ # and install cloud-init from that pocket
+ cat > setup_proposed.sh <<EOF
+ #/bin/bash
+ mirror=http://archive.ubuntu.com/ubuntu
+ echo deb \$mirror \$(lsb_release -sc)-proposed main | tee \
+ /etc/apt/sources.list.d/proposed.list
+ apt-get update -q
+ apt-get install -qy cloud-init
+ EOF
+
+ scp setup_proposed.sh ubuntu@$CI_VM_IP:.
+ ssh ubuntu@$CI_VM_IP -- sudo bash setup_proposed.sh
+
+4. Change hostname, clean cloud-init's state, and reboot to run cloud-init
+ from scratch:
+
+.. code-block:: bash
+
+ ssh ubuntu@$CI_VM_IP -- sudo hostname something-else
+ ssh ubuntu@$CI_VM_IP -- sudo cloud-init clean --logs --reboot
+
+5. Validate **-proposed** cloud-init came up without error
+
+.. code-block:: bash
+
+ # Block until cloud-init completes and verify from --long the datasource
+ # from step 1. Errors would show up in --long
+
+ ssh ubuntu@$CI_VM_IP -- cloud-init status --wait --long
+ # Make sure hostname was set properly to SRU-worked-<cloud name>
+ ssh ubuntu@$CI_VM_IP -- hostname
+ # Check for any errors or warnings in cloud-init logs.
+ # (This should produce no output if successful.)
+ ssh ubuntu@$CI_VM_IP -- grep Trace "/var/log/cloud-init*"
+
+6. If you encounter an error during SRU testing:
+
+ * Create a `new cloud-init bug`_ reporting the version of cloud-init
+ affected
+ * Ping upstream cloud-init on Freenode's `#cloud-init IRC channel`_
+
+.. _SRU: https://wiki.ubuntu.com/StableReleaseUpdates
+.. _CloudinitUpdates: https://wiki.ubuntu.com/CloudinitUpdates
+.. _new cloud-init bug: https://bugs.launchpad.net/cloud-init/+filebug
+.. _#cloud-init IRC channel: https://webchat.freenode.net/?channel=#cloud-init