Brian C. Lane <firstname.lastname@example.org>
composer-cli is used to interact with the
lorax-composer API server, managing blueprints, exploring available packages, and building new images.
It requires lorax-composer to be installed on the
local system, and the user running it needs to be a member of the
group. They do not need to be root, but all of the security precautions apply.
composer-cli cmdline arguments¶
Lorax Composer commandline tool
usage: composer-cli [-h] [-j] [-s SOCKET] [--log LOG] [-a APIVER] [--test TESTMODE] [-V] ...
- -j, --json
Output the raw JSON response instead of the normal output.
- -s, --socket
Path to the socket file to listen on
Path to logfile (./composer-cli.log)
- -a, --api
API Version to use
Pass test mode to compose. 1=Mock compose with fail. 2=Mock compose with finished.
show program's version number and exit
- compose start <BLUEPRINT> <TYPE> [<IMAGE-NAME> <PROVIDER> <PROFILE> | <IMAGE-NAME> <PROFILE.TOML>]
Start a compose using the selected blueprint and output type. Optionally start an upload.
- compose types
List the supported output types.
- compose status
List the status of all running and finished composes.
- compose list [waiting|running|finished|failed]
List basic information about composes.
- compose log <UUID> [<SIZE>]
Show the last SIZE kB of the compose log.
- compose cancel <UUID>
Cancel a running compose and delete any intermediate results.
- compose delete <UUID,...>
Delete the listed compose results.
- compose info <UUID>
Show detailed information on the compose.
- compose metadata <UUID>
Download the metadata use to create the compose to <uuid>-metadata.tar
- compose logs <UUID>
Download the compose logs to <uuid>-logs.tar
- compose results <UUID>
Download all of the compose results; metadata, logs, and image to <uuid>.tar
- compose image <UUID>
Download the output image from the compose. Filename depends on the type.
- blueprints list
List the names of the available blueprints.
- blueprints show <BLUEPRINT,...>
Display the blueprint in TOML format.
- blueprints changes <BLUEPRINT,...>
Display the changes for each blueprint.
- blueprints diff <BLUEPRINT> <FROM-COMMIT> <TO-COMMIT>
Display the differences between 2 versions of a blueprint. FROM-COMMIT can be a commit hash or NEWEST TO-COMMIT can be a commit hash, NEWEST, or WORKSPACE
- blueprints save <BLUEPRINT,...>
Save the blueprint to a file, <BLUEPRINT>.toml
- blueprints delete <BLUEPRINT>
Delete a blueprint from the server
- blueprints depsolve <BLUEPRINT,...>
Display the packages needed to install the blueprint.
- blueprints push <BLUEPRINT>
Push a blueprint TOML file to the server.
- blueprints freeze <BLUEPRINT,...>
Display the frozen blueprint's modules and packages.
- blueprints freeze show <BLUEPRINT,...>
Display the frozen blueprint in TOML format.
- blueprints freeze save <BLUEPRINT,...>
Save the frozen blueprint to a file, <blueprint-name>.frozen.toml.
- blueprints tag <BLUEPRINT>
Tag the most recent blueprint commit as a release.
- blueprints undo <BLUEPRINT> <COMMIT>
Undo changes to a blueprint by reverting to the selected commit.
- blueprints workspace <BLUEPRINT>
Push the blueprint TOML to the temporary workspace storage.
- modules list
List the available modules.
- projects list
List the available projects.
- projects info <PROJECT,...>
Show details about the listed projects.
- sources list
List the available sources
- sources info <SOURCE-NAME,...>
Details about the source.
- sources add <SOURCE.TOML>
Add a package source to the server.
- sources change <SOURCE.TOML>
Change an existing source
- sources delete <SOURCE-NAME>
Delete a package source.
status show Show API server status.
- upload info <UPLOAD-UUID>
Details about an upload
- upload start <BUILD-UUID> <IMAGE-NAME> [<PROVIDER> <PROFILE>|<PROFILE.TOML>]
Upload a build image to the selected provider.
- upload log <UPLOAD-UUID>
Show the upload log
- upload cancel <UPLOAD-UUID>
Cancel an upload with that is queued or in progress
- upload delete <UPLOAD-UUID>
Delete the upload and remove it from the build
- upload reset <UPLOAD-UUID>
Reset the upload so that it can be tried again
- providers list <PROVIDER>
List the available providers, or list the <provider's> available profiles
- providers show <PROVIDER> <PROFILE>
show the details of a specific provider's profile
- providers push <PROFILE.TOML>
Add a new profile, or overwrite an existing one
- providers save <PROVIDER> <PROFILE>
Save the profile's details to a TOML file named <PROFILE>.toml
- providers delete <PROVIDER> <PROFILE>
Delete a profile from a provider
Edit a Blueprint¶
Start out by listing the available blueprints using
list, pick one and save it to the local directory by running
blueprints save http-server. If there are no blueprints available you can
copy one of the examples from the test suite.
Edit the file (it will be saved with a .toml extension) and change the
description, add a package or module to it. Send it back to the server by
composer-cli blueprints push http-server.toml. You can verify that it was
saved by viewing the changelog -
composer-cli blueprints changes http-server.
Build an image¶
qcow2 disk image from this blueprint by running
compose start http-server qcow2. It will print a UUID that you can use to
keep track of the build. You can also cancel the build if needed.
The available types of images is displayed by
composer-cli compose types.
Currently this consists of: alibaba, ami, ext4-filesystem, google, hyper-v,
live-iso, openstack, partitioned-disk, qcow2, tar, vhd, vmdk
You can optionally start an upload of the finished image, see Image Uploads for more information.
Monitor the build status¶
Monitor it using
composer-cli compose status, which will show the status of
all the builds on the system. You can view the end of the anaconda build logs
once it is in the
RUNNING state using
composer-cli compose log UUID
where UUID is the UUID returned by the start command.
Once the build is in the
FINISHED state you can download the image.
Download the image¶
Downloading the final image is done with
composer-cli compose image UUID and it will
save the qcow2 image as
UUID-disk.qcow2 which you can then use to boot a VM like this:
qemu-kvm --name test-image -m 1024 -hda ./UUID-disk.qcow2
composer-cli can upload the images to a number of services, including AWS,
OpenStack, and vSphere. The upload can be started when the build is finished,
composer-cli compose start ... or an existing image can be uploaded
composer-cli upload start .... In order to access the service you need
to pass authentication details to composer-cli using a TOML file, or reference
a previously saved profile.
Providers are the services providers with Ansible playbook support under
/usr/share/lorax/lifted/providers/, you will need to gather some provider
specific information in order to authenticate with it. You can view the
required fields using
composer-cli providers template <PROVIDER>, eg. for AWS
you would run:
composer-cli upload template aws
The output looks like this:
provider = "aws" [settings] aws_access_key = "AWS Access Key" aws_bucket = "AWS Bucket" aws_region = "AWS Region" aws_secret_key = "AWS Secret Key"
Save this into an
aws-credentials.toml file and use it when running
The access key and secret key can be created by going to the
IAM->Users->Security Credentials section and creating a new access key. The
secret key will only be shown when it is first created so make sure to record
it in a secure place. The region should be the region that you want to use the
AMI in, and the bucket can be an existing bucket, or a new one, following the
normal AWS bucket naming rules. It will be created if it doesn't already exist.
When uploading the image it is first uploaded to the s3 bucket, and then converted to an AMI. If the conversion is successful the s3 object will be deleted. If it fails, re-trying after correcting the problem will re-use the object if you have not deleted it in the meantime, speeding up the process.
Profiles store the authentication settings associated with a specific provider. Providers can have multiple profiles, as long as their names are unique. For example, you may have one profile for testing and another for production uploads.
Profiles are created by pushing the provider settings template to the server using
composer-cli providers push <PROFILE.TOML> where
PROFILE.TOML is the same as the
provider template, but with the addition of a
profile field. For example, an AWS
test-uploads would look like this:
provider = "aws" profile = "test-uploads" [settings] aws_access_key = "AWS Access Key" aws_bucket = "AWS Bucket" aws_region = "AWS Region" aws_secret_key = "AWS Secret Key"
You can view the profile by using
composer-cli providers aws test-uploads.
Build an image and upload results¶
If you have a profile named
composer-cli compose start example-http-server ami "http image" aws test-uploads
Or if you have the settings stored in a TOML file:
composer-cli compose start example-http-server ami "http image" aws-settings.toml
It will return the UUID of the image build, and the UUID of the upload. Once
the build has finished successfully it will start the upload process, which you
can monitor with
composer-cli upload info <UPLOAD-UUID>
You can also view the upload logs from the Ansible playbook with:
``composer-cli upload log <UPLOAD-UUID>``
The type of the image must match the type supported by the provider.
Upload an existing image¶
You can upload previously built images, as long as they are in the
FINISHED state, using
composer-cli upload start ...`. If you have a profile named
composer-cli upload start <UUID> "http-image" aws test-uploads
Or if you have the settings stored in a TOML file:
composer-cli upload start <UUID> "http-image" aws-settings.toml
This will output the UUID of the upload, which can then be used to monitor the status in the same way described above.