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

EDIT A BLUEPRINT

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

BUILD AN IMAGE

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

MONITOR THE BUILD STATUS

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

DOWNLOAD THE IMAGE

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

IMAGE UPLOADS

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

PROVIDERS

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

PROFILES

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

BUILD AN IMAGE AND UPLOAD RESULTS

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

UPLOAD AN EXISTING IMAGE

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

AUTHOR

347       Weldr Team
348
350       2018, Red Hat, Inc.
351
352
353
354
35532.6                             Feb 12, 2020                  COMPOSER-CLI(1)
Impressum