almalinux/lorax
13
0
Fork 0
Code Issues Pull Requests Releases Activity

composer-cli: Add documentation for uploads and osbuild-composer

Browse Source 
Related: rhbz#1844649
This commit is contained in:
Brian C. Lane 2020-06-10 12:06:59 -07:00
parent c300ac6000
commit a003c871b3
1 changed files with 84 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
docs/composer-cli.rst
View File

@ -4,12 +4,14 @@ composer-cli
:Authors: :Authors:
Brian C. Lane <bcl@redhat.com> Brian C. Lane <bcl@redhat.com>
``composer-cli`` is used to interact with the ``lorax-composer`` API server, managing blueprints, exploring available packages, and building new images. ``composer-cli`` is an interactive tool for use with a WELDR API server,
managing blueprints, exploring available packages, and building new images.
`lorax-composer <lorax-composer.html>` and `osbuild-composer
<https://osbuild.org>` both implement compatible servers.
It requires `lorax-composer <lorax-composer.html>`_ to be installed on the It requires server to be installed on the local system, and the user running it
local system, and the user running it needs to be a member of the ``weldr`` needs to be a member of the ``weldr`` group. They do not need to be root, but
group. They do not need to be root, but all of the `security precautions all of the `security precautions <lorax-composer.html#security>`_ apply.
<lorax-composer.html#security>`_ apply.
composer-cli cmdline arguments composer-cli cmdline arguments
------------------------------ ------------------------------
@ -60,3 +62,80 @@ Downloading the final image is done with ``composer-cli compose image UUID`` and
save the qcow2 image as ``UUID-disk.qcow2`` which you can then use to boot a VM like this:: 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 qemu-kvm --name test-image -m 1024 -hda ./UUID-disk.qcow2
Image Uploads
-------------
``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
by using ``composer-cli compose start ...``. In order to access the service you need
to pass authentication details to composer-cli using a TOML file.
.. note::
This is only supported when running the ``osbuild-composer`` API server.
Providers
---------
Providers are where the images are uploaded to. You
will need to gather some provider
specific information in order to authenticate with it. Please refer to the ``osbuild-composer``
documentation for the provider specific fields. You will then create a TOML file with the
name of the provider and the settings, 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 ``start``.
AWS
^^^
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.
Build an image and upload results
---------------------------------
With 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. Once
the build has finished successfully it will start the upload process.
Debugging
---------
There are a couple of arguments that can be helpful when debugging problems.
These are only meant for debugging and should not be used to script access to
the API. If you need to do that you can communicate with it directly in the
language of your choice.
``--json`` will return the server's response as a nicely formatted json output
instead of printing what the command would usually print.
``--test=1`` will cause a compose start to start creating an image, and then
end with a failed state.
``--test=2`` will cause a compose to start and then end with a finished state,
without actually composing anything.