Merge lp:~ralsina/tanuki-agent/fix-product-ref into lp:tanuki-agent

Proposed by Roberto Alsina on 2016-01-04
Status: Merged
Approved by: Roberto Alsina on 2016-01-04
Approved revision: 203
Merged at revision: 201
Proposed branch: lp:~ralsina/tanuki-agent/fix-product-ref
Merge into: lp:tanuki-agent
Diff against target: 491 lines (+160/-159)
1 file modified
docs/api-reference-products.md (+160/-159)
To merge this branch: bzr merge lp:~ralsina/tanuki-agent/fix-product-ref
Reviewer Review Type Date Requested Status
Bret Barker 2016-01-04 Approve on 2016-01-04
Review via email: mp+281552@code.launchpad.net

Commit message

Updated docs for test triggering scenarios and progress/results APIs

Description of the change

Updated docs for test triggering scenarios and progress/results APIs

To post a comment you must log in.
Bret Barker (noise) wrote :

+1'ing with known FIXMEs remaining.

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'docs/api-reference-products.md'
2--- docs/api-reference-products.md 2016-01-04 20:06:45 +0000
3+++ docs/api-reference-products.md 2016-01-04 20:33:35 +0000
4@@ -4,8 +4,7 @@
5 [TOC]
6
7
8-Definitions
9-============
10+# Definitions
11
12 - **Manifest**: used to define a Product
13 that is based on Snaps. This is optional for image-based workflows.
14@@ -25,8 +24,7 @@
15 tests against a target device.
16 - **Test Result**: metadata about output of a test run.
17
18-Authentication
19-============
20+# Authentication
21
22 All API endpoints are authenticated, which ensures private access
23 to your product's information.
24@@ -114,8 +112,7 @@
25 login process) into a file called conf.ini. Note, this script is meant only as an example and not
26 intended for production use.
27
28-Errors
29-============
30+# Errors
31
32 The APIs use standard HTTP response codes. Most errors will
33 contain a human-readable "message" field in the JSON response body. Here
34@@ -141,8 +138,7 @@
35 <p>There was an temporary error on the server. The request may be retried after a short wait. If the problem persists please contact support. Scripts should use an exponential backoff to avoid hammering the servers with retries.
36 </table>
37
38-API Reference
39-=============
40+# API Reference
41
42 Product Management
43 ------------------
44@@ -257,7 +253,7 @@
45 "test-snap.foo"
46 ],
47 "release": "15.04-core",
48- "name": "test-product.e2e",
49+ "name": "test-product.foo",
50 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
51 "created_at": "2016-01-04T17:34:39.093142"
52 }
53@@ -705,12 +701,6 @@
54 has the following required fields:
55
56
57-- ```image_name```: a unique name within an
58- organization that is combined with each
59- test case to produce the full set of test
60- opportunities. I.e. if you have two test cases with a
61- matching image_name, then two test opportunities will be created.
62- Maximum length is 200 characters.
63 - ```image_reference```: is opaque to the
64 system; it is for your Provisioning Kit in your lab
65 to interpret and use. It can be any JSON
66@@ -727,51 +717,50 @@
67 image\_reference is not a URL to a binary. Currently
68 this ID is used for querying test results. Maximum length is 36
69 characters.
70-- ```upgrade\_snaps```: NOT IMPLEMENTED YET.
71+- ```channel```: **FIXME DESCRIBE**
72+- ```extra_snaps```: **FIXME DESCRIBE**
73
74
75 <table class="table">
76 <tr>
77- <th>Action <th>Image Reference Creation
78+ <th>Action <th>Image Advertising
79 <tr>
80- <td>URL <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/images
81+ <td>URL <td>https://spi.canonical.com/products/&lt;product-id&gt;/images
82 <tr>
83 <td>Method <td>POST
84 <tr>
85 <td>Data <td>
86 <pre>
87 {
88- image_reference: "http://foo.bar",
89- image_unique_id: some unique_id,
90- image_name: my_image,
91- upgrade_snaps: []
92-}
93-</pre>
94-<tr>
95- <td>Response <td><code>201 CREATED</code> with a list of test opportunity IDs
96-<tr>
97- <td>Response <td><code>404 NOT FOUND</code> if there is no test spec for this image_name
98-<pre>
99-{
100- "id": "resource-not-found",
101- "message": "Couldn't find a Spec for image name 'my_image'",
102- "url": null
103-}
104-</pre>
105+ "image_unique_id": "DEADBEEF_83451039",
106+ "extra_snaps": [],
107+ "channel": "edge",
108+ "image_reference": "http://foo.com/bar"
109+}
110+</pre>
111+<tr>
112+ <td>Response <td><code>201 CREATED</code> with a list of test opportunity IDs and image unique IDs.
113 <tr>
114 <td>Example <td>
115 <pre>
116-$ ./scripts/api_example.py -X POST conf.ini https://spi.canonical.com/orgs/docs-org/images --data \
117-'{
118-"image_reference": "http://foo.bar",
119-"image_unique_id": "fooo",
120-"image_name": "imgname",
121-"upgrade_snaps": []
122-}'
123+$ ./scripts/api_example.py -X POST conf.ini https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images --data \
124+'
125+{
126+ "image_unique_id": "DEADBEEF_83451039",
127+ "extra_snaps": [],
128+ "channel": "edge",
129+ "image_reference": "http://foo.com/bar"
130+}
131+'
132
133 HTTP 201
134 {
135- 'ids': ['99787105-911f-4e23-bded-b0b8253aee11']
136+ "ids": [
137+ {
138+ "image_unique_id": "DEADBEEF_83451039",
139+ "test_opportunity_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
140+ }
141+ ]
142 }
143 </pre>
144 </table>
145@@ -785,43 +774,24 @@
146 advertised to the system, however they can be re-advertised manually
147 afterwards, re-triggering tests with their original context.
148
149-The new revision advertised will be matched with all **Manifests** within the context **Organization**
150+The new revision advertised will be matched with all **Products**
151 referencing the given **Snap**, and **Test Opportunities** will be created for all **Test Specs** linked to those
152-**Manifests**.
153+**Products**.
154
155 ![](images/image03.png)
156
157
158-By modelling new / specific **Manifests** (Products) under the same
159-**Organization** customers define the testing context they care about:
160-
161-
162-
163-1. **Update from a Gold Master (GM) image**:
164-
165- Product "base\_image\_reference" contains specific versions of
166- product-specific snaps reflecting one generation / portion of the
167- installed base. In this case, tests represent the act of updating
168- products of an specific generation to the advertised snap.
169-
170-
171-2. **Fresh Install (special case of above where GM == Ubuntu-Core)**:
172-
173- Product "base\_image\_reference" does not include
174- product-specific snaps and tests represent, for instance, the act of
175- installing the advertised snap on top of a vanilla ubuntu-core
176- image.
177-
178-
179-From the [Agent & Provisioning Kit](#agent-operation) point of view, testing contexts will
180-be homogeneously defined via Test Opportunity base\_image\_reference and extra\_snaps.
181+By modelling new / specific **Products** customers define the testing context they care about:
182+
183+
184+**FIXME Describe the new world test triggering scenarios**
185
186 Snap revision advertisement request requires the following
187 fields:
188
189 - **name** The name of the snap package. Maximum length is 200 characters.
190 - **revision** The new snap's revision. An integer number.
191-
192+- **channel** On which channel is the new snap revision advertised.
193
194
195 Snap revision advertisement will return a list of test opportunity IDs and image unique IDs that can be used to [query for results](#querying-test-results) later.
196@@ -830,42 +800,101 @@
197 <tr>
198 <th>Action <th>Snap Revision Triggering
199 <tr>
200- <td>URL <td>https://spi.canonical.com/orgs/&lt;org-id&gt;/snap-revisions
201-<tr>
202- <td>Method <td>POST
203-<tr>
204- <td>Data <td>
205-<pre>
206-{
207- "name": name of snap package
208- "revision": revision number in the Store (integer)
209-}
210-</pre>
211-<tr>
212- <td>Response <td><code>201 CREATED</code> with a list of test opportunity IDs and image unique IDs
213-<tr>
214- <td>Response <td><code>404 NOT FOUND</code> if there is no matched Manifests
215-<pre>
216-{
217- "id": "resource-not-found",
218- "message": "",
219- "url": null
220-}
221-</pre>
222-<tr>
223- <td>Example <td>
224-<pre>
225-$ ./scripts/api_example.py -X POST conf.ini https://spi.canonical.com/orgs/docs-org/snap-revisions \
226---data '
227-> {
228-> "name": "hello.world",
229-> "revision": 123
230-> }'
231-
232-HTTP 201
233-{
234-'ids': [{'test_opportunity_id': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
235- 'image_unique_id': 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'}]}
236+ <td>URL <td>https://spi.canonical.com/products/&lt;product-id&gt;/snaps
237+<tr>
238+ <td>Method <td>POST
239+<tr>
240+ <td>Data <td>
241+<pre>
242+{
243+ "name": "test-snap.foo",
244+ "revision": 2,
245+ "channel": "edge"
246+}
247+</pre>
248+<tr>
249+ <td>Response <td><code>201 CREATED</code> with a list of test opportunity IDs and image unique IDs
250+<tr>
251+ <td>Example <td>
252+<pre>
253+$ ./scripts/api_example.py -X POST conf.ini https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/snaps \
254+--data '
255+{
256+ "name": "test-snap.foo",
257+ "revision": 2,
258+ "channel": "edge"
259+}'
260+
261+HTTP 201
262+{
263+ "ids": [
264+ {
265+ "image_unique_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
266+ "test_opportunity_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
267+ }
268+ ]
269+}
270+</pre>
271+</table>
272+
273+### Gold Master
274+
275+Gold Master advertisement requires the following fields:
276+
277+- **snaps** A list of snaps that form the gold master image.
278+- **channel** On what channel is the gold master advertised.
279+
280+Gold master advertisement will return a list of test opportunity IDs and image unique IDs that can be used to [query for results](#querying-test-results) later.
281+
282+<table class="table">
283+<tr>
284+ <th>Action <th>Gold Master Triggering
285+<tr>
286+ <td>URL <td>https://spi.canonical.com/products/&lt;product-id&gt;/gold-masters
287+<tr>
288+ <td>Method <td>POST
289+<tr>
290+ <td>Data <td>
291+<pre>
292+{
293+ "snaps": A list of snaps/revisions,
294+ "channel": a channel name
295+}
296+</pre>
297+<tr>
298+ <td>Response <td><code>201 CREATED</code> with a list of test opportunity IDs and image unique IDs
299+<tr>
300+ <td>Example <td>
301+<pre>
302+$ ./scripts/api_example.py -X POST conf.ini https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/snaps \
303+--data '
304+{
305+ "snaps": [
306+ {
307+ "name": "pi2.canonical",
308+ "revision": 1
309+ },
310+ {
311+ "name": "webdm.canonical",
312+ "revision": 1
313+ },
314+ {
315+ "name": "test-snap.foo",
316+ "revision": 1
317+ }
318+ ],
319+ "channel": "stable"
320+}'
321+
322+HTTP 201
323+{
324+ "ids": [
325+ {
326+ "image_unique_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
327+ "test_opportunity_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
328+ }
329+ ]
330+}
331 </pre>
332 </table>
333
334@@ -873,8 +902,6 @@
335 Querying Test Progress
336 ----------------------
337
338-
339-
340 As a test opportunity progresses from being triggered to deliver a
341 result it flows through a series of expected events. This is the normal
342 expected event flow for a test opportunity:
343@@ -898,7 +925,7 @@
344 <tr>
345 <th>Action <th>Result Query
346 <tr>
347- <td>URL <td>https://spi.canonical.com/orgs/&lt;org_id&gt;/tests/events
348+ <td>URL <td>https://spi.canonical.com/products/&lt;prod_id&gt;/tests/events
349 <tr>
350 <td>Method <td>GET
351 <tr>
352@@ -926,54 +953,43 @@
353 <td>Example <td>
354 <pre>
355 $ ./scripts/api_example.py conf.ini \
356-http://spi.canonical.com/orgs/e2e-org/tests/events?test_opportunity_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
357+http://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/tests/events?test_opportunity_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
358 HTTP 200
359 {
360 "event_logs": [
361 {
362- "organization_id": "e2e-org",
363- "image_name": "e2e-imgf151a8cd9081404db54ed1d8dab1e140",
364- "queued_at": "2015-09-17T12:13:03.288000+00:00",
365- "updated_at": "2015-09-17T12:13:06.799000+00:00",
366- "image_unique_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
367- "events_seen": [
368- "QUEUED_FOR_AGENTS",
369- "PICKED_BY_AGENT",
370- "RESULT_POSTED",
371- "RESULT_STORED"
372- ],
373 "events": [
374 {
375 "event_type": "QUEUED_FOR_AGENTS",
376- "timestamp": "2015-09-17T12:13:03.288000+00:00"
377+ "timestamp": "2016-01-04T16:58:28.805000+00:00"
378 },
379 {
380+ "timestamp": "2016-01-04T16:58:33.185000+00:00",
381 "event_type": "PICKED_BY_AGENT",
382- "agent_group": "e2e-group",
383- "agent_id": "e2e-id",
384- "timestamp": "2015-09-17T12:13:06.291000+00:00",
385- "platform": "amd64"
386+ "agent_id": "foo-agent-id",
387+ "platform": null,
388+ "agent_group": null
389 },
390 {
391 "result_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
392 "test_status": "PASSED",
393- "agent_group": "e2e-group",
394 "event_type": "RESULT_POSTED",
395- "timestamp": "2015-09-17T12:13:06.734000+00:00",
396- "agent_id": "e2e-id",
397- "platform": "amd64"
398+ "agent_id": "foo-agent-id",
399+ "platform": null,
400+ "agent_group": null,
401+ "timestamp": "2016-01-04T16:58:33.734000+00:00"
402 },
403 {
404+ "result_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
405+ "test_status": "PASSED",
406 "event_type": "RESULT_STORED",
407- "result_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
408- "test_status": "PASSED",
409- "timestamp": "2015-09-17T12:13:06.745000+00:00"
410+ "timestamp": "2016-01-04T16:58:33.764000+00:00"
411 }
412 ],
413+ "updated_at": "2016-01-04T16:58:33.825000+00:00",
414+ "product_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
415+ "queued_at": "2016-01-04T16:58:28.805000+00:00",
416 "test_opportunity_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
417- "spec_name": "e2e-spec_13691451",
418- "test_opportunity": {
419-
420 (...)
421 </pre>
422 </table>
423@@ -1028,7 +1044,7 @@
424 <tr>
425 <th>Action <th>Result Query
426 <tr>
427- <td>URL <td>https://spi.canonical.com/orgs/&lt;org_id&gt;/results
428+ <td>URL <td>https://spi.canonical.com/products/&lt;productd_id&gt;/tests/results
429 <tr>
430 <td>Method <td>GET
431 <tr>
432@@ -1049,30 +1065,19 @@
433 <td>Example <td>
434 <pre>
435 ./scripts/api_example.py conf.ini \
436-'https://spi.canonical.com/orgs/docs-org/results?start_date=20150826T00%3A00%3A00&end_date=20150826T04%3A00%3A00'
437+'https://spi.canonical.com/products/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/results?start_date=20150826T00%3A00%3A00&end_date=20150826T04%3A00%3A00'
438
439 HTTP 200
440 {
441 "test_results": [
442 {
443- "test_spec": {
444- "name": "e2e-spec_70600150",
445- "platform": "amd64",
446- "image_name": "e2e-img",
447- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
448- "created_at": "2015-08-26T00:00:20.297477",
449- "test_payload": "{'foo': 'bar'}"
450- },
451 "test_status": "PASSED",
452- "platform": "amd64",
453- "organization_id": "docs-org",
454- "image_name": "e2e-img",
455- "extra_snaps": [],
456- "image_reference": "http://foo.com/bar",
457- "agent": {
458- "timing": {
459- "setup_start": "2015-08-26T00:00:22.651078",
460-
461+ "agent_revno": "197",
462+ "image_reference": null,
463+ "test_opportunity_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
464+ "primary_snap_name": "test-snap.foo",
465+ "base_channel": "stable",
466+ "update_channel": null,
467 [...]
468 </pre>
469 </table>
470@@ -1093,12 +1098,8 @@
471 - 20150914 17:51:31
472 - 20150914 175131 Z
473
474-
475-
476 ### Test Result Data
477
478-
479-
480 There are a few key fields in the test result JSON of note:
481
482 <!-- FIX link to actors-and-results -->
483@@ -1141,7 +1142,7 @@
484 {
485 "image_unique_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
486 "test_status": "PASSED",
487- "agent-id": "e2e-id",
488+ "agent-id": "foo-agent-id",
489 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
490 "result_payload": {
491 "foo": "bar"

Subscribers

People subscribed via source and target branches

to all changes: