Begin breaking out installation documentation
Broke out install related content, and linked the mission statement in to the main index page. Change-Id: I439e07429f9862f57520c7f92f5b0814536c0ffc
This commit is contained in:
parent
3f19e0c6fa
commit
bc0a12dfff
238
README.rst
238
README.rst
|
@ -7,7 +7,6 @@ automates the task of deploying a base image onto a set of known hardware using
|
||||||
ironic. It provides modular utility for one-off operating system deployment
|
ironic. It provides modular utility for one-off operating system deployment
|
||||||
with as few operational requirements as reasonably possible.
|
with as few operational requirements as reasonably possible.
|
||||||
|
|
||||||
========================
|
|
||||||
Team and repository tags
|
Team and repository tags
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
@ -16,7 +15,6 @@ Team and repository tags
|
||||||
|
|
||||||
.. Change things from this point on
|
.. Change things from this point on
|
||||||
|
|
||||||
=========
|
|
||||||
Use Cases
|
Use Cases
|
||||||
=========
|
=========
|
||||||
|
|
||||||
|
@ -26,237 +24,9 @@ Use Cases
|
||||||
a batch operation.
|
a batch operation.
|
||||||
* Testing and development of ironic in a standalone use case.
|
* Testing and development of ironic in a standalone use case.
|
||||||
|
|
||||||
==========
|
Documentation
|
||||||
How to Use
|
=============
|
||||||
==========
|
|
||||||
|
|
||||||
Installation and use of bifrost is split into roughly three steps:
|
Bifrost's documentation can be found at the
|
||||||
|
`OpenStack documentation site <https://docs.openstack.org/bifrost/latest>`.
|
||||||
|
|
||||||
- **install**:
|
|
||||||
prepare the local environment by downloading and/or building machine images,
|
|
||||||
and installing and configuring the necessary services.
|
|
||||||
- **enroll-dynamic**:
|
|
||||||
take as input a customizable hardware inventory file and enroll the
|
|
||||||
listed hardware with ironic, configuring each appropriately for deployment
|
|
||||||
with the previously-downloaded images.
|
|
||||||
- **deploy-dynamic**:
|
|
||||||
instruct ironic to deploy the operating system onto each machine.
|
|
||||||
|
|
||||||
Supported operating systems:
|
|
||||||
|
|
||||||
* Ubuntu 14.04, 14.10, 15.04, 16.04
|
|
||||||
* Red Hat Enterprise Linux (RHEL) 7
|
|
||||||
* CentOS 7
|
|
||||||
* Fedora 22
|
|
||||||
* openSUSE Leap 42.1, 42.2
|
|
||||||
|
|
||||||
============
|
|
||||||
Installation
|
|
||||||
============
|
|
||||||
|
|
||||||
Pre-install steps
|
|
||||||
=================
|
|
||||||
|
|
||||||
Installing bifrost on RHEL or CentOS requires a few extra pre-install steps.
|
|
||||||
|
|
||||||
Enable additional repositories (RHEL only)
|
|
||||||
------------------------------------------
|
|
||||||
|
|
||||||
The extras and optional yum repositories must be enabled to satisfy
|
|
||||||
bifrost's dependencies. To check::
|
|
||||||
|
|
||||||
sudo yum repolist | grep 'optional\|extras'
|
|
||||||
|
|
||||||
To add the repositories::
|
|
||||||
|
|
||||||
sudo yum repolist all | grep 'optional\|extras'
|
|
||||||
|
|
||||||
The output will look like this::
|
|
||||||
|
|
||||||
!rhui-REGION-rhel-server-debug-extras/7Server/x86_64 Red H disabled
|
|
||||||
rhui-REGION-rhel-server-debug-optional/7Server/x86_64 Red H disabled
|
|
||||||
rhui-REGION-rhel-server-extras/7Server/x86_64 Red H disabled
|
|
||||||
rhui-REGION-rhel-server-optional/7Server/x86_64 Red H disabled
|
|
||||||
rhui-REGION-rhel-server-source-extras/7Server/x86_64 Red H disabled
|
|
||||||
rhui-REGION-rhel-server-source-optional/7Server/x86_64 Red H disabled
|
|
||||||
|
|
||||||
Use the names of the repositories (minus the version and architecture) to enable them::
|
|
||||||
|
|
||||||
sudo yum-config-manager --enable rhui-REGION-rhel-server-optional
|
|
||||||
sudo yum-config-manager --enable rhui-REGION-rhel-server-extras
|
|
||||||
|
|
||||||
Enable the EPEL repository (RHEL)
|
|
||||||
---------------------------------
|
|
||||||
|
|
||||||
The Extra Packages for Enterprise Linux (EPEL) repository contains
|
|
||||||
some of bifrost's dependencies. To enable it, install the
|
|
||||||
``epel-release`` package as follows::
|
|
||||||
|
|
||||||
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
|
|
||||||
|
|
||||||
Enable the EPEL repository (CentOS)
|
|
||||||
-----------------------------------
|
|
||||||
|
|
||||||
To enable EPEL on CentOS, run::
|
|
||||||
|
|
||||||
sudo yum install epel-release
|
|
||||||
|
|
||||||
Bifrost Installation
|
|
||||||
====================
|
|
||||||
|
|
||||||
The installation is split into two parts.
|
|
||||||
|
|
||||||
The first part is a bash script which lays the basic groundwork of installing
|
|
||||||
Ansible itself.
|
|
||||||
|
|
||||||
Bifrost source code should be pulled directly from git first::
|
|
||||||
|
|
||||||
git clone https://git.openstack.org/openstack/bifrost.git
|
|
||||||
cd bifrost
|
|
||||||
|
|
||||||
Edit ``./playbooks/inventory/group_vars/*`` to match your environment. The
|
|
||||||
target file is intended for steps executed upon the target server, such as
|
|
||||||
installation, or image generation. The baremetal file is geared for steps
|
|
||||||
performed on baremetal nodes, such as enrollment, deployment, or any other
|
|
||||||
custom playbooks that a user may bolt on to this toolkit.
|
|
||||||
|
|
||||||
- If MySQL is already installed, update ``mysql_password`` to match
|
|
||||||
your local installation.
|
|
||||||
- Change ``network_interface`` to match the interface that will need
|
|
||||||
to service DHCP requests.
|
|
||||||
- Change the ``ironic_db_password`` which is set by Ansible in MySQL
|
|
||||||
and in ironic's configuration file.
|
|
||||||
|
|
||||||
The install process builds or modifies a disk image to deploy. The
|
|
||||||
following two settings (which are mutually exclusive) allow you to
|
|
||||||
choose if a partition image is used or an image is created with
|
|
||||||
diskimage-builder::
|
|
||||||
|
|
||||||
create_image_via_dib: true
|
|
||||||
transform_boot_image: false
|
|
||||||
|
|
||||||
If you are running the installation behind a proxy, export the
|
|
||||||
environment variables ``http_proxy`` and ``https_proxy`` so that
|
|
||||||
Ansible will use these proxy settings.
|
|
||||||
|
|
||||||
The recommended path for use is with a local Ansible installation, and to
|
|
||||||
install the library requirements. Alternatively the ``env-setup.sh`` script
|
|
||||||
will install ansible and all of bifrost's dependencies.
|
|
||||||
|
|
||||||
If you use ``env-setup.sh``, ansible will be installed along
|
|
||||||
with its missing Python dependencies into user's ``~/.local`` directory.
|
|
||||||
|
|
||||||
Warning::
|
|
||||||
|
|
||||||
Use of the ``env-setup.sh`` script can squash an existing
|
|
||||||
Ansible installation, and is intended primarily for development
|
|
||||||
and testing.
|
|
||||||
|
|
||||||
Note::
|
|
||||||
|
|
||||||
The next setup steps require elevated privilges, and might need to
|
|
||||||
be executed with the ``sudo`` command, depending on the access rights
|
|
||||||
of the user executing the command.
|
|
||||||
|
|
||||||
If using the environment setup script::
|
|
||||||
|
|
||||||
bash ./scripts/env-setup.sh
|
|
||||||
export PATH=${HOME}/.local/bin:${PATH}
|
|
||||||
cd playbooks
|
|
||||||
|
|
||||||
Otherwise::
|
|
||||||
|
|
||||||
pip install -r requirements.txt
|
|
||||||
cd playbooks
|
|
||||||
|
|
||||||
The second part is an Ansible playbook that installs and configures ironic
|
|
||||||
in a stand-alone fashion.
|
|
||||||
|
|
||||||
* Keystone is NOT installed by default, and ironic's API is accessible without
|
|
||||||
authentication. It is possible to put basic password auth on ironic's API by
|
|
||||||
changing the nginx configuration accordingly.
|
|
||||||
|
|
||||||
* Bifrost playbooks can leverage and optionally install keystone.
|
|
||||||
See `doc/source/keystone.rst`.
|
|
||||||
|
|
||||||
* Neutron is NOT installed. Ironic performs static IP injection via
|
|
||||||
config-drive.
|
|
||||||
* dnsmasq is configured statically and responds to all PXE boot requests by
|
|
||||||
chain-loading to iPXE, which then fetches the ironic-python-agent ramdisk
|
|
||||||
from Nginx.
|
|
||||||
* Deployments are performed by the Ironic Python Agent, which as configured
|
|
||||||
supports IPMI, iLO, and UCS drivers.
|
|
||||||
* By default, installation will build an Ubuntu-based image for deployment
|
|
||||||
to nodes. This image can be easily customized if so desired.
|
|
||||||
|
|
||||||
The re-execution of the playbook will cause states to be re-asserted. If not
|
|
||||||
already present, a number of software packages including MySQL and RabbitMQ
|
|
||||||
will be installed on the host. Python code will be reinstalled regardless if
|
|
||||||
it has changed, RabbitMQ user passwords will be reset, and services will be
|
|
||||||
restarted.
|
|
||||||
|
|
||||||
Run::
|
|
||||||
|
|
||||||
If you have passwordless sudo enabled, run:
|
|
||||||
ansible-playbook -vvvv -i inventory/target install.yaml
|
|
||||||
Otherwise, add -K option to let Ansible prompting for the sudo password:
|
|
||||||
ansible-playbook -K -vvvv -i inventory/target install.yaml
|
|
||||||
|
|
||||||
With regard to testing, ironic's node cleaning capability is disabled by
|
|
||||||
default as it can be an unexpected surprise for a new user that their test
|
|
||||||
node is unusable for however long it takes for the disks to be wiped.
|
|
||||||
|
|
||||||
If you wish to enable cleaning, you can achieve this by passing the option
|
|
||||||
``-e cleaning=true`` to the command line or executing the command below::
|
|
||||||
|
|
||||||
ansible-playbook -K -vvvv -i inventory/target install.yaml -e cleaning=true
|
|
||||||
|
|
||||||
After you have performed an installation, you can edit /etc/ironic/ironic.conf
|
|
||||||
to enable or disable cleaning as desired, however it is highly encouraged to
|
|
||||||
utilize cleaning in any production environment.
|
|
||||||
|
|
||||||
The ironic community maintains a repository additional of drivers outside ironic.
|
|
||||||
These drivers and information about them can be found in
|
|
||||||
`ironic-staging-drivers docs <http://git.openstack.org/cgit/openstack/ironic-staging-drivers/>`_.
|
|
||||||
If you would like to install the ironic staging drivers, simply pass
|
|
||||||
``-e staging_drivers_include=true`` when executing the install playbook::
|
|
||||||
|
|
||||||
ansible-playbook -K -vvvv -i inventory/target install.yaml -e staging_drivers_include=true
|
|
||||||
|
|
||||||
==============
|
|
||||||
Driver Support
|
|
||||||
==============
|
|
||||||
|
|
||||||
|
|
||||||
Testing Mode
|
|
||||||
============
|
|
||||||
|
|
||||||
When setup in testing mode, bifrost configures ironic to utilize the
|
|
||||||
``agent_ssh`` driver to help facilitate the deployment of local test
|
|
||||||
machines.
|
|
||||||
|
|
||||||
|
|
||||||
Default Mode
|
|
||||||
============
|
|
||||||
|
|
||||||
When not in testing mode, bifrost enables the following ironic drivers:
|
|
||||||
|
|
||||||
* agent_ipmitool
|
|
||||||
* agent_ilo
|
|
||||||
* agent_ucs
|
|
||||||
|
|
||||||
|
|
||||||
OneView Driver Support
|
|
||||||
======================
|
|
||||||
|
|
||||||
As the OneView driver requires configuration information to be populated
|
|
||||||
in the ironic.conf configuration file that points to the OneView manager
|
|
||||||
node as well as credentials, bifrost does not support installation and
|
|
||||||
configuration of the driver.
|
|
||||||
|
|
||||||
Please reference the ironic OneView driver documentation at if you wish
|
|
||||||
to update the configuration after installation in order to leverage bifrost
|
|
||||||
for mass node deployment.
|
|
||||||
|
|
||||||
More information about this driver can be found in the
|
|
||||||
`OneView driver documentation <http://docs.openstack.org/developer/ironic/drivers/oneview.html>`_.
|
|
||||||
|
|
|
@ -7,43 +7,6 @@
|
||||||
|
|
||||||
.. _`IRC`: https://wiki.openstack.org/wiki/Ironic#IRC
|
.. _`IRC`: https://wiki.openstack.org/wiki/Ironic#IRC
|
||||||
|
|
||||||
Installation with Keystone
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
Bifrost can now install and make use of keystone. In order to enable
|
|
||||||
this as part of the installation, the ``enable_keystone`` variable
|
|
||||||
must be set to ``true``.
|
|
||||||
Either in ``playbooks/inventory/group_vars/target`` or on the
|
|
||||||
command line during installation. Example::
|
|
||||||
|
|
||||||
ansible-playbook -vvvv -i inventory/target install.yaml -e enable_keystone=true
|
|
||||||
|
|
||||||
However, prior to installation, overriding credentials should be set
|
|
||||||
in order to customize the deployment to meet your needs. See::
|
|
||||||
|
|
||||||
playbooks/roles/bifrost-ironic-install/defaults/main.yml
|
|
||||||
playbooks/roles/bifrost-keystone-install/defaults/main.yml
|
|
||||||
|
|
||||||
Using an existing Keystone
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
If you choose to install bifrost using an existing keystone, this
|
|
||||||
should be possible, however it has not been tested. In this case you
|
|
||||||
will need to set the appropriate defaults, via
|
|
||||||
``playbooks/roles/bifrost-ironic-install/defaults/main.yml``
|
|
||||||
which would be a good source for the role level defaults.
|
|
||||||
Ideally, when setting new defaults, they should be set in the
|
|
||||||
``playbooks/inventory/group_vars/target`` file.
|
|
||||||
|
|
||||||
Creation of clouds.yaml
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
By default, during bifrost installation, when keystone is enabled,
|
|
||||||
a file will be written to the user's home directory that is executing
|
|
||||||
the installation. That file can be located at
|
|
||||||
``~/.config/openstack/clouds.yaml``. The cloud that is written
|
|
||||||
to that file is named ``bifrost``.
|
|
||||||
|
|
||||||
Bifrost execution with Keystone
|
Bifrost execution with Keystone
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
|
|
|
@ -328,24 +328,4 @@ Use Bifrost with Keystone
|
||||||
=========================
|
=========================
|
||||||
.. include:: deploy/keystone.rst
|
.. include:: deploy/keystone.rst
|
||||||
|
|
||||||
Virtualenv installation support (EXPERIMENTAL)
|
|
||||||
==============================================
|
|
||||||
|
|
||||||
Bifrost can be used with a python virtual environment. At present,
|
|
||||||
this feature is experimental, so it's disabled by default. If you
|
|
||||||
would like to use a virtual environment, you'll need to modify the
|
|
||||||
install steps slightly. To set up the virtual environment and install
|
|
||||||
ansible into it, run ``env-setup.sh`` as follows::
|
|
||||||
|
|
||||||
export VENV=/opt/stack/bifrost
|
|
||||||
./scripts/env-setup.sh
|
|
||||||
|
|
||||||
Then run the install playbook with the following arguments::
|
|
||||||
|
|
||||||
ansible-playbook -vvvv -i inventory/target install.yaml
|
|
||||||
|
|
||||||
This will install ironic and its dependencies into the virtual environment.
|
|
||||||
|
|
||||||
Offline Installation
|
|
||||||
====================
|
|
||||||
.. include:: offline-install.rst
|
|
||||||
|
|
|
@ -1,20 +1,17 @@
|
||||||
Welcome to bifrost's documentation!
|
Welcome to bifrost's documentation!
|
||||||
========================================================
|
===================================
|
||||||
|
|
||||||
|
.. include:: ../../README.rst
|
||||||
|
|
||||||
|
.. include:: ../../MISSION.rst
|
||||||
|
|
||||||
Contents:
|
Contents:
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 1
|
||||||
|
|
||||||
readme
|
install/index
|
||||||
howto
|
howto
|
||||||
contributing
|
contributing
|
||||||
troubleshooting
|
troubleshooting
|
||||||
vagrant
|
vagrant
|
||||||
|
|
||||||
Indices and tables
|
|
||||||
==================
|
|
||||||
|
|
||||||
* :ref:`genindex`
|
|
||||||
* :ref:`search`
|
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,277 @@
|
||||||
|
####################
|
||||||
|
Bifrost Installation
|
||||||
|
####################
|
||||||
|
|
||||||
|
============
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
Installation and use of bifrost is split into roughly three steps:
|
||||||
|
|
||||||
|
- **install**:
|
||||||
|
prepare the local environment by downloading and/or building machine images,
|
||||||
|
and installing and configuring the necessary services.
|
||||||
|
- **enroll-dynamic**:
|
||||||
|
take as input a customizable hardware inventory file and enroll the
|
||||||
|
listed hardware with ironic, configuring each appropriately for deployment
|
||||||
|
with the previously-downloaded images.
|
||||||
|
- **deploy-dynamic**:
|
||||||
|
instruct ironic to deploy the operating system onto each machine.
|
||||||
|
|
||||||
|
Supported operating systems:
|
||||||
|
|
||||||
|
* Ubuntu 14.04, 14.10, 15.04, 16.04
|
||||||
|
* Red Hat Enterprise Linux (RHEL) 7
|
||||||
|
* CentOS 7
|
||||||
|
* Fedora 22
|
||||||
|
* openSUSE Leap 42.1, 42.2
|
||||||
|
|
||||||
|
============
|
||||||
|
Installation
|
||||||
|
============
|
||||||
|
|
||||||
|
Pre-install steps
|
||||||
|
=================
|
||||||
|
|
||||||
|
Installing bifrost on RHEL or CentOS requires a few extra pre-install steps,
|
||||||
|
in order to have access to the additional packages contained in the EPEL
|
||||||
|
repository. Some of the software bifrost leverages, can only be obtained from
|
||||||
|
EPEL on RHEL and CentOS systems.
|
||||||
|
|
||||||
|
.. note:: Use of EPEL repositories may result in incompatible packages
|
||||||
|
being installed by the package manager. Care should be taken
|
||||||
|
when using a system with EPEL enabled.
|
||||||
|
|
||||||
|
RHEL
|
||||||
|
----
|
||||||
|
|
||||||
|
Enable additional repositories (RHEL only)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The ``extras`` and ``optional`` yum repositories must be enabled to satisfy
|
||||||
|
bifrost's dependencies. To check::
|
||||||
|
|
||||||
|
sudo yum repolist | grep 'optional\|extras'
|
||||||
|
|
||||||
|
To view the status of repositories::
|
||||||
|
|
||||||
|
sudo yum repolist all | grep 'optional\|extras'
|
||||||
|
|
||||||
|
The output will look like this::
|
||||||
|
|
||||||
|
!rhui-REGION-rhel-server-debug-extras/7Server/x86_64 Red H disabled
|
||||||
|
rhui-REGION-rhel-server-debug-optional/7Server/x86_64 Red H disabled
|
||||||
|
rhui-REGION-rhel-server-extras/7Server/x86_64 Red H disabled
|
||||||
|
rhui-REGION-rhel-server-optional/7Server/x86_64 Red H disabled
|
||||||
|
rhui-REGION-rhel-server-source-extras/7Server/x86_64 Red H disabled
|
||||||
|
rhui-REGION-rhel-server-source-optional/7Server/x86_64 Red H disabled
|
||||||
|
|
||||||
|
Use the names of the repositories (minus the version and architecture) to enable them::
|
||||||
|
|
||||||
|
sudo yum-config-manager --enable rhui-REGION-rhel-server-optional
|
||||||
|
sudo yum-config-manager --enable rhui-REGION-rhel-server-extras
|
||||||
|
|
||||||
|
Enable the EPEL repository
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The Extra Packages for Enterprise Linux (EPEL) repository contains
|
||||||
|
some of bifrost's dependencies. To enable it, install the
|
||||||
|
``epel-release`` package as follows::
|
||||||
|
|
||||||
|
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
|
||||||
|
|
||||||
|
CentOS
|
||||||
|
------
|
||||||
|
|
||||||
|
Enable the EPEL repository (CentOS)
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
To enable EPEL on CentOS, run::
|
||||||
|
|
||||||
|
sudo yum install epel-release
|
||||||
|
|
||||||
|
Performing the installation
|
||||||
|
===========================
|
||||||
|
|
||||||
|
Installation is split into four parts:
|
||||||
|
|
||||||
|
* Cloning the bifrost repository
|
||||||
|
* Installation of Ansible
|
||||||
|
* Configuring settings for the installation
|
||||||
|
* Execution of the installation playbook
|
||||||
|
|
||||||
|
.. note:: The documentation expects that you have a copy of the repository
|
||||||
|
on your local machine, and that your working directory is inside
|
||||||
|
of the copy of the bifrost repository.
|
||||||
|
|
||||||
|
Cloning
|
||||||
|
-------
|
||||||
|
|
||||||
|
Clone the Bifrost repository::
|
||||||
|
|
||||||
|
git clone https://git.openstack.org/openstack/bifrost.git
|
||||||
|
cd bifrost
|
||||||
|
|
||||||
|
Installation of Ansible
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Installation of Ansible can take place using the provided environment setup
|
||||||
|
script located at ``scripts/env-setup.sh`` which is present in the bifrost
|
||||||
|
repository. This may also be used if you already have ansible, as it will
|
||||||
|
install ansible and various dependencies to ``~/.local`` in order to avoid
|
||||||
|
overwriting or conflicting with a system-wide Ansible installation.
|
||||||
|
|
||||||
|
If you use ``env-setup.sh``, ansible will be installed along
|
||||||
|
with its missing Python dependencies into user's ``~/.local`` directory.
|
||||||
|
|
||||||
|
Alternatively, if you have a working Ansible installation,
|
||||||
|
under normal circumstances the installation playbook can be executed.
|
||||||
|
|
||||||
|
.. note:: All testing takes place utilizing the ``scripts/env-setup.sh``
|
||||||
|
script. Please feel free to submit
|
||||||
|
`bug reports <https://bugs.launchpad.net/bifrost/>`_ or patches
|
||||||
|
to OpenStack Gerrit for any issues encountered if you choose to
|
||||||
|
directly invoke the playbooks without using ``env-setup.sh``.
|
||||||
|
|
||||||
|
Pre-installation settings
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Before performing the installation, it is highly recommended that you edit
|
||||||
|
``./playbooks/inventory/group_vars/*`` to match your environment. Several
|
||||||
|
files are located in this folder, and you may wish to review and edit the
|
||||||
|
settings across multiple files:
|
||||||
|
|
||||||
|
* The ``target`` file is used by roles that execute against the target node
|
||||||
|
upon which you are installing ironic and all required services.
|
||||||
|
* The ``baremetal`` file is geared for roles executed against baremetal
|
||||||
|
nodes. This may be useful if you are automating multiple steps involving
|
||||||
|
deployment and configuration of nodes beyond deployment via the same
|
||||||
|
roles.
|
||||||
|
* The ``localhost`` file is similar to the ``target`` file, and likely
|
||||||
|
contains identical settings. This file is referenced if no explicit
|
||||||
|
target is defined, as it defaults to the localhost.
|
||||||
|
|
||||||
|
Duplication between variable names does occur within these files, as
|
||||||
|
variables are unique to the group that the role is being executed
|
||||||
|
upon.
|
||||||
|
|
||||||
|
- If MySQL is already installed, update ``mysql_password`` to match
|
||||||
|
your local installation.
|
||||||
|
- Change ``network_interface`` to match the interface that will need
|
||||||
|
to service DHCP requests.
|
||||||
|
- Change the ``ironic_db_password`` which is set by ansible in MySQL
|
||||||
|
and in ironic's configuration file.
|
||||||
|
|
||||||
|
The install process, when executed will either download, or build
|
||||||
|
disk images for the deployment of nodes, and be deployed to the nodes.
|
||||||
|
|
||||||
|
If you wish to build an image, based upon the settings, you will need
|
||||||
|
to set ``create_image_via_dib`` to ``true``.
|
||||||
|
|
||||||
|
.. note:: Bifrost does not overwrite pre-existing IPA ramdisk and
|
||||||
|
deployment image files. As such, you will need to remove
|
||||||
|
the files if you wish to rebuild them.
|
||||||
|
These files typically consist the default files:
|
||||||
|
``/httpboot/deployment_image.qcow2``, ``/httpboot/ipa.kernel``,
|
||||||
|
``/etc/httpboot/ipa.initramfs``.
|
||||||
|
|
||||||
|
If you are running the installation behind a proxy, export the
|
||||||
|
environment variables ``http_proxy`` and ``https_proxy`` so that
|
||||||
|
ansible will use these proxy settings.
|
||||||
|
|
||||||
|
Installing
|
||||||
|
----------
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
|
In order to really get started, you must install dependencies.
|
||||||
|
|
||||||
|
If you used the ``env-setup.sh`` environment setup script::
|
||||||
|
|
||||||
|
bash ./scripts/env-setup.sh
|
||||||
|
export PATH=${HOME}/.local/bin:${PATH}
|
||||||
|
cd playbooks
|
||||||
|
|
||||||
|
Otherwise::
|
||||||
|
|
||||||
|
pip install -r requirements.txt
|
||||||
|
cd playbooks
|
||||||
|
|
||||||
|
Once the dependencies are in-place, you can execute the ansible playbook to
|
||||||
|
perform the actual installation. The playbook will install and configure
|
||||||
|
ironic in a stand-alone fashion.
|
||||||
|
|
||||||
|
A few important notes:
|
||||||
|
|
||||||
|
* The OpenStack Identity service (keystone) is NOT installed by default,
|
||||||
|
and ironic's API is accessible without authentication. It is possible
|
||||||
|
to put basic password authentication on ironic's API by changing the nginx
|
||||||
|
configuration accordingly.
|
||||||
|
|
||||||
|
.. note:: Bifrost playbooks can leverage and optionally install keystone.
|
||||||
|
See :doc:`Keystone install details <keystone>`.
|
||||||
|
|
||||||
|
* The OpenStack Networking service (neutron) is NOT installed. Ironic performs
|
||||||
|
static IP injection via config-drive or DHCP reservation.
|
||||||
|
* Deployments are performed by the ironic python agent (IPA).
|
||||||
|
* dnsmasq is configured statically and responds to all PXE boot requests by
|
||||||
|
chain-loading to iPXE, which then fetches the Ironic Python Agent ramdisk
|
||||||
|
from nginx.
|
||||||
|
* By default, installation will build an Ubuntu-based image for deployment
|
||||||
|
to nodes. This image can be easily customized if so desired.
|
||||||
|
|
||||||
|
The re-execution of the playbook will cause states to be re-asserted. If not
|
||||||
|
already present, a number of software packages including MySQL and RabbitMQ
|
||||||
|
will be installed on the host. Python code will be reinstalled regardless if
|
||||||
|
it has changed. RabbitMQ user passwords will be reset, and services will be
|
||||||
|
restarted.
|
||||||
|
|
||||||
|
Playbook Execution
|
||||||
|
^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
If you have passwordless sudo enabled, run::
|
||||||
|
|
||||||
|
ansible-playbook -vvvv -i inventory/target install.yaml
|
||||||
|
|
||||||
|
Otherwise, add the ``-K`` to the ansible command line, to trigger ansible
|
||||||
|
to prompt for the sudo password::
|
||||||
|
|
||||||
|
ansible-playbook -K -vvvv -i inventory/target install.yaml
|
||||||
|
|
||||||
|
With regard to testing, ironic's node cleaning capability is disabled by
|
||||||
|
default as it can be an unexpected surprise for a new user that their test
|
||||||
|
node is unusable for however long it takes for the disks to be wiped.
|
||||||
|
|
||||||
|
If you wish to enable cleaning, you can achieve this by passing the option
|
||||||
|
``-e cleaning=true`` to the command line or executing the command below::
|
||||||
|
|
||||||
|
ansible-playbook -K -vvvv -i inventory/target install.yaml -e cleaning=true
|
||||||
|
|
||||||
|
After you have performed an installation, you can edit
|
||||||
|
``/etc/ironic/ironic.conf`` to enable or disable cleaning as desired.
|
||||||
|
It is highly encouraged to utilize cleaning in any production environment.
|
||||||
|
|
||||||
|
Additional ironic drivers
|
||||||
|
=========================
|
||||||
|
|
||||||
|
An additional collection of drivers are maintained outside of the ironic source
|
||||||
|
code repository, as they do not have Continuous Integration (CI) testing.
|
||||||
|
|
||||||
|
These drivers and information about them can be found in
|
||||||
|
`ironic-staging-drivers docs <https://git.openstack.org/cgit/openstack/ironic-staging-drivers/>`_.
|
||||||
|
If you would like to install the ironic staging drivers, simply pass
|
||||||
|
``-e staging_drivers_include=true`` when executing the install playbook::
|
||||||
|
|
||||||
|
ansible-playbook -K -vvvv -i inventory/target install.yaml -e staging_drivers_include=true
|
||||||
|
|
||||||
|
Advanced Topics
|
||||||
|
===============
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
keystone
|
||||||
|
offline-install
|
||||||
|
virtualenv
|
||||||
|
oneview
|
|
@ -0,0 +1,42 @@
|
||||||
|
Installation with Keystone
|
||||||
|
==========================
|
||||||
|
|
||||||
|
.. NOTE:: Use of keystone with bifrost is a very new feature and should
|
||||||
|
be considered an advanced topic. Please feel free to reach out to the
|
||||||
|
bifrost contributors and the ironic community as a whole in the project's
|
||||||
|
`IRC`_ channel.
|
||||||
|
|
||||||
|
.. _`IRC`: https://wiki.openstack.org/wiki/Ironic#IRC
|
||||||
|
|
||||||
|
Bifrost can now install and make use of keystone. In order to enable
|
||||||
|
this as part of the installation, the ``enable_keystone`` variable
|
||||||
|
must be set to ``true``, either in ``playbooks/inventory/group_vars/target``
|
||||||
|
or on the command line during installation. Example::
|
||||||
|
|
||||||
|
ansible-playbook -vvvv -i inventory/target install.yaml -e enable_keystone=true
|
||||||
|
|
||||||
|
However, prior to installation, overriding credentials should be set
|
||||||
|
in order to customize the deployment to meet your needs.
|
||||||
|
|
||||||
|
* ``playbooks/roles/bifrost-ironic-install/defaults/main.yml``
|
||||||
|
* ``playbooks/roles/bifrost-keystone-install/defaults/main.yml``
|
||||||
|
|
||||||
|
Using an existing Keystone
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
If you choose to install bifrost using an existing keystone, this
|
||||||
|
should be possible, however it has not been tested. In this case you
|
||||||
|
will need to set the appropriate defaults, via
|
||||||
|
``playbooks/roles/bifrost-ironic-install/defaults/main.yml``
|
||||||
|
which would be a good source for the role level defaults.
|
||||||
|
Ideally, when setting new defaults, they should be set in the
|
||||||
|
``playbooks/inventory/group_vars/target`` file.
|
||||||
|
|
||||||
|
Creation of clouds.yaml
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
By default, during bifrost installation, when keystone is enabled,
|
||||||
|
a file will be written to the user's home directory that is executing
|
||||||
|
the installation. That file can be located at
|
||||||
|
``~/.config/openstack/clouds.yaml``. The cloud that is written
|
||||||
|
to that file is named ``bifrost``.
|
|
@ -1,8 +1,10 @@
|
||||||
|
Offline Installation
|
||||||
|
--------------------
|
||||||
|
|
||||||
The ansible scripts that compose Bifrost download and install
|
The ansible scripts that compose Bifrost download and install
|
||||||
software via a number of means, which generally assumes connectivity
|
software via a number of means, which generally assumes connectivity
|
||||||
to the internet.
|
to the internet. However, it is possible to use Bifrost without external
|
||||||
|
connectivity.
|
||||||
That connectivity is not required.
|
|
||||||
|
|
||||||
If you want or need to install Bifrost without having a dependency on
|
If you want or need to install Bifrost without having a dependency on
|
||||||
a connection to the internet, there are a number of steps that you will
|
a connection to the internet, there are a number of steps that you will
|
||||||
|
@ -14,7 +16,7 @@ steps that need to be done in your inventory file, and the second being
|
||||||
steps that need to be done on your target host outside of Ansible.
|
steps that need to be done on your target host outside of Ansible.
|
||||||
|
|
||||||
Ansible Specific Steps
|
Ansible Specific Steps
|
||||||
----------------------
|
^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
The script ``scripts/env-setup.sh`` will do a ``git clone`` to create
|
The script ``scripts/env-setup.sh`` will do a ``git clone`` to create
|
||||||
``/opt/stack/ansible``, if it doesn't already exist. You can use the
|
``/opt/stack/ansible``, if it doesn't already exist. You can use the
|
||||||
|
@ -28,14 +30,16 @@ are also cloned from an alternate location - otherwise, the submodules
|
||||||
will still try to clone from GitHub.
|
will still try to clone from GitHub.
|
||||||
|
|
||||||
Bifrost Specific Steps
|
Bifrost Specific Steps
|
||||||
----------------------
|
^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
As a general rule, any URL referenced by Bifrost scripts is configured in a
|
As a general rule, any URL referenced by Bifrost scripts is configured in a
|
||||||
``playbook/roles/<role>/defaults/main.yml`` file, which means that all of those
|
``playbook/roles/<role>/defaults/main.yml`` file, which means that all of
|
||||||
can be redirected to point to a local copy by creating a file named
|
those can be redirected to point to a local copy by creating a file named
|
||||||
``playbooks/host_vars/<hostname>.yml`` and redirecting the appropriate variables.
|
``playbooks/host_vars/<hostname>.yml`` and redirecting the appropriate
|
||||||
|
variables.
|
||||||
|
|
||||||
As an example, my current file looks like:
|
As an example, the yaml file's contents may look like something like like
|
||||||
|
this.
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
@ -52,7 +56,7 @@ need to be fixed by looking for any URLs in the
|
||||||
``playbook/roles/<role>/defaults/main.yml`` files, as noted above.
|
``playbook/roles/<role>/defaults/main.yml`` files, as noted above.
|
||||||
|
|
||||||
External Steps
|
External Steps
|
||||||
--------------
|
^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Bifrost doesn't attempt to configure ``apt``, ``yum``, or ``pip``, so if you are
|
Bifrost doesn't attempt to configure ``apt``, ``yum``, or ``pip``, so if you are
|
||||||
working in an offline mode, you'll need to make sure those work independently.
|
working in an offline mode, you'll need to make sure those work independently.
|
|
@ -0,0 +1,9 @@
|
||||||
|
OneView Driver Support
|
||||||
|
======================
|
||||||
|
|
||||||
|
As the OneView driver requires configuration information to be populated
|
||||||
|
in the ``ironic.conf`` configuration file that points to the OneView manager
|
||||||
|
node as well as credentials, bifrost does not support installation and
|
||||||
|
configuration of the driver. Please reference the
|
||||||
|
`OneView driver documentation <http://docs.openstack.org/latest/ironic/admin/drivers/oneview.html>`_
|
||||||
|
for information on configuring of the ``oneview`` driver.
|
|
@ -0,0 +1,17 @@
|
||||||
|
Virtualenv Installation Support
|
||||||
|
===============================
|
||||||
|
|
||||||
|
Bifrost can be used with a Python virtual environment. At present,
|
||||||
|
this feature is experimental, so it's disabled by default. If you
|
||||||
|
would like to use a virtual environment, you'll need to modify the
|
||||||
|
install steps slightly. To set up the virtual environment and install
|
||||||
|
ansible into it, run ``env-setup.sh`` as follows::
|
||||||
|
|
||||||
|
export VENV=/opt/stack/bifrost
|
||||||
|
./scripts/env-setup.sh
|
||||||
|
|
||||||
|
Then run the install playbook with the following arguments::
|
||||||
|
|
||||||
|
ansible-playbook -vvvv -i inventory/target install.yaml
|
||||||
|
|
||||||
|
This will install ironic and its dependencies into the virtual environment.
|
|
@ -1 +0,0 @@
|
||||||
.. include:: ../../README.rst
|
|
Loading…
Reference in New Issue