pylorax.api package

Submodules

pylorax.api.bisect module

pylorax.api.bisect.insort_left(a, x, key=None, lo=0, hi=None)

Insert item x in list a, and keep it sorted assuming a is sorted.

Parameters

• a (list) -- sorted list

• x (object) -- item to insert into the list

• key (function) -- Function to use to compare items in the list

Returns

index where the item was inserted

Return type

int

If x is already in a, insert it to the left of the leftmost x. Optional args lo (default 0) and hi (default len(a)) bound the slice of a to be searched.

This is a modified version of bisect.insort_left that can use a function for the compare, and returns the index position where it was inserted.

pylorax.api.checkparams module

pylorax.api.checkparams.checkparams(tuples)

pylorax.api.cmdline module

pylorax.api.cmdline.lorax_composer_parser()

Return the ArgumentParser for lorax-composer

pylorax.api.compose module

Setup for composing an image

Adding New Output Types

The new output type must add a kickstart template to ./share/composer/ where the name of the kickstart (without the trailing .ks) matches the entry in compose_args.

The kickstart should not have any url or repo entries, these will be added at build time. The %packages section should be the last thing, and while it can contain mandatory packages required by the output type, it should not have the trailing %end because the package NEVRAs will be appended to it at build time.

compose_args should have a name matching the kickstart, and it should set the novirt_install parameters needed to generate the desired output. Other types should be set to False.

pylorax.api.compose.add_customizations(f, recipe)

Add customizations to the kickstart file

Parameters

• f (open file object) -- kickstart file object

• recipe (Recipe object) --

Returns

None

Raises

RuntimeError if there was a problem writing to the kickstart

pylorax.api.compose.bootloader_append(line, kernel_append)

Insert the kernel_append string into the --append argument

Parameters

• line (str) -- The bootloader ... line

• kernel_append (str) -- The arguments to append to the --append section

Using pykickstart to process the line is the best way to make sure it is parsed correctly, and re-assembled for inclusion into the final kickstart

pylorax.api.compose.compose_args(compose_type)

Returns the settings to pass to novirt_install for the compose type

Parameters

compose_type (str) -- The type of compose to create, from compose_types()

This will return a dict of options that match the ArgumentParser options for livemedia-creator. These are the ones the define the type of output, it's filename, etc. Other options will be filled in by make_compose()

pylorax.api.compose.compose_types(share_dir)

Returns a list of tuples of the supported output types, and their state

The output types come from the kickstart names in /usr/share/lorax/composer/*ks

If they are disabled on the current arch their state is False. If enabled, it is True. eg. [("alibaba", False), ("ext4-filesystem", True), ...]

pylorax.api.compose.customize_ks_template(ks_template, recipe)

Customize the kickstart template and return it

Parameters

• ks_template (str) -- The kickstart template

• recipe (Recipe object) --

Apply customizations to existing template commands, or add defaults for ones that are missing and required.

Apply customizations.kernel.append to the bootloader argument in the template. Add bootloader line if it is missing.

Add default timezone if needed. It does NOT replace an existing timezone entry

pylorax.api.compose.firewall_cmd(line, settings)

Update the firewall line with the new ports and services

Parameters

• line (str) -- The firewall ... line

• settings (dict) -- A dict with the list of services and ports to enable and disable

Using pykickstart to process the line is the best way to make sure it is parsed correctly, and re-assembled for inclusion into the final kickstart

pylorax.api.compose.get_default_services(recipe)

Get the default string for services, based on recipe :param recipe: The recipe

Returns

string with "services" or ""

Return type

str

When no services have been selected we don't need to add anything to the kickstart so return an empty string. Otherwise return "services" which will be updated with the settings.

pylorax.api.compose.get_extra_pkgs(dbo, share_dir, compose_type)

Return extra packages needed for the output type

Parameters

• dbo (dnf.Base) -- dnf base object

• share_dir (str) -- Path to the top level share directory

• compose_type (str) -- The type of output to create from the recipe

Returns

List of package names (name only, not NEVRA)

Return type

list

Currently this is only needed by live-iso, it reads ./live/live-install.tmpl and processes only the installpkg lines. It lists the packages needed to complete creation of the iso using the templates such as x86.tmpl

Keep in mind that the live-install.tmpl is shared between livemedia-creator and lorax-composer, even though the results are applied differently.

pylorax.api.compose.get_firewall_settings(recipe)

Return the customizations.firewall settings

Parameters

recipe (Recipe object) -- The recipe

Returns

A dict of settings

Return type

dict

pylorax.api.compose.get_kernel_append(recipe)

Return the customizations.kernel append value

Parameters

recipe (Recipe object) --

Returns

append value or empty string

Return type

str

pylorax.api.compose.get_keyboard_layout(recipe)

Return the customizations.locale.keyboard list

Parameters

recipe (Recipe object) -- The recipe

Returns

The keyboard layout string

Return type

str

pylorax.api.compose.get_languages(recipe)

Return the customizations.locale.languages list

Parameters

recipe (Recipe object) -- The recipe

Returns

list of language strings

Return type

list

pylorax.api.compose.get_services(recipe)

Return the customizations.services settings

Parameters

recipe (Recipe object) -- The recipe

Returns

A dict of settings

Return type

dict

pylorax.api.compose.get_timezone_settings(recipe)

Return the customizations.timezone dict

Parameters

recipe (Recipe object) --

Returns

append value or empty string

Return type

dict

pylorax.api.compose.keyboard_cmd(line, layout)

Update the keyboard line with the layout

Parameters

• line (str) -- The keyboard ... line

• settings (str) -- The keyboard layout

Using pykickstart to process the line is the best way to make sure it is parsed correctly, and re-assembled for inclusion into the final kickstart

pylorax.api.compose.lang_cmd(line, languages)

Update the lang line with the languages

Parameters

• line (str) -- The lang ... line

• settings (list) -- The list of languages

Using pykickstart to process the line is the best way to make sure it is parsed correctly, and re-assembled for inclusion into the final kickstart

pylorax.api.compose.move_compose_results(cfg, results_dir)

Move the final image to the results_dir and cleanup the unneeded compose files

Parameters

• cfg (DataHolder) -- Build configuration

• results_dir (str) -- Directory to put the results into

pylorax.api.compose.repo_to_ks(r, url='url')

Return a kickstart line with the correct args. :param r: DNF repository information :type r: dnf.Repo :param url: "url" or "baseurl" to use for the baseurl parameter :type url: str :returns: kickstart command arguments for url/repo command :rtype: str

Set url to "baseurl" if it is a repo, leave it as "url" for the installation url.

pylorax.api.compose.services_cmd(line, settings)

Update the services line with additional services to enable/disable

Parameters

• line (str) -- The services ... line

• settings (dict) -- A dict with the list of services to enable and disable

Using pykickstart to process the line is the best way to make sure it is parsed correctly, and re-assembled for inclusion into the final kickstart

pylorax.api.compose.start_build(cfg, dnflock, gitlock, branch, recipe_name, compose_type, test_mode=0)

Start the build

Parameters

• cfg (ComposerConfig) -- Configuration object

• dnflock (YumLock) -- Lock and YumBase for depsolving

• recipe (str) -- The recipe to build

• compose_type (str) -- The type of output to create from the recipe

Returns

Unique ID for the build that can be used to track its status

Return type

str

pylorax.api.compose.test_templates(dbo, share_dir)

Try depsolving each of the the templates and report any errors

Parameters

dbo (dnf.Base) -- dnf base object

Returns

List of template types and errors

Return type

List of errors

Return a list of templates and errors encountered or an empty list

pylorax.api.compose.timezone_cmd(line, settings)

Update the timezone line with the settings

Parameters

• line (str) -- The timezone ... line

• settings (dict) -- A dict with timezone and/or ntpservers list

Using pykickstart to process the line is the best way to make sure it is parsed correctly, and re-assembled for inclusion into the final kickstart

pylorax.api.compose.write_ks_group(f, group)

Write kickstart group entry

Parameters

• f (open file object) -- kickstart file object

• group -- A blueprint group dictionary

gid is optional

pylorax.api.compose.write_ks_root(f, user)

Write kickstart root password and sshkey entry

Parameters

• f (open file object) -- kickstart file object

• user (dict) -- A blueprint user dictionary

Returns

True if it wrote a rootpw command to the kickstart

Return type

bool

If the entry contains a ssh key, use sshkey to write it If it contains password, use rootpw to set it

root cannot be used with the user command. So only key and password are supported for root.

pylorax.api.compose.write_ks_user(f, user)

Write kickstart user and sshkey entry

Parameters

• f (open file object) -- kickstart file object

• user (dict) -- A blueprint user dictionary

If the entry contains a ssh key, use sshkey to write it All of the user fields are optional, except name, write out a kickstart user entry with whatever options are relevant.

pylorax.api.config module

class pylorax.api.config.ComposerConfig(defaults=None, dict_type=<class 'collections.OrderedDict'>, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section='DEFAULT', interpolation=<object object>, converters=<object object>)

Bases: configparser.ConfigParser

get_default(section, option, default)

pylorax.api.config.configure(conf_file='/etc/lorax/composer.conf', root_dir='/', test_config=False)

lorax-composer configuration

Parameters

• conf_file (str) -- Path to the config file overriding the default settings

• root_dir (str) -- Directory to prepend to paths, defaults to /

• test_config (bool) -- Set to True to skip reading conf_file

Returns

Configuration

Return type

ComposerConfig

pylorax.api.config.make_dnf_dirs(conf, uid, gid)

Make any missing dnf directories owned by user:group

Parameters

• conf (ComposerConfig) -- The configuration to use

• uid (int) -- uid of owner

• gid (int) -- gid of owner

Returns

list of errors

Return type

list of str

pylorax.api.config.make_owned_dir(p_dir, uid, gid)

Make a directory and its parents, setting owner and group

Parameters

• p_dir (string) -- path to directory to create

• uid (int) -- uid of owner

• gid (int) -- gid of owner

Returns

list of errors

Return type

list of str

Check to make sure it does not have o+rw permissions and that it is owned by uid:gid

pylorax.api.config.make_queue_dirs(conf, gid)

Make any missing queue directories

Parameters

• conf (ComposerConfig) -- The configuration to use

• gid (int) -- Group ID that has access to the queue directories

Returns

list of errors

Return type

list of str

pylorax.api.dnfbase module

class pylorax.api.dnfbase.DNFLock(conf, expire_secs=21600)

Bases: object

Hold the dnf.Base object and a Lock to control access to it.

self.dbo is a property that returns the dnf.Base object, but it may change from one call to the next if the upstream repositories have changed.

property lock

Check for repo updates (using expiration time) and return the lock

If the repository has been updated, tear down the old dnf.Base and create a new one. This is the only way to force dnf to use the new metadata.

property lock_check

Force a check for repo updates and return the lock

Use this method sparingly, it removes the repodata and downloads a new copy every time.

pylorax.api.dnfbase.get_base_object(conf)

Get the DNF object with settings from the config file

Parameters

conf (ComposerParser) -- configuration object

Returns

A DNF Base object

Return type

dnf.Base

pylorax.api.errors module

pylorax.api.flask_blueprint module

Flask Blueprints that support skipping routes

When using Blueprints for API versioning you will usually want to fall back to the previous version's rules for routes that have no new behavior. To do this we add a 'skip_rule' list to the Blueprint's options dictionary. It lists all of the routes that you do not want to register.

For example:

from pylorax.api.v0 import v0 from pylorax.api.v1 import v1

server.register_blueprint(v0, url_prefix="/api/v0/") server.register_blueprint(v0, url_prefix="/api/v1/", skip_rules=["/blueprints/list"] server.register_blueprint(v1, url_prefix="/api/v1/")

This will register all of v0's routes under /api/v0, and all but /blueprints/list under /api/v1, and then register v1's version of /blueprints/list under /api/v1

class pylorax.api.flask_blueprint.BlueprintSetupStateSkip(blueprint, app, options, first_registration, skip_rules)

Bases: flask.blueprints.BlueprintSetupState

add_url_rule(rule, endpoint=None, view_func=None, **options)

A helper method to register a rule (and optionally a view function) to the application. The endpoint is automatically prefixed with the blueprint's name.

class pylorax.api.flask_blueprint.BlueprintSkip(*args, **kwargs)

Bases: flask.blueprints.Blueprint

make_setup_state(app, options, first_registration=False)

Creates an instance of BlueprintSetupState() object that is later passed to the register callback functions. Subclasses can override this to return a subclass of the setup state.

pylorax.api.gitrpm module

Clone a git repository and package it as an rpm

This module contains functions for cloning a git repo, creating a tar archive of the selected commit, branch, or tag, and packaging the files into an rpm that will be installed by anaconda when creating the image.

class pylorax.api.gitrpm.GitArchiveTarball(gitRepo)

Bases: object

Create a git archive of the selected git repo and reference

write_file(sourcesDir)

Create the tar archive

Parameters

sourcesDir (str) -- Path to use for creating the archive

This clones the git repository and creates a git archive from the specified reference. The result is in RPMNAME.tar.xz under the sourcesDir

class pylorax.api.gitrpm.GitRpmBuild(*args, **kwargs)

Bases: rpmfluff.SimpleRpmBuild

Build an rpm containing files from a git repository

add_git_tarball(gitRepo)

Add a tar archive of a git repository to the rpm

Parameters

gitRepo (dict) -- A dict with the repository details

This populates the rpm with the URL of the git repository, the summary describing the repo, the description of the repository and reference used, and sets up the rpm to install the archive contents into the destination path.

check()

clean()

Remove the base directory from inside the tmpdir

cleanup_tmpdir()

Remove the temporary directory and all of its contents

get_base_dir()

Place all the files under a temporary directory + rpmbuild/

pylorax.api.gitrpm.create_gitrpm_repo(results_dir, recipe)

Create a dnf repository with the rpms from the recipe

Parameters

• results_dir (str) -- Path to create the repository under

• recipe (Recipe) -- The recipe to get the repos.git entries from

Returns

Path to the dnf repository or ""

Return type

str

This function creates a dnf repository directory at results_dir+"repo/", creates rpms for all of the repos.git entries in the recipe, runs createrepo_c on the dnf repository so that Anaconda can use it, and returns the path to the repository to the caller.

pylorax.api.gitrpm.get_repo_description(gitRepo)

Return a description including the git repo and reference

Parameters

gitRepo (dict) -- A dict with the repository details

Returns

A string with the git repo url and reference

Return type

str

pylorax.api.gitrpm.make_git_rpm(gitRepo, dest)

Create an rpm from the specified git repo

Parameters

gitRepo (dict) -- A dict with the repository details

This will clone the git repository, create an archive of the selected reference, and build an rpm that will install the files from the repository under the destination directory. The gitRepo dict should have the following fields:

rpmname: "server-config"
rpmversion: "1.0"
rpmrelease: "1"
summary: "Setup files for server deployment"
repo: "PATH OF GIT REPO TO CLONE"
ref: "v1.0"
destination: "/opt/server/"

• rpmname: Name of the rpm to create, also used as the prefix name in the tar archive

• rpmversion: Version of the rpm, eg. "1.0.0"

• rpmrelease: Release of the rpm, eg. "1"

• summary: Summary string for the rpm

• repo: URL of the get repo to clone and create the archive from

• ref: Git reference to check out. eg. origin/branch-name, git tag, or git commit hash

• destination: Path to install the / of the git repo at when installing the rpm

pylorax.api.projects module

exception pylorax.api.projects.ProjectsError

Bases: Exception

pylorax.api.projects.api_changelog(changelog)

Convert the changelog to a string

Parameters

changelog (tuple) -- A list of time, author, string tuples.

Returns

The most recent changelog text or ""

Return type

str

This returns only the most recent changelog entry.

pylorax.api.projects.api_time(t)

Convert time since epoch to a string

Parameters

t (int) -- Seconds since epoch

Returns

Time string

Return type

str

pylorax.api.projects.delete_repo_source(source_glob, source_id)

Delete a source from a repo file

Parameters

• source_glob (str) -- A glob of the repo sources to search

• source_id (str) -- The repo id to delete

Returns

None

Raises

ProjectsError if there was a problem

A repo file may have multiple sources in it, delete only the selected source. If it is the last one in the file, delete the file.

WARNING: This will delete ANY source, the caller needs to ensure that a system source_id isn't passed to it.

pylorax.api.projects.dep_evra(dep)

Return the epoch:version-release.arch for the dep

Parameters

dep (dict) -- dependency dict

Returns

epoch:version-release.arch

Return type

str

pylorax.api.projects.dep_nevra(dep)

Return the name-epoch:version-release.arch

pylorax.api.projects.dnf_repo_to_file_repo(repo)

Return a string representation of a DNF Repo object suitable for writing to a .repo file

Parameters

repo (dnf.RepoDict) -- DNF Repository

Returns

A string

Return type

str

The DNF Repo.dump() function does not produce a string that can be used as a dnf .repo file, it ouputs baseurl and gpgkey as python lists which DNF cannot read. So do this manually with only the attributes we care about.

pylorax.api.projects.estimate_size(packages, block_size=6144)

Estimate the installed size of a package list

Parameters

• packages (list of hawkey.Package objects) -- The packages to be installed

• block_size (int) -- The block size to use for rounding up file sizes.

Returns

The estimated size of installed packages

Return type

int

Estimating actual requirements is difficult without the actual file sizes, which dnf doesn't provide access to. So use the file count and block size to estimate a minimum size for each package.

pylorax.api.projects.get_repo_sources(source_glob)

Return a list of sources from a directory of yum repositories

Parameters

source_glob (str) -- A glob to use to match the source files, including full path

Returns

A list of the source ids in all of the matching files

Return type

list of str

pylorax.api.projects.get_source_ids(source_path)

Return a list of the source ids in a file

Parameters

source_path (str) -- Full path and filename of the source (yum repo) file

Returns

A list of source id strings

Return type

list of str

pylorax.api.projects.modules_info(dbo, module_names)

Return details about a module, including dependencies

Parameters

• dbo (dnf.Base) -- dnf base object

• module_names (str) -- Names of the modules to get info about

Returns

List of dicts with module details and dependencies.

Return type

list of dicts

pylorax.api.projects.modules_list(dbo, module_names)

Return a list of modules

Parameters

• dbo (dnf.Base) -- dnf base object

• offset -- Number of modules to skip

• limit (int) -- Maximum number of modules to return

Returns

List of module information and total count

Return type

tuple of a list of dicts and an Int

Modules don't exist in RHEL7 so this only returns projects and sets the type to "rpm"

pylorax.api.projects.new_repo_source(dbo, repoid, source, repo_dir)

Add a new repo source from a Weldr source dict

Parameters

• dbo (dnf.Base) -- dnf base object

• id (str) -- The repo id (API v0 uses the name, v1 uses the id)

• source (dict) -- A Weldr source dict

Returns

None

Raises

...

Make sure access to the dbo has been locked before calling this. The id parameter will the the 'name' field for API v0, and the 'id' field for API v1

DNF variables will be substituted at load time, and on restart.

pylorax.api.projects.pkg_to_build(pkg)

Extract the build details from a hawkey.Package object

Parameters

pkg (hawkey.Package) -- hawkey.Package object with package details

Returns

A dict with the build details, epoch, release, arch, build_time, changelog, ...

Return type

dict

metadata entries are hard-coded to {}

Note that this only returns the build dict, it does not include the name, description, etc.

pylorax.api.projects.pkg_to_dep(pkg)

Extract the info from a hawkey.Package object

Parameters

pkg (hawkey.Package) -- A hawkey.Package object

Returns

A dict with name, epoch, version, release, arch

Return type

dict

pylorax.api.projects.pkg_to_project(pkg)

Extract the details from a hawkey.Package object

Parameters

pkgs (hawkey.Package) -- hawkey.Package object with package details

Returns

A dict with the name, summary, description, and url.

Return type

dict

upstream_vcs is hard-coded to UPSTREAM_VCS

pylorax.api.projects.pkg_to_project_info(pkg)

Extract the details from a hawkey.Package object

Parameters

pkg (hawkey.Package) -- hawkey.Package object with package details

Returns

A dict with the project details, as well as epoch, release, arch, build_time, changelog, ...

Return type

dict

metadata entries are hard-coded to {}

pylorax.api.projects.proj_to_module(proj)

Extract the name from a project_info dict

Parameters

pkg (dict) -- dict with package details

Returns

A dict with name, and group_type

Return type

dict

group_type is hard-coded to "rpm"

pylorax.api.projects.projects_depsolve(dbo, projects, groups)

Return the dependencies for a list of projects

Parameters

• dbo (dnf.Base) -- dnf base object

• projects (List of Strings) -- The projects to find the dependencies for

• groups (List of str) -- The groups to include in dependency solving

Returns

NEVRA's of the project and its dependencies

Return type

list of dicts

Raises

ProjectsError if there was a problem installing something

pylorax.api.projects.projects_depsolve_with_size(dbo, projects, groups, with_core=True)

Return the dependencies and installed size for a list of projects

Parameters

• dbo (dnf.Base) -- dnf base object

• project_names (List of Strings) -- The projects to find the dependencies for

• groups (List of str) -- The groups to include in dependency solving

Returns

installed size and a list of NEVRA's of the project and its dependencies

Return type

tuple of (int, list of dicts)

Raises

ProjectsError if there was a problem installing something

pylorax.api.projects.projects_info(dbo, project_names)

Return details about specific projects

Parameters

• dbo (dnf.Base) -- dnf base object

• project_names (str) -- List of names of projects to get info about

Returns

List of project info dicts with pkg_to_project as well as epoch, version, release, etc.

Return type

list of dicts

If project_names is None it will return the full list of available packages

pylorax.api.projects.projects_list(dbo)

Return a list of projects

Parameters

dbo (dnf.Base) -- dnf base object

Returns

List of project info dicts with name, summary, description, homepage, upstream_vcs

Return type

list of dicts

pylorax.api.projects.repo_to_source(repo, system_source, api=1)

Return a Weldr Source dict created from the DNF Repository

Parameters

• repo (dnf.RepoDict) -- DNF Repository

• system_source (bool) -- True if this source is an immutable system source

• api (int) -- Select which api version of the dict to return (default 1)

Returns

A dict with Weldr Source fields filled in

Return type

dict

Example:

{
  "check_gpg": true,
  "check_ssl": true,
  "gpgkey_url": [
    "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-28-x86_64"
  ],
  "id": "fedora",
  "name": "Fedora $releasever - $basearch",
  "proxy": "http://proxy.brianlane.com:8123",
  "system": true
  "type": "yum-metalink",
  "url": "https://mirrors.fedoraproject.org/metalink?repo=fedora-28&arch=x86_64"
}

The name field has changed in v1 of the API. In v0 of the API name is the repo.id, in v1 it is the repo.name and a new field, id has been added for the repo.id

pylorax.api.projects.source_to_repo(source, dnf_conf)

Return a dnf Repo object created from a source dict

Parameters

• source (dict) -- A Weldr source dict

• dnf_conf (dnf.conf) -- The dnf Config object

Returns

A dnf Repo object

Return type

dnf.Repo

Example:

{
  "check_gpg": True,
  "check_ssl": True,
  "gpgkey_urls": [
    "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-28-x86_64"
  ],
  "id": "fedora",
  "name": "Fedora $releasever - $basearch",
  "proxy": "http://proxy.brianlane.com:8123",
  "system": True
  "type": "yum-metalink",
  "url": "https://mirrors.fedoraproject.org/metalink?repo=fedora-28&arch=x86_64"
}

If the id field is included it is used for the repo id, otherwise name is used. v0 of the API only used name, v1 added the distinction between id and name.

pylorax.api.projects.source_to_repodict(source)

Return a tuple suitable for use with dnf.add_new_repo

Parameters

source (dict) -- A Weldr source dict

Returns

A tuple of dnf.Repo attributes

Return type

(str, list, dict)

Return a tuple with (id, baseurl|(), kwargs) that can be used with dnf.repos.add_new_repo

pylorax.api.queue module

Functions to monitor compose queue and run anaconda

pylorax.api.queue.build_status(cfg, status_filter=None, api=1)

Return the details of finished or failed builds

Parameters

• cfg (ComposerConfig) -- Configuration settings

• status_filter (str) -- What builds to return. None == all, "FINISHED", or "FAILED"

• api (int) -- Select which api version of the dict to return (default 1)

Returns

A list of the build details (from compose_detail)

Return type

list of dicts

This returns a list of build details for each of the matching builds on the system. It does not return the status of builds that have not been finished. Use queue_status() for those.

pylorax.api.queue.check_queues(cfg)

Check to make sure the new and run queue symlinks are correct

Parameters

cfg (DataHolder) -- Configuration settings

Also check all of the existing results and make sure any with WAITING set in STATUS have a symlink in queue/new/

pylorax.api.queue.compose_detail(cfg, results_dir, api=1)

Return details about the build.

Parameters

• cfg (ComposerConfig) -- Configuration settings (required for api=1)

• results_dir (str) -- The directory containing the metadata and results for the build

• api (int) -- Select which api version of the dict to return (default 1)

Returns

A dictionary with details about the compose

Return type

dict

Raises

IOError if it cannot read the directory, STATUS, or blueprint file.

The following details are included in the dict:

• id - The uuid of the comoposition

• queue_status - The final status of the composition (FINISHED or FAILED)

• compose_type - The type of output generated (tar, iso, etc.)

• blueprint - Blueprint name

• version - Blueprint version

• image_size - Size of the image, if finished. 0 otherwise.

• uploads - For API v1 details about uploading the image are included

Various timestamps are also included in the dict. These are all Unix UTC timestamps. It is possible for these timestamps to not always exist, in which case they will be None in Python (or null in JSON). The following timestamps are included:

• job_created - When the user submitted the compose

• job_started - Anaconda started running

• job_finished - Job entered FINISHED or FAILED state

pylorax.api.queue.get_compose_type(results_dir)

Return the type of composition.

Parameters

results_dir (str) -- The directory containing the metadata and results for the build

Returns

The type of compose (eg. 'tar')

Return type

str

Raises

RuntimeError if no kickstart template can be found.

pylorax.api.queue.get_image_name(uuid_dir)

Return the filename and full path of the build's image file

Parameters

uuid (str) -- The UUID of the build

Returns

The image filename and full path

Return type

tuple of strings

Raises

RuntimeError if there was a problem (eg. invalid uuid, missing config file)

pylorax.api.queue.make_compose(cfg, results_dir)

Run anaconda with the final-kickstart.ks from results_dir

Parameters

• cfg (DataHolder) -- Configuration settings

• results_dir (str) -- The directory containing the metadata and results for the build

Returns

Nothing

Raises

May raise various exceptions

This takes the final-kickstart.ks, and the settings in config.toml and runs Anaconda in no-virt mode (directly on the host operating system). Exceptions should be caught at the higer level.

If there is a failure, the build artifacts will be cleaned up, and any logs will be moved into logs/anaconda/ and their ownership will be set to the user from the cfg object.

pylorax.api.queue.monitor(cfg)

Monitor the queue for new compose requests

Parameters

cfg (DataHolder) -- Configuration settings

Returns

Does not return

The queue has 2 subdirectories, new and run. When a compose is ready to be run a symlink to the uniquely named results directory should be placed in ./queue/new/

When the it is ready to be run (it is checked every 30 seconds or after a previous compose is finished) the symlink will be moved into ./queue/run/ and a STATUS file will be created in the results directory.

STATUS can contain one of: WAITING, RUNNING, FINISHED, FAILED

If the system is restarted while a compose is running it will move any old symlinks from ./queue/run/ to ./queue/new/ and rerun them.

pylorax.api.queue.queue_status(cfg, api=1)

Return details about what is in the queue.

Parameters

• cfg (ComposerConfig) -- Configuration settings

• api (int) -- Select which api version of the dict to return (default 1)

Returns

A list of the new composes, and a list of the running composes

Return type

dict

This returns a dict with 2 lists. "new" is the list of uuids that are waiting to be built, and "run" has the uuids that are being built (currently limited to 1 at a time).

pylorax.api.queue.start_queue_monitor(cfg, uid, gid)

Start the queue monitor as a mp process

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uid (int) -- User ID that owns the queue

• gid (int) -- Group ID that owns the queue

Returns

None

pylorax.api.queue.uuid_add_upload(cfg, uuid, upload_uuid)

Add an upload UUID to a build

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

• upload_uuid (str) -- The UUID of the upload

Returns

None

Return type

None

pylorax.api.queue.uuid_cancel(cfg, uuid)

Cancel a build and delete its results

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

Returns

True if it was canceled and deleted

Return type

bool

Only call this if the build status is WAITING or RUNNING

pylorax.api.queue.uuid_delete(cfg, uuid)

Delete all of the results from a compose

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

Returns

True if it was deleted

Return type

bool

Raises

This will raise an error if the delete failed

pylorax.api.queue.uuid_get_uploads(cfg, uuid)

Return the list of uploads for a build uuid

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

Returns

The upload UUIDs associated with the build UUID

Return type

frozenset

pylorax.api.queue.uuid_image(cfg, uuid)

Return the filename and full path of the build's image file

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

Returns

The image filename and full path

Return type

tuple of strings

Raises

RuntimeError if there was a problem (eg. invalid uuid, missing config file)

pylorax.api.queue.uuid_info(cfg, uuid, api=1)

Return information about the composition

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

Returns

dictionary of information about the composition or None

Return type

dict

Raises

RuntimeError if there was a problem

This will return a dict with the following fields populated:

• id - The uuid of the comoposition

• config - containing the configuration settings used to run Anaconda

• blueprint - The depsolved blueprint used to generate the kickstart

• commit - The (local) git commit hash for the blueprint used

• deps - The NEVRA of all of the dependencies used in the composition

• compose_type - The type of output generated (tar, iso, etc.)

• queue_status - The final status of the composition (FINISHED or FAILED)

pylorax.api.queue.uuid_log(cfg, uuid, size=1024)

Return size KiB from the end of the most currently relevant log for a given compose

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

• size (int) -- Number of KiB to read. Default is 1024

Returns

Up to size KiB from the end of the log

Return type

str

Raises

RuntimeError if there was a problem (eg. no log file available)

This function will return the end of either the anaconda log, the packaging log, or the combined composer logs, depending on the progress of the compose. It tries to return lines from the end of the log, it will attempt to start on a line boundary, and it may return less than size kbytes.

pylorax.api.queue.uuid_ready_upload(cfg, uuid, upload_uuid)

Set an upload to READY if the build is in FINISHED state

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

• upload_uuid (str) -- The UUID of the upload

Returns

None

Return type

None

Raises

RuntimeError if the build uuid is invalid or not in FINISHED state.

pylorax.api.queue.uuid_remove_upload(cfg, upload_uuid)

Remove an upload UUID from the build

Parameters

• cfg (ComposerConfig) -- Configuration settings

• upload_uuid (str) -- The UUID of the upload

Returns

None

Return type

None

Raises

RuntimeError if the upload_uuid is not found

pylorax.api.queue.uuid_schedule_upload(cfg, uuid, provider_name, image_name, settings)

Schedule an upload of an image

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

• provider_name (str) -- The name of the cloud provider, e.g. "azure"

• image_name (str) -- Path of the image to upload

• settings (dict) -- Settings to use for the selected provider

Returns

uuid of the upload

Return type

str

Raises

RuntimeError if the uuid is not a valid build uuid

pylorax.api.queue.uuid_status(cfg, uuid, api=1)

Return the details of a specific UUID compose

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

• api (int) -- Select which api version of the dict to return (default 1)

Returns

Details about the build

Return type

dict or None

Returns the same dict as compose_detail()

pylorax.api.queue.uuid_tar(cfg, uuid, metadata=False, image=False, logs=False)

Return a tar of the build data

Parameters

• cfg (ComposerConfig) -- Configuration settings

• uuid (str) -- The UUID of the build

• metadata (bool) -- Set to true to include all the metadata needed to reproduce the build

• image (bool) -- Set to true to include the output image

• logs (bool) -- Set to true to include the logs from the build

Returns

A stream of bytes from tar

Return type

A generator

Raises

RuntimeError if there was a problem (eg. missing config file)

This yields an uncompressed tar's data to the caller. It includes the selected data to the caller by returning the Popen stdout from the tar process.

pylorax.api.recipes module

class pylorax.api.recipes.CommitDetails(commit, timestamp, message, revision=None)

Bases: pylorax.base.DataHolder

exception pylorax.api.recipes.CommitTimeValError

Bases: Exception

pylorax.api.recipes.NewRecipeGit(toml_dict)

Create a RecipeGit object from fields in a TOML dict

Parameters

• rpmname (str) -- Name of the rpm to create, also used as the prefix name in the tar archive

• rpmversion (str) -- Version of the rpm, eg. "1.0.0"

• rpmrelease (str) -- Release of the rpm, eg. "1"

• summary (str) -- Summary string for the rpm

• repo (str) -- URL of the get repo to clone and create the archive from

• ref (str) -- Git reference to check out. eg. origin/branch-name, git tag, or git commit hash

• destination (str) -- Path to install the / of the git repo at when installing the rpm

Returns

A populated RecipeGit object

Return type

RecipeGit

The TOML should look like this:

[[repos.git]]
rpmname="server-config"
rpmversion="1.0"
rpmrelease="1"
summary="Setup files for server deployment"
repo="PATH OF GIT REPO TO CLONE"
ref="v1.0"
destination="/opt/server/"

Note that the repo path supports anything that git supports, file://, https://, http://

Currently there is no support for authentication

class pylorax.api.recipes.Recipe(name, description, version, modules, packages, groups, customizations=None, gitrepos=None)

Bases: dict

A Recipe of package and modules

This is a subclass of dict that enforces the constructor arguments and adds a .filename property to return the recipe's filename, and a .toml() function to return the recipe as a TOML string.

bump_version(old_version=None)

semver recipe version number bump

Parameters

old_version (str) -- An optional old version number

Returns

The new version number or None

Return type

str

Raises

ValueError

If neither have a version, 0.0.1 is returned If there is no old version the new version is checked and returned If there is no new version, but there is a old one, bump its patch level If the old and new versions are the same, bump the patch level If they are different, check and return the new version

property filename

Return the Recipe's filename

Replaces spaces in the name with '-' and appends .toml

freeze(deps)

Return a new Recipe with full module and package NEVRA

Parameters

deps (list() -- A list of dependency NEVRA to use to fill in the modules and packages

Returns

A new Recipe object

Return type

Recipe

property group_names

Return the names of the groups. Groups do not have versions.

property module_names

Return the names of the modules

property module_nver

Return the names and version globs of the modules

property package_names

Return the names of the packages

property package_nver

Return the names and version globs of the packages

toml()

Return the Recipe in TOML format

exception pylorax.api.recipes.RecipeError

Bases: Exception

exception pylorax.api.recipes.RecipeFileError

Bases: Exception

class pylorax.api.recipes.RecipeGit(rpmname, rpmversion, rpmrelease, summary, repo, ref, destination)

Bases: dict

class pylorax.api.recipes.RecipeGroup(name)

Bases: dict

class pylorax.api.recipes.RecipeModule(name, version)

Bases: dict

class pylorax.api.recipes.RecipePackage(name, version)

Bases: pylorax.api.recipes.RecipeModule

pylorax.api.recipes.check_list_case(expected_keys, recipe_keys, prefix='')

Check the case of the recipe keys

Parameters

• expected_keys (list of str) -- A list of expected key strings

• recipe_keys (list of str) -- A list of the recipe's key strings

Returns

list of errors

Return type

list of str

pylorax.api.recipes.check_recipe_dict(recipe_dict)

Check a dict before using it to create a new Recipe

Parameters

recipe_dict (dict) -- A plain dict of the recipe

Returns

True if dict is ok

Return type

bool

Raises

RecipeError

This checks a dict to make sure required fields are present, that optional fields are correct, and that other optional fields are of the correct format, when included.

This collects all of the errors and returns a single RecipeError with a string that can be presented to users.

pylorax.api.recipes.check_required_list(lst, fields)

Check a list of dicts for required fields

Parameters

• lst (list of dict) -- A list of dicts with fields

• fields (list of str) -- A list of field name strings

Returns

A list of error strings

Return type

list of str

pylorax.api.recipes.commit_recipe(repo, branch, recipe)

Commit a recipe to a branch

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe (Recipe) -- Recipe to commit

Returns

OId of the new commit

Return type

Git.OId

Raises

Can raise errors from Ggit

pylorax.api.recipes.commit_recipe_directory(repo, branch, directory)

Commit all *.toml files from a directory, if they aren't already in git.

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• directory (str) -- The directory of *.toml recipes to commit

Returns

None

Raises

Can raise errors from Ggit or RecipeFileError

Files with Toml or RecipeFileErrors will be skipped, and the remainder will be tried.

pylorax.api.recipes.commit_recipe_file(repo, branch, filename)

Commit a recipe file to a branch

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- Path to the recipe file to commit

Returns

OId of the new commit

Return type

Git.OId

Raises

Can raise errors from Ggit or RecipeFileError

pylorax.api.recipes.customizations_diff(old_recipe, new_recipe)

Diff the customizations sections from two versions of a recipe

pylorax.api.recipes.delete_file(repo, branch, filename)

Delete a file from a branch.

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- filename to delete

Returns

OId of the new commit

Return type

Git.OId

Raises

Can raise errors from Ggit

pylorax.api.recipes.delete_recipe(repo, branch, recipe_name)

Delete a recipe from a branch.

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe_name (str) -- Recipe name to delete

Returns

OId of the new commit

Return type

Git.OId

Raises

Can raise errors from Ggit

pylorax.api.recipes.diff_lists(title, field, old_items, new_items)

Return the differences between two lists of dicts.

Parameters

• title (str) -- Title of the entry

• field (str) -- Field to use as the key for comparisons

• old_items (list(dict)) -- List of item dicts with "name" field

• new_items (list(dict)) -- List of item dicts with "name" field

Returns

List of diff dicts with old/new entries

Return type

list(dict)

pylorax.api.recipes.find_commit_tag(repo, branch, filename, commit_id)

Find the tag that matches the commit_id

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- filename to revert

• commit_id (Git.OId) -- The commit id to check

Returns

The tag or None if there isn't one

Return type

str or None

There should be only 1 tag pointing to a commit, but there may not be a tag at all.

The tag will look like: 'refs/tags/<branch>/<filename>/r<revision>'

pylorax.api.recipes.find_field_value(field, value, lst)

Find a field matching value in the list of dicts.

Parameters

• field (str) -- field to search for

• value (str) -- value to match in the field

• lst (list of dict) -- List of dict's with field

Returns

First dict with matching field:value, or None

Return type

dict or None

Used to return a specific entry from a list that looks like this:

[{"name": "one", "attr": "green"}, ...]

find_field_value("name", "one", lst) will return the matching dict.

pylorax.api.recipes.find_name(name, lst)

Find the dict matching the name in a list and return it.

Parameters

• name (str) -- Name to search for

• lst (list of dict) -- List of dict's with "name" field

Returns

First dict with matching name, or None

Return type

dict or None

This is just a wrapper for find_field_value with field set to "name"

pylorax.api.recipes.find_recipe_obj(path, recipe, default=None)

Find a recipe object

Parameters

• path (list of str) -- A list of dict field names

• recipe (Recipe) -- The recipe to search

• default (Any) -- The value to return if it is not found

Return the object found by applying the path to the dicts in the recipe, or return the default if it doesn't exist.

eg. {"customizations": {"hostname": "foo", "users": [...]}}

find_recipe_obj(["customizations", "hostname"], recipe, "")

pylorax.api.recipes.get_commit_details(commit, revision=None)

Return the details about a specific commit.

Parameters

• commit (Git.Commit) -- The commit to get details from

• revision (int) -- Optional commit revision

Returns

Details about the commit

Return type

CommitDetails

Raises

CommitTimeValError or Ggit exceptions

pylorax.api.recipes.get_revision_from_tag(tag)

Return the revision number from a tag

Parameters

tag (str) -- The tag to exract the revision from

Returns

The integer revision or None

Return type

int or None

The revision is the part after the r in 'branch/filename/rXXX'

pylorax.api.recipes.gfile(path)

Convert a string path to GFile for use with Git

pylorax.api.recipes.head_commit(repo, branch)

Get the branch's HEAD Commit Object

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

Returns

Branch's head commit

Return type

Git.Commit

Raises

Can raise errors from Ggit

pylorax.api.recipes.is_commit_tag(repo, commit_id, tag)

Check to see if a tag points to a specific commit.

Parameters

• repo (Git.Repository) -- Open repository

• commit_id (Git.OId) -- The commit id to check

• tag (str) -- The tag to check

Returns

True if the tag points to the commit, False otherwise

Return type

bool

pylorax.api.recipes.is_parent_diff(repo, filename, tree, parent)

Check to see if the commit is different from its parents

Parameters

• repo (Git.Repository) -- Open repository

• filename (str) -- filename to revert

• tree (Git.Tree) -- The commit's tree

• parent (Git.Commit) -- The commit's parent commit

Retuns

True if filename in the commit is different from its parents

Return type

bool

pylorax.api.recipes.list_branch_files(repo, branch)

Return a sorted list of the files on the branch HEAD

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

Returns

A sorted list of the filenames

Return type

list(str)

Raises

Can raise errors from Ggit

pylorax.api.recipes.list_commit_files(repo, commit)

Return a sorted list of the files on a commit

Parameters

• repo (Git.Repository) -- Open repository

• commit (str) -- The commit hash to list

Returns

A sorted list of the filenames

Return type

list(str)

Raises

Can raise errors from Ggit

pylorax.api.recipes.list_commits(repo, branch, filename, limit=0)

List the commit history of a file on a branch.

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- filename to revert

• limit (int) -- Number of commits to return (0=all)

Returns

A list of commit details

Return type

list(CommitDetails)

Raises

Can raise errors from Ggit

pylorax.api.recipes.open_or_create_repo(path)

Open an existing repo, or create a new one

Parameters

path (string) -- path to recipe directory

Returns

A repository object

Return type

Git.Repository

Raises

Can raise errors from Ggit

A bare git repo will be created in the git directory of the specified path. If a repo already exists it will be opened and returned instead of creating a new one.

pylorax.api.recipes.prepare_commit(repo, branch, builder)

Prepare for a commit

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• builder (TreeBuilder) -- instance of TreeBuilder

Returns

(Tree, Sig, Ref)

Return type

tuple

Raises

Can raise errors from Ggit

pylorax.api.recipes.read_commit(repo, branch, filename, commit=None)

Return the contents of a file on a specific branch or commit.

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- filename to read

• commit (str) -- Optional commit hash

Returns

The commit id, and the contents of the commit

Return type

tuple(str, str)

Raises

Can raise errors from Ggit

If no commit is passed the master:filename is returned, otherwise it will be commit:filename

pylorax.api.recipes.read_commit_spec(repo, spec)

Return the raw content of the blob specified by the spec

Parameters

• repo (Git.Repository) -- Open repository

• spec (str) -- Git revparse spec

Returns

Contents of the commit

Return type

str

Raises

Can raise errors from Ggit

eg. To read the README file from master the spec is "master:README"

pylorax.api.recipes.read_recipe_and_id(repo, branch, recipe_name, commit=None)

Read a recipe commit and its id from git

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe_name (str) -- Recipe name to read

• commit (str) -- Optional commit hash

Returns

The commit id, and a Recipe object

Return type

tuple(str, Recipe)

Raises

Can raise errors from Ggit

If no commit is passed the master:filename is returned, otherwise it will be commit:filename

pylorax.api.recipes.read_recipe_commit(repo, branch, recipe_name, commit=None)

Read a recipe commit from git and return a Recipe object

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe_name (str) -- Recipe name to read

• commit (str) -- Optional commit hash

Returns

A Recipe object

Return type

Recipe

Raises

Can raise errors from Ggit

If no commit is passed the master:filename is returned, otherwise it will be commit:filename

pylorax.api.recipes.recipe_diff(old_recipe, new_recipe)

Diff two versions of a recipe

Parameters

• old_recipe (Recipe) -- The old version of the recipe

• new_recipe (Recipe) -- The new version of the recipe

Returns

A list of diff dict entries with old/new

Return type

list(dict)

pylorax.api.recipes.recipe_filename(name)

Return the toml filename for a recipe

Replaces spaces with '-' and appends '.toml'

pylorax.api.recipes.recipe_from_dict(recipe_dict)

Create a Recipe object from a plain dict.

Parameters

recipe_dict (dict) -- A plain dict of the recipe

Returns

A Recipe object

Return type

Recipe

Raises

RecipeError

pylorax.api.recipes.recipe_from_file(recipe_path)

Return a recipe file as a Recipe object

Parameters

recipe_path (str) -- Path to the recipe fila

Returns

A Recipe object

Return type

Recipe

pylorax.api.recipes.recipe_from_toml(recipe_str)

Create a Recipe object from a toml string.

Parameters

recipe_str (str) -- The Recipe TOML string

Returns

A Recipe object

Return type

Recipe

Raises

TomlError

pylorax.api.recipes.repo_file_exists(repo, branch, filename)

Return True if the filename exists on the branch

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- Filename to check

Returns

True if the filename exists on the HEAD of the branch, False otherwise.

Return type

bool

pylorax.api.recipes.revert_file(repo, branch, filename, commit)

Revert the contents of a file to that of a previous commit

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- filename to revert

• commit (str) -- Commit hash

Returns

OId of the new commit

Return type

Git.OId

Raises

Can raise errors from Ggit

pylorax.api.recipes.revert_recipe(repo, branch, recipe_name, commit)

Revert the contents of a recipe to that of a previous commit

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe_name (str) -- Recipe name to revert

• commit (str) -- Commit hash

Returns

OId of the new commit

Return type

Git.OId

Raises

Can raise errors from Ggit

pylorax.api.recipes.tag_file_commit(repo, branch, filename)

Tag a file's most recent commit

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- Filename to tag

Returns

Tag id or None if it failed.

Return type

Git.OId

Raises

Can raise errors from Ggit

This uses git tags, of the form refs/tags/<branch>/<filename>/r<revision> Only the most recent recipe commit can be tagged to prevent out of order tagging. Revisions start at 1 and increment for each new commit that is tagged. If the commit has already been tagged it will return false.

pylorax.api.recipes.tag_recipe_commit(repo, branch, recipe_name)

Tag a file's most recent commit

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe_name (str) -- Recipe name to tag

Returns

Tag id or None if it failed.

Return type

Git.OId

Raises

Can raise errors from Ggit

Uses tag_file_commit()

pylorax.api.recipes.write_commit(repo, branch, filename, message, content)

Make a new commit to a repository's branch

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• filename (str) -- full path of the file to add

• message (str) -- The commit message

• content (str) -- The data to write

Returns

OId of the new commit

Return type

Git.OId

Raises

Can raise errors from Ggit

pylorax.api.regexes module

pylorax.api.server module

class pylorax.api.server.GitLock(repo, lock, dir)

Bases: tuple

property dir

Alias for field number 2

property lock

Alias for field number 1

property repo

Alias for field number 0

pylorax.api.timestamp module

pylorax.api.timestamp.timestamp_dict(destdir)

pylorax.api.timestamp.write_timestamp(destdir, ty)

pylorax.api.toml module

exception pylorax.api.toml.TomlError(msg, doc, pos)

Bases: toml.decoder.TomlDecodeError

pylorax.api.toml.dump(o, file)

pylorax.api.toml.dumps(o)

pylorax.api.toml.load(file)

pylorax.api.toml.loads(s)

pylorax.api.utils module

API utility functions

pylorax.api.utils.blueprint_exists(api, branch, blueprint_name)

Return True if the blueprint exists

Parameters

• api (Flask) -- flask object

• branch (str) -- Branch name

• recipe_name (str) -- Recipe name to read

pylorax.api.utils.take_limits(iterable, offset, limit)

Apply offset and limit to an iterable object

Parameters

• iterable (iter) -- The object to limit

• offset (int) -- The number of items to skip

• limit (int) -- The total number of items to return

Returns

A subset of the iterable

pylorax.api.v0 module

Setup v0 of the API server

v0_api() must be called to setup the API routes for Flask

Status Responses

Some requests only return a status/error response.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

Example response:

{
  "status": true
}

Error response:

{
  "errors": ["ggit-error: Failed to remove entry. File isn't in the tree - jboss.toml (-1)"]
  "status": false
}

API Routes

All of the blueprints routes support the optional branch argument. If it is not used then the API will use the master branch for blueprints. If you want to create a new branch use the new or workspace routes with ?branch=<branch-name> to store the new blueprint on the new branch.

pylorax.api.v0.v0_blueprints_changes(blueprint_names)

Return the changes to a blueprint or list of blueprints

/api/v0/blueprints/changes/<blueprint_names>[?offset=0&limit=20]

Return the commits to a blueprint. By default it returns the first 20 commits, this can be changed by passing offset and/or limit. The response will include the commit hash, summary, timestamp, and optionally the revision number. The commit hash can be passed to /api/v0/blueprints/diff/ to retrieve the exact changes.

Example:

{
  "errors": [],
  "limit": 20,
  "offset": 0,
  "blueprints": [
    {
      "changes": [
        {
          "commit": "e083921a7ed1cf2eec91ad12b9ad1e70ef3470be",
          "message": "blueprint glusterfs, version 0.0.6 saved.",
          "revision": null,
          "timestamp": "2017-11-23T00:18:13Z"
        },
        {
          "commit": "cee5f4c20fc33ea4d54bfecf56f4ad41ad15f4f3",
          "message": "blueprint glusterfs, version 0.0.5 saved.",
          "revision": null,
          "timestamp": "2017-11-11T01:00:28Z"
        },
        {
          "commit": "29b492f26ed35d80800b536623bafc51e2f0eff2",
          "message": "blueprint glusterfs, version 0.0.4 saved.",
          "revision": null,
          "timestamp": "2017-11-11T00:28:30Z"
        },
        {
          "commit": "03374adbf080fe34f5c6c29f2e49cc2b86958bf2",
          "message": "blueprint glusterfs, version 0.0.3 saved.",
          "revision": null,
          "timestamp": "2017-11-10T23:15:52Z"
        },
        {
          "commit": "0e08ecbb708675bfabc82952599a1712a843779d",
          "message": "blueprint glusterfs, version 0.0.2 saved.",
          "revision": null,
          "timestamp": "2017-11-10T23:14:56Z"
        },
        {
          "commit": "3e11eb87a63d289662cba4b1804a0947a6843379",
          "message": "blueprint glusterfs, version 0.0.1 saved.",
          "revision": null,
          "timestamp": "2017-11-08T00:02:47Z"
        }
      ],
      "name": "glusterfs",
      "total": 6
    }
  ]
}

pylorax.api.v0.v0_blueprints_delete(blueprint_name)

Delete a blueprint from git

DELETE /api/v0/blueprints/delete/<blueprint_name>

Delete a blueprint. The blueprint is deleted from the branch, and will no longer be listed by the list route. A blueprint can be undeleted using the undo route to revert to a previous commit. This will also delete the workspace copy of the blueprint.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

pylorax.api.v0.v0_blueprints_delete_workspace(blueprint_name)

Delete a blueprint from the workspace

DELETE /api/v0/blueprints/workspace/<blueprint_name>

Remove the temporary workspace copy of a blueprint. The info route will now return the most recent commit of the blueprint. Any changes that were in the workspace will be lost.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

pylorax.api.v0.v0_blueprints_depsolve(blueprint_names)

Return the dependencies for a blueprint

/api/v0/blueprints/depsolve/<blueprint_names>

Depsolve the blueprint using yum, return the blueprint used, and the NEVRAs of the packages chosen to satisfy the blueprint's requirements. The response will include a list of results, with the full dependency list in dependencies, the NEVRAs for the blueprint's direct modules and packages in modules, and any error will be in errors.

Example:

{
  "errors": [],
  "blueprints": [
    {
      "dependencies": [
        {
          "arch": "noarch",
          "epoch": "0",
          "name": "2ping",
          "release": "2.el7",
          "version": "3.2.1"
        },
        {
          "arch": "x86_64",
          "epoch": "0",
          "name": "acl",
          "release": "12.el7",
          "version": "2.2.51"
        },
        {
          "arch": "x86_64",
          "epoch": "0",
          "name": "audit-libs",
          "release": "3.el7",
          "version": "2.7.6"
        },
        {
          "arch": "x86_64",
          "epoch": "0",
          "name": "avahi-libs",
          "release": "17.el7",
          "version": "0.6.31"
        },
        ...
      ],
      "modules": [
        {
          "arch": "noarch",
          "epoch": "0",
          "name": "2ping",
          "release": "2.el7",
          "version": "3.2.1"
        },
        {
          "arch": "x86_64",
          "epoch": "0",
          "name": "glusterfs",
          "release": "18.4.el7",
          "version": "3.8.4"
        },
        ...
      ],
      "blueprint": {
        "description": "An example GlusterFS server with samba",
        "modules": [
          {
            "name": "glusterfs",
            "version": "3.7.*"
          },
       ...
      }
    }
  ]
}

pylorax.api.v0.v0_blueprints_diff(blueprint_name, from_commit, to_commit)

Return the differences between two commits of a blueprint

/api/v0/blueprints/diff/<blueprint_name>/<from_commit>/<to_commit>

Return the differences between two commits, or the workspace. The commit hash from the changes response can be used here, or several special strings:

• NEWEST will select the newest git commit. This works for from_commit or to_commit

• WORKSPACE will select the workspace copy. This can only be used in to_commit

eg. /api/v0/blueprints/diff/glusterfs/NEWEST/WORKSPACE will return the differences between the most recent git commit and the contents of the workspace.

Each entry in the response's diff object contains the old blueprint value and the new one. If old is null and new is set, then it was added. If new is null and old is set, then it was removed. If both are set, then it was changed.

The old/new entries will have the name of the blueprint field that was changed. This can be one of: Name, Description, Version, Module, or Package. The contents for these will be the old/new values for them.

In the example below the version was changed and the ping package was added.

Example:

{
  "diff": [
    {
      "new": {
        "Version": "0.0.6"
      },
      "old": {
        "Version": "0.0.5"
      }
    },
    {
      "new": {
        "Package": {
          "name": "ping",
          "version": "3.2.1"
        }
      },
      "old": null
    }
  ]
}

pylorax.api.v0.v0_blueprints_freeze(blueprint_names)

Return the blueprint with the exact modules and packages selected by depsolve

/api/v0/blueprints/freeze/<blueprint_names>

Return a JSON representation of the blueprint with the package and module versions set to the exact versions chosen by depsolving the blueprint.

Example:

{
  "errors": [],
  "blueprints": [
    {
      "blueprint": {
        "description": "An example GlusterFS server with samba",
        "modules": [
          {
            "name": "glusterfs",
            "version": "3.8.4-18.4.el7.x86_64"
          },
          {
            "name": "glusterfs-cli",
            "version": "3.8.4-18.4.el7.x86_64"
          }
        ],
        "name": "glusterfs",
        "packages": [
          {
            "name": "ping",
            "version": "2:3.2.1-2.el7.noarch"
          },
          {
            "name": "samba",
            "version": "4.6.2-8.el7.x86_64"
          }
        ],
        "version": "0.0.6"
      }
    }
  ]
}

pylorax.api.v0.v0_blueprints_info(blueprint_names)

Return the contents of the blueprint, or a list of blueprints

/api/v0/blueprints/info/<blueprint_names>[?format=<json|toml>]

Return the JSON representation of the blueprint. This includes 3 top level objects. changes which lists whether or not the workspace is different from the most recent commit. blueprints which lists the JSON representation of the blueprint, and errors which will list any errors, like non-existant blueprints.

By default the response is JSON, but if ?format=toml is included in the URL's arguments it will return the response as the blueprint's raw TOML content. Unless there is an error which will only return a 400 and a standard error Status Responses.

If there is an error when JSON is requested the successful blueprints and the errors will both be returned.

Example of json response:

{
  "changes": [
    {
      "changed": false,
      "name": "glusterfs"
    }
  ],
  "errors": [],
  "blueprints": [
    {
      "description": "An example GlusterFS server with samba",
      "modules": [
        {
          "name": "glusterfs",
          "version": "3.7.*"
        },
        {
          "name": "glusterfs-cli",
          "version": "3.7.*"
        }
      ],
      "name": "glusterfs",
      "packages": [
        {
          "name": "2ping",
          "version": "3.2.1"
        },
        {
          "name": "samba",
          "version": "4.2.*"
        }
      ],
      "version": "0.0.6"
    }
  ]
}

Error example:

{
  "changes": [],
  "errors": ["ggit-error: the path 'missing.toml' does not exist in the given tree (-3)"]
  "blueprints": []
}

pylorax.api.v0.v0_blueprints_list()

List the available blueprints on a branch.

/api/v0/blueprints/list

List the available blueprints:

{ "limit": 20,
  "offset": 0,
  "blueprints": [
    "atlas",
    "development",
    "glusterfs",
    "http-server",
    "jboss",
    "kubernetes" ],
  "total": 6 }

pylorax.api.v0.v0_blueprints_new()

Commit a new blueprint

POST /api/v0/blueprints/new

Create a new blueprint, or update an existing blueprint. This supports both JSON and TOML for the blueprint format. The blueprint should be in the body of the request with the Content-Type header set to either application/json or text/x-toml.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

pylorax.api.v0.v0_blueprints_tag(blueprint_name)

Tag a blueprint's latest blueprint commit as a 'revision'

POST /api/v0/blueprints/tag/<blueprint_name>

Tag a blueprint as a new release. This uses git tags with a special format. refs/tags/<branch>/<filename>/r<revision>. Only the most recent blueprint commit can be tagged. Revisions start at 1 and increment for each new tag (per-blueprint). If the commit has already been tagged it will return false.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

pylorax.api.v0.v0_blueprints_undo(blueprint_name, commit)

Undo changes to a blueprint by reverting to a previous commit.

POST /api/v0/blueprints/undo/<blueprint_name>/<commit>

This will revert the blueprint to a previous commit. The commit hash from the changes route can be used in this request.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

pylorax.api.v0.v0_blueprints_workspace()

Write a blueprint to the workspace

POST /api/v0/blueprints/workspace

Write a blueprint to the temporary workspace. This works exactly the same as new except that it does not create a commit. JSON and TOML bodies are supported.

The workspace is meant to be used as a temporary blueprint storage for clients. It will be read by the info and diff routes if it is different from the most recent commit.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

pylorax.api.v0.v0_compose_cancel(uuid)

Cancel a running compose and delete its results directory

DELETE /api/v0/compose/cancel/<uuid>

Cancel the build, if it is not finished, and delete the results. It will return a status of True if it is successful.

Example:

{
  "status": true,
  "uuid": "03397f8d-acff-4cdb-bd31-f629b7a948f5"
}

pylorax.api.v0.v0_compose_delete(uuids)

Delete the compose results for the listed uuids

DELETE /api/v0/compose/delete/<uuids>

Delete the list of comma-separated uuids from the compose results.

Example:

{
  "errors": [],
  "uuids": [
    {
      "status": true,
      "uuid": "ae1bf7e3-7f16-4c9f-b36e-3726a1093fd0"
    }
  ]
}

pylorax.api.v0.v0_compose_failed()

Return the list of failed composes

/api/v0/compose/failed

Return the details on all of the failed composes on the system.

Example:

{
  "failed": [
     {
      "id": "8c8435ef-d6bd-4c68-9bf1-a2ef832e6b1a",
      "blueprint": "http-server",
      "queue_status": "FAILED",
      "job_created": 1517523249.9301329,
      "job_started": 1517523249.9314211,
      "job_finished": 1517523255.5623411,
      "version": "0.0.2"
    }
  ]
}

pylorax.api.v0.v0_compose_finished()

Return the list of finished composes

/api/v0/compose/finished

Return the details on all of the finished composes on the system.

Example:

{
  "finished": [
    {
      "id": "70b84195-9817-4b8a-af92-45e380f39894",
      "blueprint": "glusterfs",
      "queue_status": "FINISHED",
      "job_created": 1517351003.8210032,
      "job_started": 1517351003.8230415,
      "job_finished": 1517359234.1003145,
      "version": "0.0.6"
    },
    {
      "id": "e695affd-397f-4af9-9022-add2636e7459",
      "blueprint": "glusterfs",
      "queue_status": "FINISHED",
      "job_created": 1517362289.7193348,
      "job_started": 1517362289.9751132,
      "job_finished": 1517363500.1234567,
      "version": "0.0.6"
    }
  ]
}

pylorax.api.v0.v0_compose_image(uuid)

Return the output image for the build

/api/v0/compose/image/<uuid>

Returns the output image from the build. The filename is set to the filename from the build with the UUID as a prefix. eg. UUID-root.tar.xz or UUID-boot.iso.

pylorax.api.v0.v0_compose_info(uuid)

Return detailed info about a compose

/api/v0/compose/info/<uuid>

Get detailed information about the compose. The returned JSON string will contain the following information:

• id - The uuid of the comoposition

• config - containing the configuration settings used to run Anaconda

• blueprint - The depsolved blueprint used to generate the kickstart

• commit - The (local) git commit hash for the blueprint used

• deps - The NEVRA of all of the dependencies used in the composition

• compose_type - The type of output generated (tar, iso, etc.)

• queue_status - The final status of the composition (FINISHED or FAILED)

Example:

{
  "commit": "7078e521a54b12eae31c3fd028680da7a0815a4d",
  "compose_type": "tar",
  "config": {
    "anaconda_args": "",
    "armplatform": "",
    "compress_args": [],
    "compression": "xz",
    "image_name": "root.tar.xz",
    ...
  },
  "deps": {
    "packages": [
      {
        "arch": "x86_64",
        "epoch": "0",
        "name": "acl",
        "release": "14.el7",
        "version": "2.2.51"
      }
    ]
  },
  "id": "c30b7d80-523b-4a23-ad52-61b799739ce8",
  "queue_status": "FINISHED",
  "blueprint": {
    "description": "An example kubernetes master",
    ...
  }
}

pylorax.api.v0.v0_compose_log_tail(uuid)

Return the tail of the most currently relevant log

/api/v0/compose/log/<uuid>[?size=KiB]

Returns the end of either the anaconda log, the packaging log, or the composer logs, depending on the progress of the compose. The size parameter is optional and defaults to 1 MiB if it is not included. The returned data is raw text from the end of the log file, starting on a line boundary.

Example:

12:59:24,222 INFO anaconda: Running Thread: AnaConfigurationThread (140629395244800)
12:59:24,223 INFO anaconda: Configuring installed system
12:59:24,912 INFO anaconda: Configuring installed system
12:59:24,912 INFO anaconda: Creating users
12:59:24,913 INFO anaconda: Clearing libuser.conf at /tmp/libuser.Dyy8Gj
12:59:25,154 INFO anaconda: Creating users
12:59:25,155 INFO anaconda: Configuring addons
12:59:25,155 INFO anaconda: Configuring addons
12:59:25,155 INFO anaconda: Generating initramfs
12:59:49,467 INFO anaconda: Generating initramfs
12:59:49,467 INFO anaconda: Running post-installation scripts
12:59:49,467 INFO anaconda: Running kickstart %%post script(s)
12:59:50,782 INFO anaconda: All kickstart %%post script(s) have been run
12:59:50,782 INFO anaconda: Running post-installation scripts
12:59:50,784 INFO anaconda: Thread Done: AnaConfigurationThread (140629395244800)

pylorax.api.v0.v0_compose_logs(uuid)

Return a tar of the metadata for the build

/api/v0/compose/logs/<uuid>

Returns a .tar of the anaconda build logs. The tar is not compressed, but is not large.

The mime type is set to 'application/x-tar' and the filename is set to UUID-logs.tar

pylorax.api.v0.v0_compose_metadata(uuid)

Return a tar of the metadata for the build

/api/v0/compose/metadata/<uuid>

Returns a .tar of the metadata used for the build. This includes all the information needed to reproduce the build, including the final kickstart populated with repository and package NEVRA.

The mime type is set to 'application/x-tar' and the filename is set to UUID-metadata.tar

The .tar is uncompressed, but is not large.

pylorax.api.v0.v0_compose_queue()

Return the status of the new and running queues

/api/v0/compose/queue

Return the status of the build queue. It includes information about the builds waiting, and the build that is running.

Example:

{
  "new": [
    {
      "id": "45502a6d-06e8-48a5-a215-2b4174b3614b",
      "blueprint": "glusterfs",
      "queue_status": "WAITING",
      "job_created": 1517362647.4570868,
      "version": "0.0.6"
    },
    {
      "id": "6d292bd0-bec7-4825-8d7d-41ef9c3e4b73",
      "blueprint": "kubernetes",
      "queue_status": "WAITING",
      "job_created": 1517362659.0034983,
      "version": "0.0.1"
    }
  ],
  "run": [
    {
      "id": "745712b2-96db-44c0-8014-fe925c35e795",
      "blueprint": "glusterfs",
      "queue_status": "RUNNING",
      "job_created": 1517362633.7965999,
      "job_started": 1517362633.8001345,
      "version": "0.0.6"
    }
  ]
}

pylorax.api.v0.v0_compose_results(uuid)

Return a tar of the metadata and the results for the build

/api/v0/compose/results/<uuid>

Returns a .tar of the metadata, logs, and output image of the build. This includes all the information needed to reproduce the build, including the final kickstart populated with repository and package NEVRA. The output image is already in compressed form so the returned tar is not compressed.

The mime type is set to 'application/x-tar' and the filename is set to UUID.tar

pylorax.api.v0.v0_compose_start()

Start a compose

The body of the post should have these fields:

blueprint_name - The blueprint name from /blueprints/list/ compose_type - The type of output to create, from /compose/types branch - Optional, defaults to master, selects the git branch to use for the blueprint.

POST /api/v0/compose

Start a compose. The content type should be 'application/json' and the body of the POST should look like this

Example:

{
  "blueprint_name": "http-server",
  "compose_type": "tar",
  "branch": "master"
}

Pass it the name of the blueprint, the type of output (from '/api/v0/compose/types'), and the blueprint branch to use. 'branch' is optional and will default to master. It will create a new build and add it to the queue. It returns the build uuid and a status if it succeeds

Example:

{
  "build_id": "e6fa6db4-9c81-4b70-870f-a697ca405cdf",
  "status": true
}

pylorax.api.v0.v0_compose_status(uuids)

Return the status of the listed uuids

/api/v0/compose/status/<uuids>[?blueprint=<blueprint_name>&status=<compose_status>&type=<compose_type>]

Return the details for each of the comma-separated list of uuids. A uuid of '*' will return details for all composes.

Example:

{
  "uuids": [
    {
      "id": "8c8435ef-d6bd-4c68-9bf1-a2ef832e6b1a",
      "blueprint": "http-server",
      "queue_status": "FINISHED",
      "job_created": 1517523644.2384307,
      "job_started": 1517523644.2551234,
      "job_finished": 1517523689.9864314,
      "version": "0.0.2"
    },
    {
      "id": "45502a6d-06e8-48a5-a215-2b4174b3614b",
      "blueprint": "glusterfs",
      "queue_status": "FINISHED",
      "job_created": 1517363442.188399,
      "job_started": 1517363442.325324,
      "job_finished": 1517363451.653621,
      "version": "0.0.6"
    }
  ]
}

pylorax.api.v0.v0_compose_types()

Return the list of enabled output types

(only enabled types are returned)

/api/v0/compose/types

Returns the list of supported output types that are valid for use with 'POST /api/v0/compose'

Example:

{
  "types": [
    {
      "enabled": true,
      "name": "tar"
    }
  ]
}

pylorax.api.v0.v0_modules_info(module_names)

Return detailed information about the listed modules

/api/v0/modules/info/<module_names>

Return the module's dependencies, and the information about the module.

Example:

{
  "modules": [
    {
      "dependencies": [
        {
          "arch": "noarch",
          "epoch": "0",
          "name": "basesystem",
          "release": "7.el7",
          "version": "10.0"
        },
        {
          "arch": "x86_64",
          "epoch": "0",
          "name": "bash",
          "release": "28.el7",
          "version": "4.2.46"
        },
        ...
      ],
      "description": "The GNU tar program saves ...",
      "homepage": "http://www.gnu.org/software/tar/",
      "name": "tar",
      "summary": "A GNU file archiving program",
      "upstream_vcs": "UPSTREAM_VCS"
    }
  ]
}

pylorax.api.v0.v0_modules_list(module_names=None)

List available modules, filtering by module_names

/api/v0/modules/list[?offset=0&limit=20]

Return a list of all of the available modules. This includes the name and the group_type, which is always "rpm" for lorax-composer. By default this returns the first 20 items. This can be changed by setting the offset and limit arguments.

Example:

{
  "limit": 20,
  "modules": [
    {
      "group_type": "rpm",
      "name": "0ad"
    },
    {
      "group_type": "rpm",
      "name": "0ad-data"
    },
    {
      "group_type": "rpm",
      "name": "0install"
    },
    {
      "group_type": "rpm",
      "name": "2048-cli"
    },
    ...
  ]
  "total": 21770
}

/api/v0/modules/list/<module_names>[?offset=0&limit=20]

Return the list of comma-separated modules. Output is the same as /modules/list

Example:

{
  "limit": 20,
  "modules": [
    {
      "group_type": "rpm",
      "name": "tar"
    }
  ],
  "offset": 0,
  "total": 1
}

pylorax.api.v0.v0_projects_depsolve(project_names)

Return detailed information about the listed projects

/api/v0/projects/depsolve/<project_names>

Depsolve the comma-separated list of projects and return the list of NEVRAs needed to satisfy the request.

Example:

{
  "projects": [
    {
      "arch": "noarch",
      "epoch": "0",
      "name": "basesystem",
      "release": "7.el7",
      "version": "10.0"
    },
    {
      "arch": "x86_64",
      "epoch": "0",
      "name": "bash",
      "release": "28.el7",
      "version": "4.2.46"
    },
    {
      "arch": "x86_64",
      "epoch": "0",
      "name": "filesystem",
      "release": "21.el7",
      "version": "3.2"
    },
    ...
  ]
}

pylorax.api.v0.v0_projects_info(project_names)

Return detailed information about the listed projects

/api/v0/projects/info/<project_names>

Return information about the comma-separated list of projects. It includes the description of the package along with the list of available builds.

Example:

{
  "projects": [
    {
      "builds": [
        {
          "arch": "x86_64",
          "build_config_ref": "BUILD_CONFIG_REF",
          "build_env_ref": "BUILD_ENV_REF",
          "build_time": "2017-03-01T08:39:23",
          "changelog": "- restore incremental backups correctly, files ...",
          "epoch": "2",
          "metadata": {},
          "release": "32.el7",
          "source": {
            "license": "GPLv3+",
            "metadata": {},
            "source_ref": "SOURCE_REF",
            "version": "1.26"
          }
        }
      ],
      "description": "The GNU tar program saves many ...",
      "homepage": "http://www.gnu.org/software/tar/",
      "name": "tar",
      "summary": "A GNU file archiving program",
      "upstream_vcs": "UPSTREAM_VCS"
    }
  ]
}

pylorax.api.v0.v0_projects_list()

List all of the available projects/packages

/api/v0/projects/list[?offset=0&limit=20]

List all of the available projects. By default this returns the first 20 items, but this can be changed by setting the offset and limit arguments.

Example:

{
  "limit": 20,
  "offset": 0,
  "projects": [
    {
      "description": "0 A.D. (pronounced "zero ey-dee") is a ...",
      "homepage": "http://play0ad.com",
      "name": "0ad",
      "summary": "Cross-Platform RTS Game of Ancient Warfare",
      "upstream_vcs": "UPSTREAM_VCS"
    },
    ...
  ],
  "total": 21770
}

pylorax.api.v0.v0_projects_source_delete(source_name)

Delete the named source and return a status response

DELETE /api/v0/projects/source/delete/<source-name>

Delete a user added source. This will fail if a system source is passed to it.

The response will be a status response with status set to true, or an error response with it set to false and an error message included.

pylorax.api.v0.v0_projects_source_info(source_names)

Return detailed info about the list of sources

/api/v0/projects/source/info/<source-names>

Return information about the comma-separated list of source names. Or all of the sources if '*' is passed. Note that general globbing is not supported, only '*'.

immutable system sources will have the "system" field set to true. User added sources will have it set to false. System sources cannot be changed or deleted.

Example:

{
  "errors": [],
  "sources": {
    "fedora": {
      "check_gpg": true,
      "check_ssl": true,
      "gpgkey_urls": [
        "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-28-x86_64"
      ],
      "name": "fedora",
      "proxy": "http://proxy.brianlane.com:8123",
      "system": true,
      "type": "yum-metalink",
      "url": "https://mirrors.fedoraproject.org/metalink?repo=fedora-28&arch=x86_64"
    }
  }
}

pylorax.api.v0.v0_projects_source_list()

Return the list of source names

/api/v0/projects/source/list

Return the list of repositories used for depsolving and installing packages.

Example:

{
  "sources": [
    "fedora",
    "fedora-cisco-openh264",
    "fedora-updates-testing",
    "fedora-updates"
  ]
}

pylorax.api.v0.v0_projects_source_new()

Add a new package source. Or change an existing one

POST /api/v0/projects/source/new

Add (or change) a source for use when depsolving blueprints and composing images.

The proxy and gpgkey_urls entries are optional. All of the others are required. The supported types for the urls are:

• yum-baseurl is a URL to a yum repository.

• yum-mirrorlist is a URL for a mirrorlist.

• yum-metalink is a URL for a metalink.

If check_ssl is true the https certificates must be valid. If they are self-signed you can either set this to false, or add your Certificate Authority to the host system.

If check_gpg is true the GPG key must either be installed on the host system, or gpgkey_urls should point to it.

You can edit an existing source (other than system sources), by doing a POST of the new version of the source. It will overwrite the previous one.

Example:

{
    "name": "custom-source-1",
    "url": "https://url/path/to/repository/",
    "type": "yum-baseurl",
    "check_ssl": true,
    "check_gpg": true,
    "gpgkey_urls": [
        "https://url/path/to/gpg-key"
    ]
}

pylorax.api.v1 module

Setup v1 of the API server

pylorax.api.v1.v1_compose_failed()

Return the list of failed composes

/api/v1/compose/failed

Return the details on all of the failed composes on the system.

Example:

{
  "failed": [
     {
      "id": "8c8435ef-d6bd-4c68-9bf1-a2ef832e6b1a",
      "blueprint": "http-server",
      "queue_status": "FAILED",
      "job_created": 1517523249.9301329,
      "job_started": 1517523249.9314211,
      "job_finished": 1517523255.5623411,
      "version": "0.0.2",
      "uploads": [
          {
              "creation_time": 1568150660.524401,
              "image_name": "http-server",
              "image_path": null,
              "provider_name": "azure",
              "settings": {
                  "client_id": "need",
                  "location": "need",
                  "resource_group": "group",
                  "secret": "need",
                  "storage_account_name": "need",
                  "storage_container": "need",
                  "subscription_id": "need",
                  "tenant": "need"
              },
              "status": "WAITING",
              "uuid": "21898dfd-9ac9-4e22-bb1d-7f12d0129e65"
          }
      ]
    }
  ]
}

pylorax.api.v1.v1_compose_finished()

Return the list of finished composes

/api/v1/compose/finished

Return the details on all of the finished composes on the system.

Example:

{
  "finished": [
    {
      "id": "70b84195-9817-4b8a-af92-45e380f39894",
      "blueprint": "glusterfs",
      "queue_status": "FINISHED",
      "job_created": 1517351003.8210032,
      "job_started": 1517351003.8230415,
      "job_finished": 1517359234.1003145,
      "version": "0.0.6"
    },
    {
      "id": "e695affd-397f-4af9-9022-add2636e7459",
      "blueprint": "glusterfs",
      "queue_status": "FINISHED",
      "job_created": 1517362289.7193348,
      "job_started": 1517362289.9751132,
      "job_finished": 1517363500.1234567,
      "version": "0.0.6",
      "uploads": [
          {
              "creation_time": 1568150660.524401,
              "image_name": "glusterfs server",
              "image_path": "/var/lib/lorax/composer/results/e695affd-397f-4af9-9022-add2636e7459/disk.vhd",
              "provider_name": "azure",
              "settings": {
                  "client_id": "need",
                  "location": "need",
                  "resource_group": "group",
                  "secret": "need",
                  "storage_account_name": "need",
                  "storage_container": "need",
                  "subscription_id": "need",
                  "tenant": "need"
              },
              "status": "WAITING",
              "uuid": "21898dfd-9ac9-4e22-bb1d-7f12d0129e65"
          }
      ]
    }
  ]
}

pylorax.api.v1.v1_compose_info(uuid)

Return detailed info about a compose

/api/v1/compose/info/<uuid>

Get detailed information about the compose. The returned JSON string will contain the following information:

• id - The uuid of the comoposition

• config - containing the configuration settings used to run Anaconda

• blueprint - The depsolved blueprint used to generate the kickstart

• commit - The (local) git commit hash for the blueprint used

• deps - The NEVRA of all of the dependencies used in the composition

• compose_type - The type of output generated (tar, iso, etc.)

• queue_status - The final status of the composition (FINISHED or FAILED)

Example:

{
  "commit": "7078e521a54b12eae31c3fd028680da7a0815a4d",
  "compose_type": "tar",
  "config": {
    "anaconda_args": "",
    "armplatform": "",
    "compress_args": [],
    "compression": "xz",
    "image_name": "root.tar.xz",
    ...
  },
  "deps": {
    "packages": [
      {
        "arch": "x86_64",
        "epoch": "0",
        "name": "acl",
        "release": "14.el7",
        "version": "2.2.51"
      }
    ]
  },
  "id": "c30b7d80-523b-4a23-ad52-61b799739ce8",
  "queue_status": "FINISHED",
  "blueprint": {
    "description": "An example kubernetes master",
    ...
  },
  "uploads": [
      {
          "creation_time": 1568150660.524401,
          "image_name": "glusterfs server",
          "image_path": "/var/lib/lorax/composer/results/c30b7d80-523b-4a23-ad52-61b799739ce8/disk.vhd",
          "provider_name": "azure",
          "settings": {
              "client_id": "need",
              "location": "need",
              "resource_group": "group",
              "secret": "need",
              "storage_account_name": "need",
              "storage_container": "need",
              "subscription_id": "need",
              "tenant": "need"
          },
          "status": "FAILED",
          "uuid": "21898dfd-9ac9-4e22-bb1d-7f12d0129e65"
      }
  ]
}

pylorax.api.v1.v1_compose_queue()

Return the status of the new and running queues

/api/v1/compose/queue

Return the status of the build queue. It includes information about the builds waiting, and the build that is running.

Example:

{
  "new": [
    {
      "id": "45502a6d-06e8-48a5-a215-2b4174b3614b",
      "blueprint": "glusterfs",
      "queue_status": "WAITING",
      "job_created": 1517362647.4570868,
      "version": "0.0.6"
    },
    {
      "id": "6d292bd0-bec7-4825-8d7d-41ef9c3e4b73",
      "blueprint": "kubernetes",
      "queue_status": "WAITING",
      "job_created": 1517362659.0034983,
      "version": "0.0.1"
    }
  ],
  "run": [
    {
      "id": "745712b2-96db-44c0-8014-fe925c35e795",
      "blueprint": "glusterfs",
      "queue_status": "RUNNING",
      "job_created": 1517362633.7965999,
      "job_started": 1517362633.8001345,
      "version": "0.0.6",
      "uploads": [
          {
              "creation_time": 1568150660.524401,
              "image_name": "glusterfs server",
              "image_path": null,
              "provider_name": "azure",
              "settings": {
                  "client_id": "need",
                  "location": "need",
                  "resource_group": "group",
                  "secret": "need",
                  "storage_account_name": "need",
                  "storage_container": "need",
                  "subscription_id": "need",
                  "tenant": "need"
              },
              "status": "WAITING",
              "uuid": "21898dfd-9ac9-4e22-bb1d-7f12d0129e65"
          }
      ]
    }
  ]
}

pylorax.api.v1.v1_compose_start()

Start a compose

The body of the post should have these fields:

blueprint_name - The blueprint name from /blueprints/list/ compose_type - The type of output to create, from /compose/types branch - Optional, defaults to master, selects the git branch to use for the blueprint.

POST /api/v1/compose

Start a compose. The content type should be 'application/json' and the body of the POST should look like this. The "upload" object is optional.

The upload object can specify either a pre-existing profile to use (as returned by /uploads/providers) or one-time use settings for the provider.

Example with upload profile:

{
  "blueprint_name": "http-server",
  "compose_type": "tar",
  "branch": "master",
  "upload": {
    "image_name": "My Image",
    "provider": "azure",
    "profile": "production-azure-settings"
  }
}

Example with upload settings:

{
  "blueprint_name": "http-server",
  "compose_type": "tar",
  "branch": "master",
  "upload": {
    "image_name": "My Image",
    "provider": "azure",
    "settings": {
      "resource_group": "SOMEBODY",
      "storage_account_name": "ONCE",
      "storage_container": "TOLD",
      "location": "ME",
      "subscription_id": "THE",
      "client_id": "WORLD",
      "secret": "IS",
      "tenant": "GONNA"
    }
  }
}

Pass it the name of the blueprint, the type of output (from '/api/v1/compose/types'), and the blueprint branch to use. 'branch' is optional and will default to master. It will create a new build and add it to the queue. It returns the build uuid and a status if it succeeds. If an "upload" is given, it will schedule an upload to run when the build finishes.

Example response:

{
  "build_id": "e6fa6db4-9c81-4b70-870f-a697ca405cdf",
  "upload_id": "572eb0d0-5348-4600-9666-14526ba628bb",
  "status": true
}

pylorax.api.v1.v1_compose_status(uuids)

Return the status of the listed uuids

/api/v1/compose/status/<uuids>[?blueprint=<blueprint_name>&status=<compose_status>&type=<compose_type>]

Return the details for each of the comma-separated list of uuids. A uuid of '*' will return details for all composes.

Example:

{
  "uuids": [
    {
      "id": "8c8435ef-d6bd-4c68-9bf1-a2ef832e6b1a",
      "blueprint": "http-server",
      "queue_status": "FINISHED",
      "job_created": 1517523644.2384307,
      "job_started": 1517523644.2551234,
      "job_finished": 1517523689.9864314,
      "version": "0.0.2"
    },
    {
      "id": "45502a6d-06e8-48a5-a215-2b4174b3614b",
      "blueprint": "glusterfs",
      "queue_status": "FINISHED",
      "job_created": 1517363442.188399,
      "job_started": 1517363442.325324,
      "job_finished": 1517363451.653621,
      "version": "0.0.6",
      "uploads": [
          {
              "creation_time": 1568150660.524401,
              "image_name": "glusterfs server",
              "image_path": null,
              "provider_name": "azure",
              "settings": {
                  "client_id": "need",
                  "location": "need",
                  "resource_group": "group",
                  "secret": "need",
                  "storage_account_name": "need",
                  "storage_container": "need",
                  "subscription_id": "need",
                  "tenant": "need"
              },
              "status": "WAITING",
              "uuid": "21898dfd-9ac9-4e22-bb1d-7f12d0129e65"
          }
      ]
    }
  ]
}

pylorax.api.v1.v1_compose_uploads_delete(upload_uuid)

Delete an upload and disassociate it from its compose

DELETE /api/v1/upload/delete/<upload_uuid>

Example response:

{
  "status": true,
  "upload_id": "572eb0d0-5348-4600-9666-14526ba628bb"
}

pylorax.api.v1.v1_compose_uploads_schedule(compose_uuid)

Schedule an upload of a compose to a given cloud provider

POST /api/v1/uploads/schedule/<compose_uuid>

The body can specify either a pre-existing profile to use (as returned by /uploads/providers) or one-time use settings for the provider.

Example with upload profile:

{
  "image_name": "My Image",
  "provider": "azure",
  "profile": "production-azure-settings"
}

Example with upload settings:

{
  "image_name": "My Image",
  "provider": "azure",
  "settings": {
    "resource_group": "SOMEBODY",
    "storage_account_name": "ONCE",
    "storage_container": "TOLD",
    "location": "ME",
    "subscription_id": "THE",
    "client_id": "WORLD",
    "secret": "IS",
    "tenant": "GONNA"
  }
}

Example response:

{
  "status": true,
  "upload_id": "572eb0d0-5348-4600-9666-14526ba628bb"
}

pylorax.api.v1.v1_projects_source_info(source_ids)

Return detailed info about the list of sources

/api/v1/projects/source/info/<source-ids>

Return information about the comma-separated list of source ids. Or all of the sources if '*' is passed. Note that general globbing is not supported, only '*'.

Immutable system sources will have the "system" field set to true. User added sources will have it set to false. System sources cannot be changed or deleted.

Example:

{
  "errors": [],
  "sources": {
    "fedora": {
      "check_gpg": true,
      "check_ssl": true,
      "gpgkey_urls": [
        "file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-28-x86_64"
      ],
      "id": "fedora",
      "name": "Fedora $releasever - $basearch",
      "proxy": "http://proxy.brianlane.com:8123",
      "system": true,
      "type": "yum-metalink",
      "url": "https://mirrors.fedoraproject.org/metalink?repo=fedora-28&arch=x86_64"
    }
  }
}

In v0 the name field was used for the id (a short name for the repo). In v1 name changed to id and name is now used for the longer descriptive name of the repository.

pylorax.api.v1.v1_projects_source_new()

Add a new package source. Or change an existing one

POST /api/v1/projects/source/new

Add (or change) a source for use when depsolving blueprints and composing images.

The proxy and gpgkey_urls entries are optional. All of the others are required. The supported types for the urls are:

• yum-baseurl is a URL to a yum repository.

• yum-mirrorlist is a URL for a mirrorlist.

• yum-metalink is a URL for a metalink.

If check_ssl is true the https certificates must be valid. If they are self-signed you can either set this to false, or add your Certificate Authority to the host system.

If check_gpg is true the GPG key must either be installed on the host system, or gpgkey_urls should point to it.

You can edit an existing source (other than system sources), by doing a POST of the new version of the source. It will overwrite the previous one.

Example:

{
    "id": "custom-source-1",
    "name": "Custom Package Source #1",
    "url": "https://url/path/to/repository/",
    "type": "yum-baseurl",
    "check_ssl": true,
    "check_gpg": true,
    "gpgkey_urls": [
        "https://url/path/to/gpg-key"
    ]
}

In v0 the name field was used for the id (a short name for the repo). In v1 name changed to id and name is now used for the longer descriptive name of the repository.

pylorax.api.v1.v1_providers_delete(provider_name, profile)

Delete a provider's profile settings

DELETE /api/v1/upload/providers/delete/<provider_name>/<profile>

Example response:

{
  "status": true
}

pylorax.api.v1.v1_providers_save()

Save provider settings as a profile for later use

POST /api/v1/upload/providers/save

Example request:

{
  "provider": "azure",
  "profile": "my-profile",
  "settings": {
    "resource_group": "SOMEBODY",
    "storage_account_name": "ONCE",
    "storage_container": "TOLD",
    "location": "ME",
    "subscription_id": "THE",
    "client_id": "WORLD",
    "secret": "IS",
    "tenant": "GONNA"
  }
}

Saving to an existing profile will overwrite it.

Example response:

{
  "status": true
}

pylorax.api.v1.v1_upload_cancel(upload_uuid)

Cancel an upload that is either queued or in progress

DELETE /api/v1/upload/cancel/<upload_uuid>

Example response:

{
  "status": true,
  "upload_id": "037a3d56-b421-43e9-9935-c98350c89996"
}

pylorax.api.v1.v1_upload_info(upload_uuid)

Returns information about a given upload

GET /api/v1/upload/info/<upload_uuid>

Example response:

{
  "status": true,
  "upload": {
    "creation_time": 1565620940.069004,
    "image_name": "My Image",
    "image_path": "/var/lib/lorax/composer/results/b6218e8f-0fa2-48ec-9394-f5c2918544c4/disk.vhd",
    "provider_name": "azure",
    "settings": {
      "resource_group": "SOMEBODY",
      "storage_account_name": "ONCE",
      "storage_container": "TOLD",
      "location": "ME",
      "subscription_id": "THE",
      "client_id": "WORLD",
      "secret": "IS",
      "tenant": "GONNA"
    },
    "status": "FAILED",
    "uuid": "b637c411-9d9d-4279-b067-6c8d38e3b211"
  }
}

pylorax.api.v1.v1_upload_log(upload_uuid)

Returns an upload's log

GET /api/v1/upload/log/<upload_uuid>

Example response:

{
  "status": true,
  "upload_id": "b637c411-9d9d-4279-b067-6c8d38e3b211",
  "log": "< PLAY [localhost] >..."
}

pylorax.api.v1.v1_upload_providers()

Return the information about all upload providers, including their display names, expected settings, and saved profiles. Refer to the resolve_provider function.

GET /api/v1/upload/providers

Example response:

{
  "providers": {
    "azure": {
      "display": "Azure",
      "profiles": {
        "default": {
          "client_id": "example",
          ...
        }
      },
      "settings-info": {
        "client_id": {
          "display": "Client ID",
          "placeholder": "",
          "regex": "",
          "type": "string"
        },
        ...
      },
      "supported_types": ["vhd"]
    },
    ...
  }
}

pylorax.api.v1.v1_upload_reset(upload_uuid)

Reset an upload so it can be attempted again

POST /api/v1/upload/reset/<upload_uuid>

Optionally pass in a new image name and/or new settings.

Example request:

{
  "image_name": "My renamed image",
  "settings": {
    "resource_group": "ROLL",
    "storage_account_name": "ME",
    "storage_container": "I",
    "location": "AIN'T",
    "subscription_id": "THE",
    "client_id": "SHARPEST",
    "secret": "TOOL",
    "tenant": "IN"
  }
}

Example response:

{
  "status": true,
  "upload_id": "c75d5d62-9d26-42fc-a8ef-18bb14679fc7"
}

pylorax.api.workspace module

pylorax.api.workspace.workspace_delete(repo, branch, recipe_name)

Delete the recipe from the workspace

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe_name (str) -- The name of the recipe

Returns

None

Raises

IO related errors

pylorax.api.workspace.workspace_dir(repo, branch)

Create the workspace's path from a Repository and branch

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

Returns

The path to the branch's workspace directory

Return type

str

pylorax.api.workspace.workspace_read(repo, branch, recipe_name)

Read a Recipe from the branch's workspace

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe_name (str) -- The name of the recipe

Returns

The workspace copy of the recipe, or None if it doesn't exist

Return type

Recipe or None

Raises

RecipeFileError

pylorax.api.workspace.workspace_write(repo, branch, recipe)

Write a recipe to the workspace

Parameters

• repo (Git.Repository) -- Open repository

• branch (str) -- Branch name

• recipe (Recipe) -- The recipe to write to the workspace

Returns

None

Raises

IO related errors

Module contents