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
parent
42862e0276
commit
d9bc2b6ccc
2
.gitignore
vendored
2
.gitignore
vendored
@ -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
103
doc/source/admin/dib.rst
Normal 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
|
||||||
@ -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
|
|
||||||
|
|||||||
193
doc/source/admin/tinyipa.rst
Normal file
193
doc/source/admin/tinyipa.rst
Normal 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
|
||||||
@ -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
|
||||||
|
|||||||
@ -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
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user