From d9bc2b6ccc6f48485873de12a1d87e6b5300cec2 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Thu, 5 Sep 2019 13:32:54 +0200 Subject: [PATCH] Add documentation on building images Mostly copy-pasted with small fixes from ironic-python-agent. Change-Id: I8333a36f343991a888c6e9276ecae03aaf1941ae --- .gitignore | 2 + doc/source/admin/dib.rst | 103 +++++++++++++++++++ doc/source/admin/index.rst | 14 ++- doc/source/admin/tinyipa.rst | 193 +++++++++++++++++++++++++++++++++++ doc/source/install/index.rst | 14 ++- tinyipa/README.rst | 144 +------------------------- 6 files changed, 316 insertions(+), 154 deletions(-) create mode 100644 doc/source/admin/dib.rst create mode 100644 doc/source/admin/tinyipa.rst diff --git a/.gitignore b/.gitignore index de7bc65..6e193d9 100644 --- a/.gitignore +++ b/.gitignore @@ -51,3 +51,5 @@ ChangeLog # Files created by releasenotes build releasenotes/build +RELEASENOTES.rst +releasenotes/notes/reno.cache diff --git a/doc/source/admin/dib.rst b/doc/source/admin/dib.rst new file mode 100644 index 0000000..c1ef962 --- /dev/null +++ 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 + +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 "`` 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 diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 2aa5ec5..c220ba2 100644 --- 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 + dib + tinyipa .. _Ironic Python Agent: https://docs.openstack.org/ironic-python-agent -.. _diskimage-builder: https://docs.openstack.org/diskimage-builder diff --git a/doc/source/admin/tinyipa.rst b/doc/source/admin/tinyipa.rst new file mode 100644 index 0000000..634da4b --- /dev/null +++ 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= + +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 +`_. +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 diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 510d2f7..9f42133 100644 --- 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 -`_, 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 diff --git a/tinyipa/README.rst b/tinyipa/README.rst index 90a13e6..a02b1f9 100644 --- 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= - -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 `_ 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