Add documentation on building images

Mostly copy-pasted with small fixes from ironic-python-agent.

Change-Id: I8333a36f343991a888c6e9276ecae03aaf1941ae
This commit is contained in:
Dmitry Tantsur 2019-09-05 13:32:54 +02:00
parent 42862e0276
commit d9bc2b6ccc
6 changed files with 316 additions and 154 deletions

2
.gitignore vendored
View File

@ -51,3 +51,5 @@ ChangeLog
# Files created by releasenotes build # Files created by releasenotes build
releasenotes/build releasenotes/build
RELEASENOTES.rst
releasenotes/notes/reno.cache

103
doc/source/admin/dib.rst Normal file
View File

@ -0,0 +1,103 @@
diskimage-builder images
========================
Images built using diskimage-builder_ are recommended for production use on
real hardware.
Building
--------
... with the helper script
~~~~~~~~~~~~~~~~~~~~~~~~~~
To build an image using diskimage-builder_, run:
.. code-block:: shell
ironic-python-agent-builder <distribution, e.g. ubuntu>
You can add other diskimage-builder_ elements via the ``-e`` flag. For example,
dhcp-all-interfaces_ is required for automatic DHCP on some operating systems
(e.g. CentOS 7):
.. code-block:: shell
ironic-python-agent-builder -e dhcp-all-interfaces centos7
You can specify the base name of the target images:
.. code-block:: shell
ironic-python-agent-builder -o my-ipa -e dhcp-all-interfaces centos7
... with diskimage-builder
~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also use diskimage-builder_ directly. First you need to set the
``ELEMENTS_PATH`` variable to the correct location:
* If installed with ``pip install --user``, use:
.. code-block:: bash
export ELEMENTS_PATH=$HOME/.local/share/ironic-python-agent-builder/dib
* On Fedora/CentOS/RHEL (installed via ``sudo pip install`` or from packages):
.. code-block:: bash
export ELEMENTS_PATH=/usr/share/ironic-python-agent-builder/dib
* On Debian and its derivatives, if installed with ``sudo pip install``:
.. code-block:: bash
export ELEMENTS_PATH=/usr/local/share/ironic-python-agent-builder/dib
Now you can build an image adding the ``ironic-python-agent-ramdisk`` element,
for example:
.. code-block:: shell
disk-image-create -o ironic-python-agent \
ironic-python-agent-ramdisk centos7 dhcp-all-interfaces
To use a specific branch of ironic-python-agent, use:
.. code-block:: bash
export DIB_REPOREF_ironic_python_agent=origin/stable/queens
Advanced options
----------------
SSH access
~~~~~~~~~~
SSH access can be added to DIB built IPA images with the dynamic-login_
or the devuser_ element.
The *dynamic-login* element allows the operator to inject an SSH key at boot
time via the kernel command line parameters:
* Add ``sshkey="ssh-rsa <your public key here>"`` to ``pxe_append_params``
setting in the ``ironic.conf`` file. Disabling SELinux is required for
systems where it is enabled, it can be done with ``selinux=0``.
.. warning:: Quotation marks around the public key are important!
* Restart the ironic-conductor.
The *devuser* element allows creating a user at build time, for example:
.. code-block:: bash
export DIB_DEV_USER_USERNAME=username
export DIB_DEV_USER_PWDLESS_SUDO=yes
export DIB_DEV_USER_AUTHORIZED_KEYS=$HOME/.ssh/id_rsa.pub
disk-image-create debian ironic-python-agent-ramdisk devuser
.. _diskimage-builder: https://docs.openstack.org/diskimage-builder
.. _dhcp-all-interfaces: https://docs.openstack.org/diskimage-builder/latest/elements/dhcp-all-interfaces/README.html
.. _dynamic-login: https://docs.openstack.org/diskimage-builder/latest/elements/dynamic-login/README.html
.. _devuser: https://docs.openstack.org/diskimage-builder/latest/elements/devuser/README.html

View File

@ -2,15 +2,13 @@
Administrators guide Administrators guide
==================== ====================
This guide describes how to build an `Ironic Python Agent`_-based image using This guide describes how to build and use an `Ironic Python Agent`_-based image
the builders provided in the **ironic-python-agent-builder** project. using the builders provided in the **ironic-python-agent-builder** project.
diskimage-builder image .. toctree::
----------------------- :maxdepth: 2
To build an image using diskimage-builder_, run:: dib
tinyipa
ironic-python-agent-builder <distribution, e.g. ubuntu>
.. _Ironic Python Agent: https://docs.openstack.org/ironic-python-agent .. _Ironic Python Agent: https://docs.openstack.org/ironic-python-agent
.. _diskimage-builder: https://docs.openstack.org/diskimage-builder

View File

@ -0,0 +1,193 @@
TinyIPA images
==============
TinyIPA is an `Ironic Python Agent`_ image based on TinyCoreLinux_. It is very
lightweight and thus very suitable for CI use. It may lack necessary drivers
and the build process uses insecure communication, thus these images are not
recommended for production usage.
Requirements
------------
You need to have a git clone of **ironic-python-agent-builder**:
.. code-block:: shell
git clone https://opendev.org/openstack/ironic-python-agent-builder
cd ironic-python-agent-builder/tinyipa
Then you need to install some utilities. For the main build script:
* wget
* pip
* unzip
* sudo
* awk
* mksquashfs
For building an ISO you'll also need:
* genisoimage
Building
--------
Building ramdisk
~~~~~~~~~~~~~~~~
To create a new ramdisk, run:
.. code-block:: shell
make
or:
.. code-block:: shell
./build-tinyipa.sh && ./finalise-tinyipa.sh
This will create two new files once completed:
* ``tinyipa.vmlinuz`` - the kernel image
* ``tinyipa.gz`` - the initramfs image
Upload them to the Image service or another location where you want them to be
hosted (an HTTP or FILE location in case of standalone ironic).
Building ISO
~~~~~~~~~~~~
Once you've built tinyIPA it is possible to pack it into an ISO if required. To
create a bootable ISO, run:
.. code-block:: shell
make iso
or:
.. code-block:: shell
./build-iso.sh
This will create one new file once completed:
* ``tinyipa.iso``
Cleaning up
~~~~~~~~~~~
To clean up the whole build environment, run:
.. code-block:: shell
make clean
For cleaning up just the iso or just the ramdisk build:
.. code-block:: shell
make clean_iso
or:
.. code-block:: shell
make clean_build
Advanced options
----------------
(De)Optimizing the image
~~~~~~~~~~~~~~~~~~~~~~~~
If you want the build script to preinstall everything into the ramdisk,
instead of loading some things at runtime (this results in a slightly bigger
ramdisk), before running ``make`` or ``build-tinyipa.sh`` set:
.. code-block:: bash
export BUILD_AND_INSTALL_TINYIPA=true
By default, building tinyIPA will compile most of the Python code to
optimized ``*.pyo`` files, completely remove most of ``*.py`` and ``*.pyc``
files, and run ironic-python-agent with ``PYTHONOPTIMIZE=1``
to save space on the ramdisk. If instead you want a normal Python experience
inside the image, for example for debugging/hacking on IPA in a running
ramdisk, before running ``make`` or ``build-tinyipa.sh`` set:
.. code-block:: bash
export PYOPTIMIZE_TINYIPA=false
Enabling/disabling SSH access to the ramdisk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default tinyIPA will be built with OpenSSH server installed but no
public SSH keys authorized to access it.
If you want to enable SSH access to the image, set ``AUTHORIZE_SSH`` variable
in your shell before building tinyIPA:
.. code-block:: bash
export AUTHORIZE_SSH=true
By default it will use public RSA or DSA keys of the user running the build.
To provide a different public SSH key, export path to it in your shell before
building tinyIPA:
.. code-block:: bash
export SSH_PUBLIC_KEY=<full-path-to-public-key>
If you want to disable SSH altogether, set ``INSTALL_SSH`` variable in your
shell to ``false`` before building tinyIPA:
.. code-block:: bash
export INSTALL_SSH=false
If you want to change the SSH access of a previously built tinyIPA image,
use the make target ``addssh``:
.. code-block:: shell
make addssh
This command will either use a local image specified by the
``TINYIPA_RAMDISK_FILE`` environment variable or download the version
specified by the ``BRANCH_PATH`` environment variable (e.g. ``master`` or
``stable-queens``) from `tarballs.openstack.org
<https://tarballs.openstack.org/ironic-python-agent/tinyipa/files/>`_.
It will install and configure OpenSSH if needed and add public SSH keys for
the user named ``tc`` using either the same ``SSH_PUBLIC_KEY`` shell variable
or the public keys of the local user.
Enabling biosdevname in the ramdisk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to collect BIOS given names of NICs in the inventory, set
``TINYIPA_REQUIRE_BIOSDEVNAME`` variable in your shell before building tinyIPA:
.. code-block:: bash
export TINYIPA_REQUIRE_BIOSDEVNAME=true
Using ironic-lib from source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ironic-lib_ contains important parts of the provisioning logic. If you would
like to build an IPA image with your local checkout of ironic-lib_, export
the following variable:
.. code-block:: bash
export IRONIC_LIB_SOURCE=/absolute/path/to/ironic-lib/checkout
.. _Ironic Python Agent: https://docs.openstack.org/ironic-python-agent
.. _TinyCoreLinux: http://tinycorelinux.net
.. _ironic-lib: https://opendev.org/openstack/ironic-lib

View File

@ -2,9 +2,15 @@
Installing Ironic Python Agent Builder Installing Ironic Python Agent Builder
====================================== ======================================
Download the ``ironic-python-agent-builder`` package from Download the ``ironic-python-agent-builder`` archive from
`tarballs.openstack.org `tarballs.openstack.org`_, install it from your distribution's repositories
<https://tarballs.openstack.org/ironic-python-agent-builder/>`_, install it or use pip::
from your distribution's repositories or use pip::
pip install --user diskimage-builder ironic-python-agent-builder pip install --user diskimage-builder ironic-python-agent-builder
In RDO_, the package is available since Train under a slightly different name::
sudo yum install -y openstack-ironic-python-agent-builder
.. _tarballs.openstack.org: https://tarballs.openstack.org/ironic-python-agent-builder/
.. _RDO: https://rdoproject.org

View File

@ -2,145 +2,5 @@
Tiny Core Ironic Python Agent Tiny Core Ironic Python Agent
============================= =============================
Build script requirements See
------------------------- https://docs.openstack.org/ironic-python-agent-builder/latest/admin/tinyipa.html
For the main build script:
* wget
* pip
* unzip
* sudo
* awk
* mksquashfs
For building an ISO you'll also need:
* genisoimage
Instructions:
-------------
To create a new ramdisk, run::
make
or::
./build-tinyipa.sh && ./finalise-tinyipa.sh
This will create two new files once completed:
* tinyipa.vmlinuz
* tinyipa.gz
These are your two files to upload to glance for use with Ironic.
Building an ISO from a previous make run:
-----------------------------------------
Once you've built tinyipa it is possible to pack it into an ISO if required. To
create a bootable ISO, run::
make iso
or::
./build-iso.sh
This will create one new file once completed:
* tinyipa.iso
To build a fresh ramdisk and build an iso from it:
--------------------------------------------------
Run::
make all
To clean up the whole build environment run:
--------------------------------------------
Run::
make clean
For cleaning up just the iso or just the ramdisk build::
make clean_iso
or::
make clean_build
Advanced options
----------------
(De)Optimizing the image
~~~~~~~~~~~~~~~~~~~~~~~~
If you want the build script to preinstall everything into the ramdisk,
instead of loading some things at runtime (this results in a slightly bigger
ramdisk), before running make or build-tinyipa.sh run::
export BUILD_AND_INSTALL_TINYIPA=true
By default, building TinyIPA will compile most of the Python code to
optimized ``*.pyo`` files, completely remove most of ``*.py`` and ``*.pyc``
files, and run ironic-python-agent with ``PYTHONOPTIMIZE=1``
to save space on the ramdisk.
If instead you want a normal Python experience inside the image,
for example for debugging/hacking on IPA in a running ramdisk,
before running make or build-tinyipa.sh run::
export PYOPTIMIZE_TINYIPA=false
Enabling/disabling SSH access to the ramdisk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default tinyipa will be built with OpenSSH server installed but no
public SSH keys authorized to access it.
If you want to enable SSH access to the image, set ``AUTHORIZE_SSH`` variable
in your shell before building the tinyipa::
export AUTHORIZE_SSH=true
By default it will use public RSA or DSA keys of the user running the build.
To provide other public SSH key, export path to it in your shell before
building tinyipa as follows::
export SSH_PUBLIC_KEY=<full-path-to-public-key>
If you want to disable SSH altogether, set ``INSTALL_SSH`` variable in your
shell to ``false`` before building the tinyipa::
export INSTALL_SSH=false
You can also rebuild an already built tinyipa image by using ``addssh`` make
tagret::
make addssh
This will fetch the pre-built tinyipa image from "tarballs.openstack.org"
using the version specified as ``BRANCH_NAME`` shell variable as described
above, or it may use an already downloaded ramdisk image if path to it is set
as ``TINYIPA_RAMDISK_FILE`` shell variable before running this make target.
It will install and configure OpenSSH if needed and add public SSH keys for
``tc`` user using the same ``SSH_PUBLIC_KEY`` shell variable as described
above.
Enabling biosdevname in the ramdisk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to collect BIOS given names of NICs in the inventory, set
``TINYIPA_REQUIRE_BIOSDEVNAME`` variable in your shell before building the
tinyipa::
export TINYIPA_REQUIRE_BIOSDEVNAME=true
Using ironic-lib from source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`ironic-lib <https://opendev.org/openstack/ironic-lib>`_ contains
important parts of the provisioning logic. If you need to build an IPA image
with your local checkout of `ironic-lib`, export the following variable::
export IRONIC_LIB_SOURCE=/absolute/path/to/ironic-lib/checkout