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
2
.gitignore
vendored
2
.gitignore
vendored
@@ -51,3 +51,5 @@ ChangeLog
|
||||
|
||||
# Files created by 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
|
||||
====================
|
||||
|
||||
This guide describes how to build an `Ironic Python Agent`_-based image using
|
||||
the builders provided in the **ironic-python-agent-builder** project.
|
||||
This guide describes how to build and use an `Ironic Python Agent`_-based image
|
||||
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::
|
||||
|
||||
ironic-python-agent-builder <distribution, e.g. ubuntu>
|
||||
dib
|
||||
tinyipa
|
||||
|
||||
.. _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
|
||||
======================================
|
||||
|
||||
Download the ``ironic-python-agent-builder`` package from
|
||||
`tarballs.openstack.org
|
||||
<https://tarballs.openstack.org/ironic-python-agent-builder/>`_, install it
|
||||
from your distribution's repositories or use pip::
|
||||
Download the ``ironic-python-agent-builder`` archive from
|
||||
`tarballs.openstack.org`_, install it from your distribution's repositories
|
||||
or use pip::
|
||||
|
||||
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
|
||||
=============================
|
||||
|
||||
Build script requirements
|
||||
-------------------------
|
||||
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
|
||||
See
|
||||
https://docs.openstack.org/ironic-python-agent-builder/latest/admin/tinyipa.html
|
||||
|
||||
Reference in New Issue
Block a user