Add documentation on building images

Mostly copy-pasted with small fixes from ironic-python-agent. Change-Id: I8333a36f343991a888c6e9276ecae03aaf1941ae
2 years ago · d9bc2b6ccc
--- a/.gitignore
+++ b/.gitignore
@ -51,3 +51,5 @@ ChangeLog

 # Files created by releasenotes build
 releasenotes/build
 RELEASENOTES.rst
 releasenotes/notes/reno.cache
--- a/doc/source/admin/dib.rst
+++ b/doc/source/admin/dib.rst
@ -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
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@ -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
--- a/doc/source/admin/tinyipa.rst
+++ b/doc/source/admin/tinyipa.rst
@ -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
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@ -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
--- a/tinyipa/README.rst
+++ b/tinyipa/README.rst
@ -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