1COMPOSER-CLI(1)                      Lorax                     COMPOSER-CLI(1)
2
3
4

NAME

6       composer-cli - Composer Cmdline Utility Documentation
7
8       Authors
9              Brian C. Lane <bcl@redhat.com>
10
11       composer-cli  is  used  to interact with the lorax-composer API server,
12       managing blueprints, exploring available  packages,  and  building  new
13       images.
14
15       It requires lorax-composer to be installed on the local system, and the
16       user running it needs to be a member of the weldr group.  They  do  not
17       need to be root, but all of the security precautions apply.
18

COMPOSER-CLI CMDLINE ARGUMENTS

20       Lorax Composer commandline tool
21
22
23          usage: composer-cli [-h] [-j] [-s SOCKET] [--log LOG] [-a APIVER]
24                              [--test TESTMODE] [-V]
25                              ...
26
27   Positional Arguments
28          Named Arguments
29
30       j, --json
31              Output the raw JSON response instead of the normal output.
32
33              Default: False
34
35       s, --socket
36              Path to the socket file to listen on
37
38              Default: "/run/weldr/api.socket"
39
40       -log   Path to logfile (./composer-cli.log)
41
42       a, --api
43              API Version to use
44
45              Default: "1"
46
47       -test  Pass test mode to compose. 1=Mock compose with fail. 2=Mock com‐
48              pose with finished.
49
50              Default: 0
51
52       V      show program's version number and exit
53
54              Default: False
55
56
57       compose start <BLUEPRINT> <TYPE> [<IMAGE-NAME> <PROVIDER>  <PROFILE>  |
58       <IMAGE-NAME> <PROFILE.TOML>]
59              Start  a  compose  using the selected blueprint and output type.
60              Optionally start an upload.
61
62       compose types
63              List the supported output types.
64
65       compose status
66              List the status of all running and finished composes.
67
68       compose list [waiting|running|finished|failed]
69              List basic information about composes.
70
71       compose log <UUID> [<SIZE>]
72              Show the last SIZE kB of the compose log.
73
74       compose cancel <UUID>
75              Cancel a running compose and delete any intermediate results.
76
77       compose delete <UUID,...>
78              Delete the listed compose results.
79
80       compose info <UUID>
81              Show detailed information on the compose.
82
83       compose metadata <UUID>
84              Download the metadata use to create the compose to  <uuid>-meta‐
85              data.tar
86
87       compose logs <UUID>
88              Download the compose logs to <uuid>-logs.tar
89
90       compose results <UUID>
91              Download  all  of the compose results; metadata, logs, and image
92              to <uuid>.tar
93
94       compose image <UUID>
95              Download the output image from the compose. Filename depends  on
96              the type.
97
98       blueprints list
99              List the names of the available blueprints.
100
101       blueprints show <BLUEPRINT,...>
102              Display the blueprint in TOML format.
103
104       blueprints changes <BLUEPRINT,...>
105              Display the changes for each blueprint.
106
107       blueprints diff <BLUEPRINT> <FROM-COMMIT> <TO-COMMIT>
108              Display  the  differences  between  2  versions  of a blueprint.
109              FROM-COMMIT can be a commit hash or NEWEST TO-COMMIT  can  be  a
110              commit hash, NEWEST, or WORKSPACE
111
112       blueprints save <BLUEPRINT,...>
113              Save the blueprint to a file, <BLUEPRINT>.toml
114
115       blueprints delete <BLUEPRINT>
116              Delete a blueprint from the server
117
118       blueprints depsolve <BLUEPRINT,...>
119              Display the packages needed to install the blueprint.
120
121       blueprints push <BLUEPRINT>
122              Push a blueprint TOML file to the server.
123
124       blueprints freeze <BLUEPRINT,...>
125              Display the frozen blueprint's modules and packages.
126
127       blueprints freeze show <BLUEPRINT,...>
128              Display the frozen blueprint in TOML format.
129
130       blueprints freeze save <BLUEPRINT,...>
131              Save    the    frozen    blueprint    to    a    file,    <blue‐
132              print-name>.frozen.toml.
133
134       blueprints tag <BLUEPRINT>
135              Tag the most recent blueprint commit as a release.
136
137       blueprints undo <BLUEPRINT> <COMMIT>
138              Undo changes to a blueprint by reverting to the selected commit.
139
140       blueprints workspace <BLUEPRINT>
141              Push the blueprint TOML to the temporary workspace storage.
142
143       modules list
144              List the available modules.
145
146       projects list
147              List the available projects.
148
149       projects info <PROJECT,...>
150              Show details about the listed projects.
151
152       sources list
153              List the available sources
154
155       sources info <SOURCE-NAME,...>
156              Details about the source.
157
158       sources add <SOURCE.TOML>
159              Add a package source to the server.
160
161       sources change <SOURCE.TOML>
162              Change an existing source
163
164       sources delete <SOURCE-NAME>
165              Delete a package source.
166
167       status show                         Show API server status.
168
169       upload info <UPLOAD-UUID>
170              Details about an upload
171
172       upload  start  <BUILD-UUID>  <IMAGE-NAME>  [<PROVIDER>  <PROFILE>|<PRO‐
173       FILE.TOML>]
174              Upload a build image to the selected provider.
175
176       upload log <UPLOAD-UUID>
177              Show the upload log
178
179       upload cancel <UPLOAD-UUID>
180              Cancel an upload with that is queued or in progress
181
182       upload delete <UPLOAD-UUID>
183              Delete the upload and remove it from the build
184
185       upload reset <UPLOAD-UUID>
186              Reset the upload so that it can be tried again
187
188       providers list <PROVIDER>
189              List the available providers, or list the <provider's> available
190              profiles
191
192       providers show <PROVIDER> <PROFILE>
193              show the details of a specific provider's profile
194
195       providers push <PROFILE.TOML>
196              Add a new profile, or overwrite an existing one
197
198       providers save <PROVIDER> <PROFILE>
199              Save the profile's details to a TOML file named <PROFILE>.toml
200
201       providers delete <PROVIDER> <PROFILE>
202              Delete a profile from a provider
203
204

EDIT A BLUEPRINT

206       Start out by listing the available blueprints using composer-cli  blue‐
207       prints  list,  pick  one  and save it to the local directory by running
208       composer-cli blueprints save http-server. If there  are  no  blueprints
209       available you can copy one of the examples from the test suite.
210
211       Edit  the file (it will be saved with a .toml extension) and change the
212       description, add a package or module to it. Send it back to the  server
213       by  running composer-cli blueprints push http-server.toml. You can ver‐
214       ify that it was saved by viewing the  changelog  -  composer-cli  blue‐
215       prints changes http-server.
216

BUILD AN IMAGE

218       Build  a  qcow2  disk image from this blueprint by running composer-cli
219       compose start http-server qcow2. It will print a UUID that you can  use
220       to keep track of the build. You can also cancel the build if needed.
221
222       The  available  types  of  images  is displayed by composer-cli compose
223       types.  Currently this  consists  of:  alibaba,  ami,  ext4-filesystem,
224       google,  hyper-v,  live-iso,  openstack,  partitioned-disk, qcow2, tar,
225       vhd, vmdk
226
227       You can optionally start an upload of the  finished  image,  see  Image
228       Uploads for more information.
229

MONITOR THE BUILD STATUS

231       Monitor  it using composer-cli compose status, which will show the sta‐
232       tus of all the builds on the system. You can view the end of  the  ana‐
233       conda  build  logs  once  it is in the RUNNING state using composer-cli
234       compose log UUID where UUID is the UUID returned by the start command.
235
236       Once the build is in the FINISHED state you can download the image.
237

DOWNLOAD THE IMAGE

239       Downloading the final image is done  with  composer-cli  compose  image
240       UUID  and it will save the qcow2 image as UUID-disk.qcow2 which you can
241       then use to boot a VM like this:
242
243          qemu-kvm --name test-image -m 1024 -hda ./UUID-disk.qcow2
244

IMAGE UPLOADS

246       composer-cli can upload the images to a number of  services,  including
247       AWS,  OpenStack,  and vSphere. The upload can be started when the build
248       is finished, by using composer-cli compose start  ...  or  an  existing
249       image  can  be uploaded with composer-cli upload start .... In order to
250       access the service you need to  pass  authentication  details  to  com‐
251       poser-cli using a TOML file, or reference a previously saved profile.
252

PROVIDERS

254       Providers  are  the  services  providers  with Ansible playbook support
255       under /usr/share/lorax/lifted/providers/, you will need to gather  some
256       provider specific information in order to authenticate with it. You can
257       view  the  required  fields  using  composer-cli   providers   template
258       <PROVIDER>, eg. for AWS you would run:
259
260          composer-cli upload template aws
261
262       The output looks like this:
263
264          provider = "aws"
265
266          [settings]
267          aws_access_key = "AWS Access Key"
268          aws_bucket = "AWS Bucket"
269          aws_region = "AWS Region"
270          aws_secret_key = "AWS Secret Key"
271
272       Save  this  into  an  aws-credentials.toml file and use it when running
273       start.
274
275   AWS
276       The access  key  and  secret  key  can  be  created  by  going  to  the
277       IAM->Users->Security Credentials section and creating a new access key.
278       The secret key will only be shown when it is first created so make sure
279       to  record  it  in a secure place. The region should be the region that
280       you want to use the AMI in, and the bucket can be an  existing  bucket,
281       or  a new one, following the normal AWS bucket naming rules. It will be
282       created if it doesn't already exist.
283
284       When uploading the image it is first uploaded to  the  s3  bucket,  and
285       then  converted  to  an  AMI.   If  the conversion is successful the s3
286       object will be deleted. If it fails,  re-trying  after  correcting  the
287       problem  will re-use the object if you have not deleted it in the mean‐
288       time, speeding up the process.
289

PROFILES

291       Profiles store the authentication settings associated with  a  specific
292       provider.  Providers can have multiple profiles, as long as their names
293       are unique. For example, you may  have  one  profile  for  testing  and
294       another for production uploads.
295
296       Profiles  are  created by pushing the provider settings template to the
297       server using composer-cli  providers  push  <PROFILE.TOML>  where  PRO‐
298       FILE.TOML  is  the same as the provider template, but with the addition
299       of a profile field. For example,  an  AWS  profile  named  test-uploads
300       would look like this:
301
302          provider = "aws"
303          profile = "test-uploads"
304
305          [settings]
306          aws_access_key = "AWS Access Key"
307          aws_bucket = "AWS Bucket"
308          aws_region = "AWS Region"
309          aws_secret_key = "AWS Secret Key"
310
311       You   can   view  the  profile  by  using  composer-cli  providers  aws
312       test-uploads.
313

BUILD AN IMAGE AND UPLOAD RESULTS

315       If you have a profile named test-uploads:
316
317          composer-cli compose start example-http-server ami "http image" aws test-uploads
318
319       Or if you have the settings stored in a TOML file:
320
321          composer-cli compose start example-http-server ami "http image" aws-settings.toml
322
323       It will return the UUID of the image build, and the UUID of the upload.
324       Once  the  build  has  finished  successfully  it will start the upload
325       process,  which  you  can  monitor  with   composer-cli   upload   info
326       <UPLOAD-UUID>
327
328       You can also view the upload logs from the Ansible playbook with:
329
330          ``composer-cli upload log <UPLOAD-UUID>``
331
332       The type of the image must match the type supported by the provider.
333

UPLOAD AN EXISTING IMAGE

335       You can upload previously built images, as long as they are in the FIN‐
336       ISHED state, using composer-cli upload start ...`. If you have  a  pro‐
337       file named test-uploads:
338
339          composer-cli upload start <UUID> "http-image" aws test-uploads
340
341       Or if you have the settings stored in a TOML file:
342
343          composer-cli upload start <UUID> "http-image" aws-settings.toml
344
345       This will output the UUID of the upload, which can then be used to mon‐
346       itor the status in the same way described above.
347

AUTHOR

349       Weldr Team
350
352       2018, Red Hat, Inc.
353
354
355
356
35733.2                             Apr 28, 2020                  COMPOSER-CLI(1)
Impressum