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] [--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
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
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
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
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
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
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
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
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
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
347 Weldr Team
348
350 2018, Red Hat, Inc.
351
352
353
354
35532.6 Feb 12, 2020 COMPOSER-CLI(1)