178 lines
5.8 KiB
ReStructuredText
178 lines
5.8 KiB
ReStructuredText
Quick Start
|
|
===========
|
|
|
|
.. hint:: **Abstract**
|
|
|
|
This document describes how to start with KIWI, an OS appliance builder.
|
|
This description applies for version |version|.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Packages for the new KIWI version are provided at the `openSUSE
|
|
buildservice <http://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder>`__.
|
|
|
|
Add the repository with :command:`zypper ar` (see following code) and replace
|
|
the distribution placeholder. The best approach is to click on the
|
|
desired distribution from the build service link above and there follow
|
|
the **Go to download repository** link.
|
|
|
|
.. note:: Multipython packages
|
|
|
|
This version of KIWI is provided for python 2 and python 3 versions.
|
|
The following information is based on the installation of the
|
|
python3-kiwi package and applies also to the installation of the
|
|
python2-kiwi package.
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo zypper ar -f \
|
|
http://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder/<DIST>
|
|
$ sudo zypper in python3-kiwi
|
|
|
|
|
|
Compatibility
|
|
-------------
|
|
|
|
The legacy KIWI version can be installed and used together with the next
|
|
generation KIWI.
|
|
|
|
.. note:: Automatic Link Creation for :command:`kiwi` Command
|
|
|
|
Note the python3-kiwi package uses the alternatives mechanism to
|
|
setup a symbolic link named :command:`kiwi` to the real executable
|
|
named :command:`kiwi-ng`. If the link target :file:`/usr/bin/kiwi`
|
|
already exists on your system, the alternative setup will skip the
|
|
creation of the link target because it already exists.
|
|
|
|
From an appliance description perspective, both KIWI versions are fully
|
|
compatible. Users can build their appliances with both versions and the
|
|
same appliance description. If the appliance description uses features
|
|
the next generation KIWI does not provide, the build will fail with an
|
|
exception early. If the appliance description uses next generation
|
|
features like the selection of the initrd system, it's not possible to
|
|
build that with the legacy KIWI, unless the appliance description
|
|
properly encapsulates the differences into a profile.
|
|
|
|
The next generation KIWI also provides the `--compat` option and
|
|
the :command:`kiwicompat` tool to be able to use the same commandline
|
|
as provided with the legacy KIWI version.
|
|
|
|
Example Appliance Descriptions
|
|
------------------------------
|
|
|
|
For use with the next generation KIWI there is also a GitHub project
|
|
hosting example appliance descriptions. Users who need an example to
|
|
start with should checkout the project as follows:
|
|
|
|
.. code:: bash
|
|
|
|
$ git clone https://github.com/SUSE/kiwi-descriptions
|
|
|
|
Example Image Build on Host System
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Install python3-kiwi as explained above and build as follows:
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo kiwi-ng --type vmx system build \
|
|
--description kiwi-descriptions/suse/x86_64/suse-leap-42.1-JeOS \
|
|
--target-dir /tmp/myimage
|
|
|
|
Find the image with the suffix :file:`.raw` below :file:`/tmp/myimage`.
|
|
|
|
Example Image Build in Container
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Install `dice <https://github.com/SUSE/dice>`__ and build as follows:
|
|
|
|
.. code:: bash
|
|
|
|
$ dice build kiwi-descriptions/suse/x86_64/suse-leap-42.1-JeOS
|
|
$ dice status kiwi-descriptions/suse/x86_64/suse-leap-42.1-JeOS
|
|
|
|
Find the image in a tarball displayed by the :command:`status` command.
|
|
|
|
In order to run your image build, call :command:`qemu` as follows:
|
|
|
|
.. code:: bash
|
|
|
|
$ qemu -drive \
|
|
file=LimeJeOS-Leap-42.1.x86_64-1.42.1.raw,format=raw,if=virtio
|
|
|
|
Using KIWI NG from Build Service
|
|
--------------------------------
|
|
|
|
The next generation KIWI is fully integrated with the build service. As
|
|
an example you can find the integration testing system in the
|
|
buildservice project `Virtualization:Appliances:Images:Testing_<arch>` at:
|
|
|
|
https://build.opensuse.org
|
|
|
|
In order to use the next generation KIWI to build an appliance in the
|
|
build service it is only required to add the Builder project as
|
|
repository to the KIWI XML configuration like in the following example:
|
|
|
|
.. code:: xml
|
|
|
|
<repository type="rpm-md" alias="kiwi-next-generation">
|
|
<source path="obs://Virtualization:Appliances:Builder/Factory"/>
|
|
</repository>
|
|
|
|
The Builder project configuration in the build service is setup to prefer
|
|
the next generation KIWI over the legacy version. Thus adding the
|
|
Builder repository inherits this project setup and activates building
|
|
with the next generation KIWI.
|
|
|
|
Using KIWI NG in a Python Project
|
|
----------------------------------
|
|
|
|
KIWI NG can also function as a module for other Python projects.
|
|
The following example demonstrates how to read an existing image
|
|
description, add a new repository definition and export the
|
|
modified description on stdout.
|
|
|
|
.. code:: python
|
|
|
|
import sys
|
|
import logging
|
|
|
|
from kiwi.xml_description import XMLDescription
|
|
from kiwi.xml_state import XMLState
|
|
|
|
# Import of log handler only needed if default logging
|
|
# setup is not appropriate for the project
|
|
# from kiwi.logger import log
|
|
|
|
# By default the logging level is set to DEBUG, which
|
|
# can be changed by the following call
|
|
# log.setLogLevel(logging.INFO)
|
|
|
|
# Logging can also be disabled completely
|
|
# log.disabled = True
|
|
|
|
description = XMLDescription('path/to/kiwi/XML/config.xml')
|
|
|
|
xml_data = description.load()
|
|
|
|
xml_state = XMLState(
|
|
xml_data=xml_data, profiles=[], build_type='iso'
|
|
)
|
|
|
|
xml_state.add_repository(
|
|
repo_source='http://repo',
|
|
repo_type='rpm-md',
|
|
repo_alias='myrepo',
|
|
repo_prio=99
|
|
)
|
|
|
|
xml_data.export(
|
|
outfile=sys.stdout, level=0
|
|
)
|
|
|
|
All classes are written in a way to care for a single responsibility
|
|
in order to allow for re-use on other use cases. Therefore it is possible
|
|
to use KIWI NG outside of the main image building scope to manage e.g
|
|
the setup of loop devices, filesystems, partitions, etc...
|