<ddclass="field-odd"><p>Brian C. Lane <<aclass="reference external"href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span></code> is used to interact with the <codeclass="docutils literal notranslate"><spanclass="pre">lorax-composer</span></code> API server, managing blueprints, exploring available packages, and building new images.</p>
<dt>compose start <BLUEPRINT><TYPE> [<IMAGE-NAME><PROVIDER><PROFILE> | <IMAGE-NAME><PROFILE.TOML>]</dt><dd><p>Start a compose using the selected blueprint and output type. Optionally start an upload.</p>
<dt>upload info <UPLOAD-UUID></dt><dd><p>Details about an upload</p>
</dd>
<dt>upload start <BUILD-UUID><IMAGE-NAME> [<PROVIDER><PROFILE>|<PROFILE.TOML>]</dt><dd><p>Upload a build image to the selected provider.</p>
</dd>
<dt>upload log <UPLOAD-UUID></dt><dd><p>Show the upload log</p>
</dd>
<dt>upload cancel <UPLOAD-UUID></dt><dd><p>Cancel an upload with that is queued or in progress</p>
</dd>
<dt>upload delete <UPLOAD-UUID></dt><dd><p>Delete the upload and remove it from the build</p>
</dd>
<dt>upload reset <UPLOAD-UUID></dt><dd><p>Reset the upload so that it can be tried again</p>
</dd>
<dt>providers list <PROVIDER></dt><dd><p>List the available providers, or list the <provider's> available profiles</p>
</dd>
<dt>providers show <PROVIDER><PROFILE></dt><dd><p>show the details of a specific provider's profile</p>
</dd>
<dt>providers push <PROFILE.TOML></dt><dd><p>Add a new profile, or overwrite an existing one</p>
</dd>
<dt>providers save <PROVIDER><PROFILE></dt><dd><p>Save the profile's details to a TOML file named <PROFILE>.toml</p>
</dd>
<dt>providers delete <PROVIDER><PROFILE></dt><dd><p>Delete a profile from a provider</p>
<p>Start out by listing the available blueprints using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span>
<spanclass="pre">list</span></code>, pick one and save it to the local directory by running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span>
<spanclass="pre">blueprints</span><spanclass="pre">save</span><spanclass="pre">http-server</span></code>. If there are no blueprints available you can
copy one of the examples <aclass="reference external"href="https://github.com/weldr/lorax/tree/master/tests/pylorax/blueprints/">from the test suite</a>.</p>
running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span><spanclass="pre">push</span><spanclass="pre">http-server.toml</span></code>. You can verify that it was
saved by viewing the changelog - <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span><spanclass="pre">changes</span><spanclass="pre">http-server</span></code>.</p>
<p>Build a <codeclass="docutils literal notranslate"><spanclass="pre">qcow2</span></code> disk image from this blueprint by running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span>
<spanclass="pre">compose</span><spanclass="pre">start</span><spanclass="pre">http-server</span><spanclass="pre">qcow2</span></code>. It will print a UUID that you can use to
keep track of the build. You can also cancel the build if needed.</p>
<p>The available types of images is displayed by <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">types</span></code>.
<p>Monitor it using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">status</span></code>, which will show the status of
once it is in the <codeclass="docutils literal notranslate"><spanclass="pre">RUNNING</span></code> state using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">log</span><spanclass="pre">UUID</span></code>
<p>Downloading the final image is done with <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">image</span><spanclass="pre">UUID</span></code> and it will
save the qcow2 image as <codeclass="docutils literal notranslate"><spanclass="pre">UUID-disk.qcow2</span></code> which you can then use to boot a VM like this:</p>
<h2>Image Uploads<aclass="headerlink"href="#image-uploads"title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span></code> 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 <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">start</span><spanclass="pre">...</span></code> or an existing image can be uploaded
with <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">upload</span><spanclass="pre">start</span><spanclass="pre">...</span></code>. 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.</p>
</div>
<divclass="section"id="providers">
<h2>Providers<aclass="headerlink"href="#providers"title="Permalink to this headline">¶</a></h2>
<p>Providers are the services providers with Ansible playbook support under
<codeclass="docutils literal notranslate"><spanclass="pre">/usr/share/lorax/lifted/providers/</span></code>, you will need to gather some provider
specific information in order to authenticate with it. You can view the
required fields using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">providers</span><spanclass="pre">template</span><spanclass="pre"><PROVIDER></span></code>, eg. for AWS
<p>Save this into an <codeclass="docutils literal notranslate"><spanclass="pre">aws-credentials.toml</span></code> file and use it when running <codeclass="docutils literal notranslate"><spanclass="pre">start</span></code>.</p>
<divclass="section"id="aws">
<h3>AWS<aclass="headerlink"href="#aws"title="Permalink to this headline">¶</a></h3>
<p>The access key and secret key can be created by going to the
<codeclass="docutils literal notranslate"><spanclass="pre">IAM->Users->Security</span><spanclass="pre">Credentials</span></code> 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.</p>
<p>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.</p>
</div>
</div>
<divclass="section"id="profiles">
<h2>Profiles<aclass="headerlink"href="#profiles"title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>Profiles are created by pushing the provider settings template to the server using
<codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">providers</span><spanclass="pre">push</span><spanclass="pre"><PROFILE.TOML></span></code> where <codeclass="docutils literal notranslate"><spanclass="pre">PROFILE.TOML</span></code> is the same as the
provider template, but with the addition of a <codeclass="docutils literal notranslate"><spanclass="pre">profile</span></code> field. For example, an AWS
profile named <codeclass="docutils literal notranslate"><spanclass="pre">test-uploads</span></code> would look like this:</p>
<p>You can view the profile by using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">providers</span><spanclass="pre">aws</span><spanclass="pre">test-uploads</span></code>.</p>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">upload</span><spanclass="pre">info</span><spanclass="pre"><UPLOAD-UUID></span></code></p>
<p>You can also view the upload logs from the Ansible playbook with:</p>
<p>The type of the image must match the type supported by the provider.</p>
</div>
<divclass="section"id="upload-an-existing-image">
<h2>Upload an existing image<aclass="headerlink"href="#upload-an-existing-image"title="Permalink to this headline">¶</a></h2>
<p>You can upload previously built images, as long as they are in the <codeclass="docutils literal notranslate"><spanclass="pre">FINISHED</span></code> state, using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">upload</span><spanclass="pre">start</span><spanclass="pre">...`</span></code>. If you have a profile named <codeclass="docutils literal notranslate"><spanclass="pre">test-uploads</span></code>:</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
