openstack/ironic-inspector
Code Issues Proposed changes

Update terribly outdated installation instructions

Browse Source 
* Update configuration options to reflect switch to keystoneauth
* Add iPXE and UEFI configuration
* Mention puppet-ironic and bifrost
* Make ordering more logical now that we only have 1 ramdisk
* Various small fixes

Change-Id: I8c4a64b260db801622bd30d6c4f2c93b41580af0
Closes-Bug: #1416371
This commit is contained in:
Dmitry Tantsur 2016-06-08 17:26:57 +02:00
parent 457c1277de
commit aa01aa7206
1 changed files with 166 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

248
doc/source/install.rst
View File

@ -15,6 +15,13 @@ status.
Finally, some distributions (e.g. Fedora) provide **ironic-inspector** Finally, some distributions (e.g. Fedora) provide **ironic-inspector**
packaged, some of them - under its old name *ironic-discoverd*. packaged, some of them - under its old name *ironic-discoverd*.
There are several projects you can use to set up **ironic-inspector** in
production. `puppet-ironic
<http://git.openstack.org/cgit/openstack/puppet-ironic/>`_ provides Puppet
manifests, while `bifrost <http://docs.openstack.org/developer/bifrost/>`_
provides an Ansible-based standalone installer. Refer to Configuration_
if you plan on installing **ironic-inspector** manually.
.. _PyPI: https://pypi.python.org/pypi/ironic-inspector .. _PyPI: https://pypi.python.org/pypi/ironic-inspector
Note for Ubuntu users Note for Ubuntu users
@ -40,6 +47,7 @@ Ironic Version Standalone Inspection Interface
Juno 1.0 N/A Juno 1.0 N/A
Kilo 1.0 - 2.2 1.0 - 1.1 Kilo 1.0 - 2.2 1.0 - 1.1
Liberty 1.1 - 2.X 2.0 - 2.X Liberty 1.1 - 2.X 2.0 - 2.X
Mitaka+ 2.0 - 2.X 2.0 - 2.X
============== ========== ==================== ============== ========== ====================
.. note:: .. note::
@ -53,11 +61,10 @@ Copy ``example.conf`` to some permanent place
(e.g. ``/etc/ironic-inspector/inspector.conf``). (e.g. ``/etc/ironic-inspector/inspector.conf``).
Fill in at least these configuration values: Fill in at least these configuration values:
* ``os_username``, ``os_password``, ``os_tenant_name`` - Keystone credentials * The ``keystone_authtoken`` section - credentials to use when checking user
to use when accessing other services and check client authentication tokens; authentication.
* ``os_auth_url``, ``identity_uri`` - Keystone endpoints for validating * The ``ironic`` section - credentials to use when accessing the Ironic API.
authentication tokens and checking user roles;
* ``connection`` in the ``database`` section - SQLAlchemy connection string * ``connection`` in the ``database`` section - SQLAlchemy connection string
for the database; for the database;
@ -75,6 +82,49 @@ for the other possible configuration options.
Configuration file contains a password and thus should be owned by ``root`` Configuration file contains a password and thus should be owned by ``root``
and should have access rights like ``0600``. and should have access rights like ``0600``.
Here is an example *inspector.conf* (adapted from a gate run)::
[DEFAULT]
debug = false
rootwrap_config = /etc/ironic-inspector/rootwrap.conf
[database]
connection = mysql+pymysql://root:<PASSWORD>@127.0.0.1/ironic_inspector?charset=utf8
[firewall]
dnsmasq_interface = br-ctlplane
[ironic]
os_region = RegionOne
project_name = service
password = <PASSWORD>
username = ironic-inspector
auth_url = http://127.0.0.1/identity
auth_type = password
[keystone_authtoken]
auth_uri = http://127.0.0.1/identity
project_name = service
password = <PASSWORD>
username = ironic-inspector
auth_url = http://127.0.0.1/identity_v2_admin
auth_type = password
[processing]
ramdisk_logs_dir = /var/log/ironic-inspector/ramdisk
store_data = swift
[swift]
os_region = RegionOne
project_name = service
password = <PASSWORD>
username = ironic-inspector
auth_url = http://127.0.0.1/identity
auth_type = password
.. note::
Set ``debug = true`` if you want to see complete logs.
**ironic-inspector** requires root rights for managing iptables. It gets them **ironic-inspector** requires root rights for managing iptables. It gets them
by running ``ironic-inspector-rootwrap`` utility with ``sudo``. by running ``ironic-inspector-rootwrap`` utility with ``sudo``.
To allow it, copy file ``rootwrap.conf`` and directory ``rootwrap.d`` to the To allow it, copy file ``rootwrap.conf`` and directory ``rootwrap.d`` to the
@ -103,6 +153,41 @@ configuration directory (e.g. ``/etc/ironic-inspector/``) and create file
Replace ``stack`` with whatever user you'll be using to run Replace ``stack`` with whatever user you'll be using to run
**ironic-inspector**. **ironic-inspector**.
Configuring IPA
^^^^^^^^^^^^^^^
ironic-python-agent_ is a ramdisk developed for Ironic. During the Liberty
cycle support for **ironic-inspector** was added. This is the default ramdisk
starting with the Mitaka release.
.. note::
You need at least 1.5 GiB of RAM on the machines to use IPA built with
diskimage-builder_ and at least 384 MiB to use the *TinyIPA*.
To build an ironic-python-agent ramdisk, do the following:
* Get the new enough version of diskimage-builder_::
sudo pip install -U "diskimage-builder>=1.1.2"
* Build the ramdisk::
disk-image-create ironic-agent fedora -o ironic-agent
.. note::
Replace "fedora" with your distribution of choice.
* Use the resulting files ``ironic-agent.kernel`` and
``ironic-agent.initramfs`` in the following instructions to set PXE or iPXE.
Alternatively, you can download a `prebuilt TinyIPA image
<http://tarballs.openstack.org/ironic-python-agent/tinyipa/files/>`_ or use
the `other builders
<http://docs.openstack.org/developer/ironic-python-agent/#image-builders>`_.
.. _diskimage-builder: https://github.com/openstack/diskimage-builder
.. _ironic-python-agent: https://github.com/openstack/ironic-python-agent
Configuring PXE Configuring PXE
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
@ -111,10 +196,41 @@ As for PXE boot environment, you'll need:
* TFTP server running and accessible (see below for using *dnsmasq*). * TFTP server running and accessible (see below for using *dnsmasq*).
Ensure ``pxelinux.0`` is present in the TFTP root. Ensure ``pxelinux.0`` is present in the TFTP root.
Copy ``ironic-agent.kernel`` and ``ironic-agent.initramfs`` to the TFTP
root as well.
* Next, set up ``$TFTPROOT/pxelinux.cfg/default`` as follows::
default introspect
label introspect
kernel ironic-agent.kernel
append initrd=ironic-agent.initramfs ipa-inspection-callback-url=http://{IP}:5050/v1/continue systemd.journald.forward_to_console=yes
ipappend 3
Replace ``{IP}`` with IP of the machine (do not use loopback interface, it
will be accessed by ramdisk on a booting machine).
.. note::
While ``systemd.journald.forward_to_console=yes`` is not actually
required, it will substantially simplify debugging if something
goes wrong.
IPA is pluggable: you can insert introspection plugins called
*collectors* into it. For example, to enable a very handy ``logs`` collector
(sending ramdisk logs to **ironic-inspector**), modify the ``append`` line in
``$TFTPROOT/pxelinux.cfg/default``::
append initrd=ironic-agent.initramfs ipa-inspection-callback-url=http://{IP}:5050/v1/continue ipa-inspection-collectors=default,logs systemd.journald.forward_to_console=yes
.. note::
You probably want to always keep the ``default`` collector, as it provides
the basic information required for introspection.
* You need PXE boot server (e.g. *dnsmasq*) running on **the same** machine as * You need PXE boot server (e.g. *dnsmasq*) running on **the same** machine as
**ironic-inspector**. Don't do any firewall configuration: **ironic-inspector**. Don't do any firewall configuration:
**ironic-inspector** will handle it for you. In **ironic-inspector** **ironic-inspector** will handle it for you. In the **ironic-inspector**
configuration file set ``dnsmasq_interface`` to the interface your configuration file set ``dnsmasq_interface`` to the interface your
PXE boot server listens on. Here is an example *dnsmasq.conf*:: PXE boot server listens on. Here is an example *dnsmasq.conf*::
@ -132,87 +248,65 @@ As for PXE boot environment, you'll need:
simultaneously cause conflicts - the same IP address is suggested to simultaneously cause conflicts - the same IP address is suggested to
several nodes. several nodes.
* You have to install and configure the ramdisk to be run on target machines - Configuring iPXE
see `Configuring IPA`_. ^^^^^^^^^^^^^^^^
Here is *inspector.conf* you may end up with:: iPXE allows better scaling as it primarily uses the HTTP protocol instead of
slow and unreliable TFTP. You still need a TFTP server as a fall back for
nodes not supporting iPXE. To use iPXE you'll need:
[DEFAULT] * TFTP server running and accessible (see above for using *dnsmasq*).
debug = false Ensure ``undionly.kpxe`` is present in the TFTP root. If any of your nodes
[ironic] boot with UEFI, you'll also need ``ipxe.efi`` there.
identity_uri = http://127.0.0.1:35357
os_auth_url = http://127.0.0.1:5000/v2.0 * You also need an HTTP server capable of serving static files.
os_username = admin Copy ``ironic-agent.kernel`` and ``ironic-agent.initramfs`` there.
os_password = password
os_tenant_name = admin * Create a file called ``inspector.ipxe`` in the HTTP root (you can name and
[firewall] place it differently, just don't forget to adjust the *dnsmasq.conf* example
dnsmasq_interface = br-ctlplane below)::
#!ipxe
:retry_dhcp
dhcp || goto retry_dhcp
:retry_boot
imgfree
kernel --timeout 30000 http://{IP}:8088/ironic-agent.kernel ipa-inspection-callback-url=http://{IP}>:5050/v1/continue systemd.journald.forward_to_console=yes BOOTIF=${mac} initrd=agent.ramdisk || goto retry_boot
initrd --timeout 30000 http://{IP}:8088/ironic-agent.ramdisk || goto retry_boot
boot
.. note:: .. note::
Set ``debug = true`` if you want to see complete logs. Older versions of the iPXE ROM tend to misbehave on unreliable network
connection, thus we use the timeout option with retries.
Configuring IPA Just like with PXE you can customize the list of collectors by appending
^^^^^^^^^^^^^^^ the ``ipa-inspector-collectors`` kernel option, for example::
ironic-python-agent_ is a ramdisk developed for Ironic. During the Liberty ipa-inspection-collectors=default,logs,extra_hardware
cycle support for **ironic-inspector** was added. This is the default ramdisk
starting with the Mitaka release.
.. note:: * Just as with PXE you'll need a PXE boot server. The configuration, however,
You need at least 1.5 GiB of RAM on the machines to use this ramdisk, will be different. Here is an example *dnsmasq.conf*::
2 GiB is recommended.
To build an ironic-python-agent ramdisk, do the following: port=0
interface={INTERFACE}
bind-interfaces
dhcp-range={DHCP IP RANGE, e.g. 192.168.0.50,192.168.0.150}
enable-tftp
tftp-root={TFTP ROOT, e.g. /tftpboot}
dhcp-sequential-ip
dhcp-match=ipxe,175
dhcp-match=set:efi,option:client-arch,7
dhcp-boot=tag:ipxe,http://{IP}:8088/inspector.ipxe
dhcp-boot=tag:efi,ipxe.efi
dhcp-boot=undionly.kpxe,localhost.localdomain,{IP}
* Get the new enough version of diskimage-builder_:: First, we configure the same common parameters as with PXE. Then we define
``ipxe`` and ``efi`` tags. Nodes already supporting iPXE are ordered to
sudo pip install -U "diskimage-builder>=1.1.2" download and execute ``inspector.ipxe``. Nodes without iPXE booted with UEFI
will get ``ipxe.efi`` firmware to execute, while the remaining will get
* Build the ramdisk:: ``undionly.kpxe``.
disk-image-create ironic-agent fedora -o ironic-agent
.. note::
Replace "fedora" with your distribution of choice.
* Copy resulting files ``ironic-agent.vmlinuz`` and ``ironic-agent.initramfs``
to the TFTP root directory.
Alternatively, you can download a `prebuilt IPA image
<http://tarballs.openstack.org/ironic-python-agent/coreos/files/>`_ or use
the `CoreOS-based IPA builder
<http://docs.openstack.org/developer/ironic-python-agent/#coreos>`_.
Next, set up ``$TFTPROOT/pxelinux.cfg/default`` as follows::
default introspect
label introspect
kernel ironic-agent.vmlinuz
append initrd=ironic-agent.initramfs ipa-inspection-callback-url=http://{IP}:5050/v1/continue systemd.journald.forward_to_console=yes
ipappend 3
Replace ``{IP}`` with IP of the machine (do not use loopback interface, it
will be accessed by ramdisk on a booting machine).
.. note::
While ``systemd.journald.forward_to_console=yes`` is not actually
required, it will substantially simplify debugging if something goes wrong.
This ramdisk is pluggable: you can insert introspection plugins called
*collectors* into it. For example, to enable a very handy ``logs`` collector
(sending ramdisk logs to **ironic-inspector**), modify the ``append`` line in
``$TFTPROOT/pxelinux.cfg/default``::
append initrd=ironic-agent.initramfs ipa-inspection-callback-url=http://{IP}:5050/v1/continue ipa-inspection-collectors=default,logs systemd.journald.forward_to_console=yes
.. note::
You probably want to always keep ``default`` collector, as it provides the
basic information required for introspection.
.. _diskimage-builder: https://github.com/openstack/diskimage-builder
.. _ironic-python-agent: https://github.com/openstack/ironic-python-agent
Managing the **ironic-inspector** database Managing the **ironic-inspector** database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~