← Back to branch summary

~jocave/checkbox/hybrid-amd-gpu-mods

« back to all changes in this revision

Viewing changes to plainbox/docs/manpages/plainbox-template-units.rst

  • Committer: Zygmunt Krynicki
  • Date: 2013-05-17 13:54:25 UTC
  • mto: This revision was merged to the branch mainline in revision 2130.
  • Revision ID: zygmunt.krynicki@canonical.com-20130517135425-cxcenxx5t0qrtbxd
checkbox-ng: add CheckBoxNG sub-project

CheckBoxNG (or lowercase as checkbox-ng, pypi:checkbox-ng) is a clean
implementation of CheckBox on top of PlainBox. It provides a new
executable, 'checkbox' that has some of the same commands that were
previously implemented in the plainbox package.

In particular CheckBoxNG comes with the 'checkbox sru' command
(the same one as in plainbox). Later on this sub-command will be removed
from plainbox.

CheckBoxNG depends on plainbox >= 0.3

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>

Show diffs side-by-side

added added

removed removed

Lines of Context:
plainbox/docs/manpages/plainbox-template-units.rst
1
 
===========================
2
 
plainbox-template-units (7)
3
 
===========================
4
 
 
5
 
Synopsis
6
 
========
7
 
 
8
 
This page documents the Plainbox template units syntax and runtime behavior
9
 
 
10
 
Description
11
 
===========
12
 
 
13
 
The template unit is a variant of Plainbox unit types. A template is a skeleton
14
 
for defining additional units, typically job definitions. A template is defined
15
 
as a typical RFC822-like Plainbox unit (like a typical job definition) with the
16
 
exception that all the fields starting with the string ``template-`` are
17
 
reserved for the template itself while all the other fields are a definition of
18
 
all the eventual instances of the template.
19
 
 
20
 
Template-Specific Fields
21
 
------------------------
22
 
 
23
 
There are four fields that are specific to the template unit:
24
 
 
25
 
``template-unit``:
26
 
    Name of the unit type this template will generate. By default job
27
 
    definition units are generated (as if the field was specified with the
28
 
    value of ``job``) eventually but other values may be used as well.
29
 
 
30
 
    This field is optional.
31
 
 
32
 
``template-resource``:
33
 
    Name of the resource job (if it is a compatible resource identifier) to use
34
 
    to parametrize the template. This must either be a name of a resource job
35
 
    available in the namespace the template unit belongs to *or* a valid
36
 
    resource identifier matching the definition in the ``template-imports``
37
 
    field.
38
 
 
39
 
    This field is mandatory.
40
 
 
41
 
``template-imports``:
42
 
    A resource import statement. It can be used to refer to arbitrary resource
43
 
    job by its full identifier and (optionally) give it a short variable name.
44
 
 
45
 
    The syntax of each imports line is::
46
 
 
47
 
        IMPORT_STMT ::  "from" <NAMESPACE> "import" <PARTIAL_ID>
48
 
                      | "from" <NAMESPACE> "import" <PARTIAL_ID>
49
 
                         AS <IDENTIFIER>
50
 
 
51
 
    The short syntax exposes ``PARTIAL_ID`` as the variable name available
52
 
    within all the fields defined within the template unit.  If it is not a
53
 
    valid variable name then the second form must be used.
54
 
 
55
 
    This field is sometimes optional. It becomes mandatory when the resource
56
 
    job definition is from another provider namespace or when it is not a valid
57
 
    resource identifier and needs to be aliased.
58
 
 
59
 
``template-filter``:
60
 
    A resource program that limits the set of records from which template
61
 
    instances will be made. The syntax of this field is the same as the syntax
62
 
    of typical job definition unit's ``requires`` field, that is, it is a
63
 
    python expression.
64
 
 
65
 
    When defined, the expression is evaluated once for each resource object and
66
 
    if it evaluates successfully to a True value then that particular resource
67
 
    object is used to instantiate a new unit.
68
 
 
69
 
    This field is optional.
70
 
 
71
 
Instantiation
72
 
-------------
73
 
 
74
 
When a template is instantiated, a single record object is used to fill in the
75
 
parametric values to all the applicable fields. Each field is formatted using
76
 
the python formatting language. Within each field the record is exposed as the
77
 
variable named by the ``template_resource`` field. Record data is exposed as
78
 
attributes of that object.
79
 
 
80
 
The special parameter ``__index__`` can be used to iterate over the devices
81
 
matching the ``template-filter`` field.
82
 
 
83
 
Migrating From Local Jobs
84
 
-------------------------
85
 
 
86
 
Migration from local jobs is mostly straightforward. Apart from one gotcha the
87
 
process is as follows:
88
 
 
89
 
1. Look at the data that was used to *instantiate* job definitions by the old
90
 
   local job. Write them down.
91
 
2. Ensure that all of the instantiated template data is exposed by exactly one
92
 
   resource. This may be the commonly-used checkbox ``device`` resource job or
93
 
   any custom resource job but it has to be all contained in one resource. Data
94
 
   that used to be computed partially by the resource and partially by the
95
 
   local job needs to be computed as additional attributes (fields) of the
96
 
   resource instead.
97
 
3. Replace the boilerplate of the local job (typically a ``cat``, here-document
98
 
   piped to ``run-templates`` and ``filter-templates``) with the equivalent
99
 
   ``template-resource`` and ``template-filter`` fields.
100
 
4. Remove the indentation so that all of the job definition is aligned to the
101
 
   left of the paragraph.
102
 
5. Re-validate the provider to ensure that everything looks okay.
103
 
6. Re-test the job by running it.
104
 
 
105
 
The only gotcha is related to step two. It is very common for local jobs to do
106
 
some additional computation. For example many storage tests compute the path
107
 
name of some ``sysfs`` file. This has to be converted to a readily-available
108
 
path that is provided by the resource job.
109
 
 
110
 
Another thing to remember is that Plainbox templates use Python syntax for
111
 
their fields. That means that some characters have to be escaped. For instance,
112
 
``${PLAINBOX_SESSION_SHARE}/test-file`` has to be escaped to
113
 
``${{PLAINBOX_SESSION_SHARE}}/test-file``.
114
 
 
115
 
Examples
116
 
========
117
 
 
118
 
Basic example
119
 
-------------
120
 
 
121
 
The following example contains a simplified template that instantiates to a
122
 
simple storage test. The test is only instantiated for devices that are
123
 
considered *physical*. In this example we don't want to spam the user with a
124
 
long list of loopback devices. This is implemented by exposing that data in the
125
 
resource job itself::
126
 
 
127
 
    id: device
128
 
    plugin: resource
129
 
    command:
130
 
        echo 'path: /dev/sda'
131
 
        echo 'has_media: yes'
132
 
        echo 'physical: yes'
133
 
        echo
134
 
        echo 'path: /dev/cdrom'
135
 
        echo 'has_media: no'
136
 
        echo 'physical: yes'
137
 
        echo
138
 
        echo 'path: /dev/loop0'
139
 
        echo 'has_media: yes'
140
 
        echo 'physical: no'
141
 
 
142
 
The template defines a test-storage-``XXX`` test where ``XXX`` is replaced by
143
 
the path of the device. Only devices which are *physical* according to some
144
 
definition are considered for testing. This means that the record related to
145
 
``/dev/loop0`` will be ignored and will not instantiate a test job for that
146
 
device. This feature can be coupled with the existing resource requirement to
147
 
let the user know that we did see their CD-ROM device but it was not tested as
148
 
there was no inserted media at the time::
149
 
 
150
 
   unit: template
151
 
   template-resource: device
152
 
   template-filter: device.physical == 'yes'
153
 
   requires: device.has_media == 'yes'
154
 
   id: test-storage-{path}
155
 
   plugin: shell
156
 
   command: perform-testing-on --device {path}
157
 
 
158
 
Real life example
159
 
-----------------
160
 
 
161
 
Here is a real life example from a provider. We have the following local job
162
 
that generates a job for each hard drive available on the system::
163
 
 
164
 
   plugin: local
165
 
   _summary: Check stats changes for each disk
166
 
   id: disk/stats
167
 
   requires: device.category == 'DISK'
168
 
   _description: 
169
 
    This test generates some disk activity and checks the stats to ensure drive
170
 
    activity is being recorded properly.
171
 
   command:
172
 
    cat <<'EOF' | run_templates -t -s 'udev_resource | filter_templates -w "category=DISK"'
173
 
    plugin: shell
174
 
    category_id: 2013.com.canonical.plainbox::disk
175
 
    id: disk/stats_`ls /sys$path/block`
176
 
    flags: deprecated
177
 
    requires:
178
 
     device.path == "$path"
179
 
     block_device.`ls /sys$path/block`_state != 'removable'
180
 
    user: root
181
 
    command: disk_stats_test `ls /sys$path/block | sed 's|!|/|'`
182
 
    description: This test checks disk stats, generates some activity and rechecks stats to verify they've changed. It also verifies that disks appear in the various files they're supposed to.
183
 
    EOF
184
 
 
185
 
After migration to a template unit job, it looks like this::
186
 
 
187
 
   unit: template
188
 
   template-resource: device
189
 
   template-filter: device.category == 'DISK'
190
 
   plugin: shell
191
 
   category_id: 2013.com.canonical.plainbox::disk
192
 
   id: disk/stats_{name}
193
 
   requires:
194
 
    device.path == "{path}"
195
 
    block_device.{name}_state != 'removable'
196
 
   user: root
197
 
   command: disk_stats_test {name}
198
 
   _description: This test checks {name} disk stats, generates some activity and rechecks stats to verify they've changed. It also verifies that disks appear in the various files they're supposed to.
199
 
 
200
 
The ``template-resource`` used here (``device``) refers to a resource job using the ``udev_resource`` script to get information about the system. The ``udev_resource`` script returns a list of items with attributes such as ``path`` and ``name``, so we can use these directly in our template.
201
 
 
202
 
We end up with a shorter (from 19 lines to 11!) and more readable template.