99732e5297
* Flatten the directory structure (we don't have that many doc files) * Dropped HTTP-API from the root so that we don't maintain 2 copies * Fixed links all over the place * Leave one copy of README text in the root and include it in docs * Update 'tox -epep8' to also check docs Change-Id: Ic14cb73668544be27c6b96b384f93b239e49acfd
268 lines
9.3 KiB
ReStructuredText
268 lines
9.3 KiB
ReStructuredText
.. _install_guide:
|
|
|
|
Installation
|
|
------------
|
|
|
|
Install from PyPI_ (you may want to use virtualenv to isolate your
|
|
environment)::
|
|
|
|
pip install ironic-inspector
|
|
|
|
Also there is a `DevStack <http://docs.openstack.org/developer/devstack/>`_
|
|
plugin for **ironic-inspector** - see :ref:`contributing_link` for the current
|
|
status.
|
|
|
|
Finally, some distributions (e.g. Fedora) provide **ironic-inspector**
|
|
packaged, some of them - under its old name *ironic-discoverd*.
|
|
|
|
.. _PyPI: https://pypi.python.org/pypi/ironic-inspector
|
|
|
|
Version Support Matrix
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
**ironic-inspector** currently requires bare metal API version ``1.6`` to be
|
|
provided by Ironic. This version is available starting with Ironic Kilo
|
|
release.
|
|
|
|
Here is a mapping between Ironic versions and supported **ironic-inspector**
|
|
versions. The Standalone column shows which **ironic-inspector** versions can
|
|
be used in standalone mode with each Ironic version. The Inspection Interface
|
|
column shows which **ironic-inspector** versions can be used with the Ironic
|
|
inspection interface in each version of Ironic.
|
|
|
|
============== ========== ====================
|
|
Ironic Version Standalone Inspection Interface
|
|
============== ========== ====================
|
|
Juno 1.0 N/A
|
|
Kilo 1.0 - 2.2 1.0 - 1.1
|
|
Liberty 1.1 - 2.X 2.0 - 2.X
|
|
============== ========== ====================
|
|
|
|
.. note::
|
|
``2.X`` means we don't have specific plans on deprecating support for this
|
|
Ironic version. This does not imply that we'll support it forever though.
|
|
|
|
Configuration
|
|
~~~~~~~~~~~~~
|
|
|
|
Copy ``example.conf`` to some permanent place
|
|
(e.g. ``/etc/ironic-inspector/inspector.conf``).
|
|
Fill in at least these configuration values:
|
|
|
|
* ``os_username``, ``os_password``, ``os_tenant_name`` - Keystone credentials
|
|
to use when accessing other services and check client authentication tokens;
|
|
|
|
* ``os_auth_url``, ``identity_uri`` - Keystone endpoints for validating
|
|
authentication tokens and checking user roles;
|
|
|
|
* ``connection`` in the ``database`` section - SQLAlchemy connection string
|
|
for the database;
|
|
|
|
* ``dnsmasq_interface`` - interface on which ``dnsmasq`` (or another DHCP
|
|
service) listens for PXE boot requests (defaults to ``br-ctlplane`` which is
|
|
a sane default for TripleO-based installations but is unlikely to work for
|
|
other cases).
|
|
|
|
See comments inside `example.conf
|
|
<https://github.com/openstack/ironic-inspector/blob/master/example.conf>`_
|
|
for the other possible configuration options.
|
|
|
|
.. note::
|
|
Configuration file contains a password and thus should be owned by ``root``
|
|
and should have access rights like ``0600``.
|
|
|
|
**ironic-inspector** requires root rights for managing iptables. It gets them
|
|
by running ``ironic-inspector-rootwrap`` utility with ``sudo``.
|
|
To allow it, copy file ``rootwrap.conf`` and directory ``rootwrap.d`` to the
|
|
configuration directory (e.g. ``/etc/ironic-inspector/``) and create file
|
|
``/etc/sudoers.d/ironic-inspector-rootwrap`` with the following content::
|
|
|
|
stack ALL=(root) NOPASSWD: /usr/bin/ironic-inspector-rootwrap /etc/ironic-inspector/rootwrap.conf *
|
|
|
|
.. DANGER::
|
|
Be very careful about typos in ``/etc/sudoers.d/ironic-inspector-rootwrap``
|
|
as any typo will break sudo for **ALL** users on the system. Especially,
|
|
make sure there is a new line at the end of this file.
|
|
|
|
.. note::
|
|
``rootwrap.conf`` and all files in ``rootwrap.d`` must be writeable
|
|
only by root.
|
|
|
|
.. note::
|
|
If you store ``rootwrap.d`` in a different location, make sure to update
|
|
the *filters_path* option in ``rootwrap.conf`` to reflect the change.
|
|
|
|
If your ``rootwrap.conf`` is in a different location, then you need
|
|
to update the *rootwrap_config* option in ``ironic-inspector.conf``
|
|
to point to that location.
|
|
|
|
Replace ``stack`` with whatever user you'll be using to run
|
|
**ironic-inspector**.
|
|
|
|
Configuring PXE
|
|
^^^^^^^^^^^^^^^
|
|
|
|
As for PXE boot environment, you'll need:
|
|
|
|
* TFTP server running and accessible (see below for using *dnsmasq*).
|
|
Ensure ``pxelinux.0`` is present in the TFTP root.
|
|
|
|
|
|
* You need PXE boot server (e.g. *dnsmasq*) running on **the same** machine as
|
|
**ironic-inspector**. Don't do any firewall configuration:
|
|
**ironic-inspector** will handle it for you. In **ironic-inspector**
|
|
configuration file set ``dnsmasq_interface`` to the interface your
|
|
PXE boot server listens on. Here is an example *dnsmasq.conf*::
|
|
|
|
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-boot=pxelinux.0
|
|
|
|
* You have to install and configure one of 2 available ramdisks: simple
|
|
bash-based (see `Using simple ramdisk`_) or more complex based on
|
|
ironic-python-agent_ (See `Using IPA`_).
|
|
|
|
Here is *inspector.conf* you may end up with::
|
|
|
|
[DEFAULT]
|
|
debug = false
|
|
[ironic]
|
|
identity_uri = http://127.0.0.1:35357
|
|
os_auth_url = http://127.0.0.1:5000/v2.0
|
|
os_username = admin
|
|
os_password = password
|
|
os_tenant_name = admin
|
|
[firewall]
|
|
dnsmasq_interface = br-ctlplane
|
|
|
|
.. note::
|
|
Set ``debug = true`` if you want to see complete logs.
|
|
|
|
Using simple ramdisk
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
* Build and put into your TFTP the kernel and ramdisk created using the
|
|
diskimage-builder_ `ironic-discoverd-ramdisk element`_::
|
|
|
|
ramdisk-image-create -o discovery fedora ironic-discoverd-ramdisk
|
|
|
|
You need diskimage-builder_ 0.1.38 or newer to do it (using the latest one
|
|
is always advised).
|
|
|
|
* Configure your ``$TFTPROOT/pxelinux.cfg/default`` with something like::
|
|
|
|
default introspect
|
|
|
|
label introspect
|
|
kernel discovery.kernel
|
|
append initrd=discovery.initramfs discoverd_callback_url=http://{IP}:5050/v1/continue
|
|
|
|
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::
|
|
There are some prebuilt images which use obsolete ``ironic_callback_url``
|
|
instead of ``discoverd_callback_url``. Modify ``pxelinux.cfg/default``
|
|
accordingly if you have one of these.
|
|
|
|
Using IPA
|
|
^^^^^^^^^
|
|
|
|
ironic-python-agent_ is a new ramdisk developed for Ironic. During the Liberty
|
|
cycle support for **ironic-inspector** was added. This is experimental
|
|
for now, but we plan on making IPA the default ramdisk in Mitaka cycle.
|
|
|
|
.. note::
|
|
You need at least 1.5 GiB of RAM on the machines to use this ramdisk.
|
|
|
|
To build an ironic-python-agent ramdisk, do the following:
|
|
|
|
* Get the latest 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.
|
|
|
|
* Copy resulting files ``ironic-agent.vmlinuz`` and ``ironic-agent.initramfs``
|
|
to the TFTP root directory.
|
|
|
|
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.
|
|
|
|
.. _diskimage-builder: https://github.com/openstack/diskimage-builder
|
|
.. _ironic-discoverd-ramdisk element: https://github.com/openstack/diskimage-builder/tree/master/elements/ironic-discoverd-ramdisk
|
|
.. _ironic-python-agent: https://github.com/openstack/ironic-python-agent
|
|
|
|
Managing the **ironic-inspector** database
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
**ironic-inspector** provides a command line client for managing its database,
|
|
this client can be used for upgrading, and downgrading the database using
|
|
alembic migrations.
|
|
|
|
If this is your first time running **ironic-inspector** to migrate the
|
|
database simply run:
|
|
::
|
|
|
|
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf upgrade
|
|
|
|
If you have previously run a version of **ironic-inspector** earlier than
|
|
2.2.0, the safest thing is to delete the existing SQLite database and run
|
|
``upgrade`` as shown above. If you, however, want to save the existing
|
|
database, to ensure your database will work with the migrations, you'll need to
|
|
run an extra step before upgrading the database. You only need to do this the
|
|
first time running version 2.2.0 or later.
|
|
|
|
If you are upgrading from **ironic-inspector** version 2.1.0 or lower:
|
|
::
|
|
|
|
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf stamp --revision 578f84f38d
|
|
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf upgrade
|
|
|
|
If you are upgrading from a git master install of **ironic-inspector** from
|
|
after :ref:`rules` were introduced:
|
|
::
|
|
|
|
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf stamp --revision d588418040d
|
|
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf upgrade
|
|
|
|
Other available commands can be discovered by running::
|
|
|
|
ironic-inspector-dbsync --help
|
|
|
|
Running
|
|
~~~~~~~
|
|
|
|
::
|
|
|
|
ironic-inspector --config-file /etc/ironic-inspector/inspector.conf
|
|
|
|
A good starting point for writing your own *systemd* unit should be `one used
|
|
in Fedora <http://pkgs.fedoraproject.org/cgit/openstack-ironic-discoverd.git/plain/openstack-ironic-discoverd.service>`_
|
|
(note usage of old name).
|