From a003c871b35842636ed99223868e11cd7cf1c25f Mon Sep 17 00:00:00 2001 From: "Brian C. Lane" Date: Wed, 10 Jun 2020 12:06:59 -0700 Subject: [PATCH] composer-cli: Add documentation for uploads and osbuild-composer Related: rhbz#1844649 --- docs/composer-cli.rst | 89 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 84 insertions(+), 5 deletions(-) diff --git a/docs/composer-cli.rst b/docs/composer-cli.rst index e9f055dc..71b6aaaa 100644 --- a/docs/composer-cli.rst +++ b/docs/composer-cli.rst @@ -4,12 +4,14 @@ composer-cli :Authors: Brian C. Lane -``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 ` and `osbuild-composer +` both implement compatible servers. -It requires `lorax-composer `_ to be installed on the -local system, and the user running it needs to be a member of the ``weldr`` -group. They do not need to be root, but all of the `security precautions -`_ apply. +It requires server to be installed on the local system, and the user running it +needs to be a member of the ``weldr`` group. They do not need to be root, but +all of the `security precautions `_ apply. 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:: 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.