Merge lp:~pedronis/tanuki-agent/tut-update-recomplete-n-tweaks into lp:tanuki-agent

[Samuele Pedroni]

reinstate tutorial additions/clarifications from 104-110 that got lost, plus some tweaks

tried to reinstate tutorial additions/clarifications from 104-110 that got lost, plus some tweaks that seemed off both before and after

[Celso Providelo (cprov)]

Thanks Samuele,

You have recovered all the bits I remember we discussed ...

Now let's decide how we are going to proceed with the agent binary builds, then perhaps give it another pass to ensure the instructions are correct (we are already missing 'apt-get install build-essential python3-dev' for running from source).

review: Approve

=== modified file 'docs/tutorial.md'
--- docs/tutorial.md	2015-10-16 21:36:04 +0000
+++ docs/tutorial.md	2015-10-21 11:35:25 +0000
@@ -11,15 +11,10 @@
 -   What you will need: A description of everything you will need to complete the tutorial.
 -   Introduction to SPI: A brief description of how the system works.
 -   Lab setup: Create and configure your own laboratory.
--   Snap creation: Create your own Snap, starting from an example app.
--   Configure SPI: Configure the SPI system, the heart of the solution.
--   Running the tests: To be written.
--   Tests results gathering and checking: To be written.
+-   Product update testing walkthrough: Walkthrough and configuration of how to test a product software update and check results.
+-   Other Testing Scenarios
 
-Some conventions: from time to time you will need to execute commands in
-a terminal. This will be indicated using ```this particular font``` and color,
-normally in a single different line. This font will also be used to specify
-filenames or any other cases where spelling matters.
+Some conventions: from time to time you will need to execute commands in a terminal. This will be indicated using ```this particular font and background color```, normally on a single different line. This font will also be used to specify filenames or any other cases where spelling matters.
 
 ## What you will need
 
@@ -58,46 +53,28 @@
 Download and install as follows:
 
     curl http://people.canonical.com/~ralsina/agent-daily-latest.tgz > spi-agent.tgz
-	tar -zxf spi-agent.tgz
-	cd agent-daily-*
+    tar -zxf spi-agent.tgz
+    cd agent-daily-*
 
 Perform initial setup and verification:
 
-	make bootstrap
-	. env/bin/activate
+     make bootstrap
+     . env/bin/activate
 
 At this point the prompt should look like this, indicating that the
 environment is activated:
 
-	(env)user@host:~user/foo$
+    (env)user@host:~user/foo$
 
 #### Configuring the Agent
 
 Once the Agent is installed, you need to create its configuration:
 
-	$ ./agent.py --default-config > config.ini
+    $ ./agent.py --default-config > config.ini
 
 The Agent authenticates using Ubuntu One. To use it you need to create an account at https://login.ubuntu.com first, and then use the Agent to put credentials in the Agent config file:
 
-	$ ./agent.py --interactive-login config.ini
-
-As a final step, register yourself in the system:  
-
-	$ ./agent.py --register config.ini
-
-IMPORTANT SECURITY NOTE:
-
-The config file now has data equivalent to your user and password.
-
-You are responsible for storing this securely. The device on which the
-Agent runs should be protected from unauthorized access.
-
-You can now run the Agent:
-
-	$ ./agent.py -v config.ini
-	2015-07-10 09:52:24,081 [agent-queue] Registered at https://spi.canonical.com/register
-	2015-07-10 09:52:24,839 [agent-queue] No tests at https://spi.canonical.com/queue/docs-org/amd64/agent-queue/agent-queue/get-one
-	2015-07-10 09:52:24,840 [agent-queue] Sleeping 10.000000 seconds
+    $ ./agent.py --interactive-login config.ini
 
 ### Setting up your organization
 
@@ -108,23 +85,32 @@
 To set up or add users to an Organization:
 
 1.  In the Agent configuration created when you logged in, there is a key of the following form: ```consumer_key = 7DzPrtB```
-2.  Contact your Canonical representative. Provide them with the name you would like to use for your Organization in the system and the consumer\_key. Your represenative will add this key into the Organization. Any agent configured with this consumer key will now have access to your Organization's data.
+2.  Contact your Canonical representative. Provide them with the name you would like to use for your Organization in the system and the consumer\_key. Your representative will add this key into the Organization. Any agent configured with this consumer key will now have access to your Organization's data.
+
+You need to replace the value of the ```organization_id``` field in the ```config.ini``` file with 'Your Organization Name', and ```platform``` to "spi-tutorial-raspi2" for the sake of this tutorial.
 
 Later, we will need to use the Organization name in the command line examples.
 You can set up an environment variable to save on typing:
 
-    export ORGANIZATION="your organization name"
-
-### How to set up the Raspberry Pi 2
-
-To do:
-
--   How to install base image, and check the image is working
--   wget, dd, test
--   troubleshoot?
--   how to connect it to the computer
--   how to setup the provisioning kit
--   what about the installation of golden images???
+    export ORGANIZATION="Your Organization Name"
+
+As a final step, register yourself in the system:
+
+    $ ./agent.py --register config.ini
+
+IMPORTANT SECURITY NOTE:
+
+The config file now has data equivalent to your user and password.
+
+You are responsible for storing this securely. The device on which the
+Agent runs should be protected from unauthorized access.
+
+You can now run the Agent:
+
+    $ ./agent.py -v config.ini
+    2015-07-10 09:52:24,081 [agent-queue] Registered at https://spi.canonical.com/register
+    2015-07-10 09:52:24,839 [agent-queue] No tests at https://spi.canonical.com/queue/docs-org/amd64/agent-queue/agent-queue/get-one
+    2015-07-10 09:52:24,840 [agent-queue] Sleeping 10.000000 seconds
 
 ## Product update testing walkthrough
 
@@ -139,31 +125,40 @@
 
 See https://developer.ubuntu.com/en/snappy/start/ for further details.
 
+Also, install Paramiko dependency:
+
+    $ sudo apt-get install python-paramiko
+
 Next, you will create an image for RPI2 from the rolling/edge channel, with our test-snap pre-installed:
 
-	$ wget http://people.canonical.com/~cprov/snappy/raspberrypi2/test-snap\_1\_all.snap
-	$ sudo ubuntu-device-flash core rolling --channel edge \
-	--oem pi2.canonical \
-	--device raspi2_armhf \
-	--developer-mode \
-	--install test-snap_1_all.snap \
-	-o spi-test_pi2.img
+    $ wget http://people.canonical.com/~cprov/snappy/raspberrypi2/test-snap\_1\_all.snap
+    $ sudo ubuntu-device-flash core rolling --channel edge \
+    --oem pi2.canonical \
+    --device raspi2_armhf \
+    --developer-mode \
+    --install test-snap_1_all.snap \
+    -o spi-test_pi2.img
 
 Or download the one we have already baked:
 
-	$ wget http://people.canonical.com/\~cprov/snappy/raspberrypi2/spi-test_pi2.img.xz
-	$ md5sum spi-test_pi2.img.xz
-	8f2cef8367b9913c92b332e5a0586281  spi-test_pi2.img.xz
+    $ wget http://people.canonical.com/\~cprov/snappy/raspberrypi2/spi-test_pi2.img.xz
+    $ md5sum spi-test_pi2.img.xz
+    8f2cef8367b9913c92b332e5a0586281  spi-test_pi2.img.xz
+    $ unxz spi-test_pi2.img.xz
 
 Now, because remotely flashing the Raspberry Pi is not supported in Snappy, you
 will need to manually flash an SD card with the image.
 
 On the host machine (careful select the correct output device):
 
-	$ xzcat spi-test_pi2.img.xz | pv -s 4g | sudo dd of=/dev/sdX bs=32M
+    $ cat spi-test_pi2.img | pv -s 4g | sudo dd of=/dev/sdX bs=32M
 
 For additional instructions see https://www.raspberrypi.org/documentation/installation/installing-images/
-Insert the SD card in your Raspberry Pi 2, power it on and wait few seconds until it boots. 
+Insert the SD card in your Raspberry Pi 2, power it on and wait few seconds until it boots.
+
+You can check whether it's online just by doing:
+
+    $ ping webdm.local
 
 If the device is not accessible, you can troubleshoot by using a serial
 cable to get a console on the RPi2, see http://elinux.org/RPi\_Serial\_Connection for instructions. Note the pins are the same for RPi1 and RPi2.
@@ -182,7 +177,7 @@
 -   ```base_image_reference```: the URL where to download the image
 -   ```snaps```: the list of snaps that the product uses
 
-So, execute the following from your computer (where you already authenticated during the lab setup above):
+So, in the agent directory execute the following from your computer (where you already authenticated during the lab setup above):
 
     ./scripts/api_example.py -X POST config.ini \
         https://spi.canonical.com/orgs/$ORGANIZATION/products/manifests
@@ -195,7 +190,9 @@
                       ["ubuntu-core.canonical", null, false]]
         }'
 
+<!---
 ToDo: the URL for ```base_image_reference``` should be fixed to its final destination
+-->
 
 Note particularly that one of the snaps is the one used for this Tutorial, in version 1; we’ll trigger the tests when a new version comes available for it.
 
@@ -208,47 +205,48 @@
 
 So, execute the following:
 
-	./scripts/api_example.py -X POST config.ini \
-	https://spi.canonical.com/orgs/$ORGANIZATION/tests/specs --data '{
-		"platform": "spi-tutorial-raspi2",
-		        "image_name": "tutorial-raspi2-image",
-		        "name": "Tutorial Example Test Specification",
-		        "test_payload": {
-		"tarball_url":
-		"http://taniquetil.com.ar/test_tarball.tar.gz",
-		"test_cmd": "./test"
-		}
-	}'
+    ./scripts/api_example.py -X POST config.ini \
+    https://spi.canonical.com/orgs/$ORGANIZATION/tests/specs --data '{
+        "platform": "spi-tutorial-raspi2",
+                "image_name": "tutorial-raspi2-image",
+                "name": "Tutorial Example Test Specification",
+                "test_payload": {
+        "tarball_url":
+        "http://taniquetil.com.ar/test_tarball.tar.gz",
+        "test_cmd": "./test"
+        }
+    }'
 
-ToDo: the URL for the tarball should be fixed to its final destination
+<!---
+ ToDo: the URL for the tarball should be fixed to its final destination
+-->
 
 At this point SPI is configured and supervising the Store for new
 versions of your snap.
 
 ### Trigger/running of actual tests
 
-To do:
-
--   describe steps to run the tests (making the Agent to run a test in the raspi is messy right now and needs manual steps)
--   explain which changes/uploads store/system image server trigger test creation, and if for this tutorial something needs to be done manually in the Store to trigger the test
--   how the user knows that a test was triggered? maybe we should merge this section with the following one (“how to check tests progress”)?
--   inform how to be sure that tests triggered by the SPI arrives ok to the Agent
-
 Now we’ll tell SPI manually that a new version of the snap we’re using for the tutorial is available:
 
-	./scripts/api_example.py -X POST config.ini \	
-	https://spi.canonical.com/orgs/$ORGANIZATION/snap-revisions --data '{
-	"name": "test-snap.spi-test",
-	"revision": 2
-	}'
-
-At this point the SPI will generate a message that is waiting to be consumed by our Agent.
+    ./scripts/api_example.py -X POST config.ini \    
+    https://spi.canonical.com/orgs/$ORGANIZATION/snap-revisions --data '{
+    "name": "test-snap.spi-test",
+    "revision": 2
+    }'
+
+In the response there is a image_unique_id that will be used next, please keep it around.
+
+At this point the SPI has generated a message that is waiting to be consumed by our Agent, and when that message arrives the Agent will try to run the commands to provision, setup and run the tests. For that we need to put useful commands in the config file. So, edit ```config.ini``` and replace the following three fields (the path needs to be absolute, be sure to replace the correct values):
+
+    provcommand = PATH_TO_AGENT/rpi2-sample-provkit/provision
+    setupcommand = PATH_TO_AGENT/rpi2-sample-provkit/setup
+    testcommand = PATH_TO_AGENT/rpi2-sample-provkit/runtest
 
 Next step, then, is to start the Agent to get that message and start running the test. As of this moment, we’d need to set up the Raspberry Pi manually, so the Agent after receiving the test to run will produce some instructions to get an image and burn it into the device, so please follow those instructions and let the Agent know when you’re ready (it will wait for you to press Enter).
 
 So, run:
 
-	./agent.py --once config.ini
+    ./agent.py --once config.ini
 
 After executing the test, the Agent will automatically retrieve the
 results and send them back to SPI.
@@ -259,20 +257,24 @@
 system, where they stands (to be run, or already run, etc), checking the
 events in the system:
 
-	./scripts/api_example.py config.ini \
-	https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?image_name=tutorial-raspi2-image
+    ./scripts/api_example.py config.ini \
+    https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?image_name=tutorial-raspi2-image
 
 Also, you can see the results produced for all the organization, doing
 
-	./scripts/api_example.py config.ini \
-	https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?image_name=tutorial-raspi2-image
+    ./scripts/api_example.py config.ini \
+    https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?image_name=tutorial-raspi2-image
 
 Or even check the results for an specific image (you can get the image
 id from the response of the query when you told the system above that a
 new snap revision was available):
 
-	./scripts/api_example.py config.ini \
-	https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?image_name=tutorial-raspi2-image/<unique_image_id>
+    ./scripts/api_example.py config.ini \
+    https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?image_name=tutorial-raspi2-image/<unique_image_id>
+
+<!--
+ToDo: add example to query the actual result
+-->
 
 ## Other Testing Scenarios