1COMPOSER-CLI(1) Lorax COMPOSER-CLI(1)
2
3
4
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
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
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
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
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
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
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
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
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
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
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
349 Weldr Team
350
352 2018, Red Hat, Inc.
353
354
355
356
35733.2 Apr 28, 2020 COMPOSER-CLI(1)