<commit_before>.. _install-guide:

=====================================
Bare Metal service Installation Guide
=====================================

This document pertains to the current code (on master branch) of OpenStack
Bare Metal service (ironic) and should be accurate for the Kilo (2015.1)
release of the Bare Metal service.
Users of earlier releases may encounter differences, and are encouraged
to look at earlier versions of this document for guidance.


Service overview
~~~~~~~~~~~~~~~~

The Bare Metal service is a collection of components that provides support to
manage and provision physical machines.

Also known as the ``ironic`` project, the Bare Metal service may, depending
upon configuration, interact with several other OpenStack services. This
includes:

- the OpenStack Telemetry module (ceilometer) for consuming the IPMI metrics
- the OpenStack Identity service (keystone) for request authentication and to
  locate other OpenStack services
- the OpenStack Image service (glance) from which to retrieve images and image meta-data
- the OpenStack Networking service (neutron) for DHCP and network configuration
- the OpenStack Compute service (nova) works with the Bare Metal service and acts as
  a user-facing API for instance management, while the Bare Metal service provides
  the admin/operator API for hardware management.
  The OpenStack Compute service also provides scheduling facilities (matching
  flavors <-> images <-> hardware), tenant quotas, IP assignment, and other
  services which the Bare Metal service does not, in and of itself, provide.

- the OpenStack Block Storage (cinder) provides volumes, but this aspect is not yet available.

The Bare Metal service includes the following components:

- ironic-api: A RESTful API that processes application requests by sending
  them to the ironic-conductor over RPC.
- ironic-conductor: Adds/edits/deletes nodes; powers on/off nodes with
  ipmi or ssh; provisions/deploys/decommissions bare metal nodes.
- ironic-python-agent: A python service which is run in a temporary ramdisk to
  provide ironic-conductor service(s) with remote access and in-band hardware
  control.
- python-ironicclient: A command-line interface (CLI) for interacting with
  the Bare Metal service.

Additionally, the Bare Metal service has certain external dependencies, which are
very similar to other OpenStack services:

- A database to store hardware information and state. You can set the database
  back-end type and location. A simple approach is to use the same database
  back end as the Compute service. Another approach is to use a separate
  database back-end to further isolate bare metal resources (and associated
  metadata) from users.
- A queue. A central hub for passing messages, such as RabbitMQ.
  It should use the same implementation as that of the Compute service.

Optionally, one may wish to utilize the following associated projects for
additional functionality:

- ironic-inspector_; An associated service which performs in-band hardware
  introspection by PXE booting unregistered hardware into a "discovery ramdisk".
- diskimage-builder_; May be used to customize machine images, create and
  discovery deploy ramdisks, if necessary.

.. _ironic-inspector: https://github.com/openstack/ironic-inspector
.. _diskimage-builder: https://github.com/openstack/diskimage-builder


.. todo: include coreos-image-builder reference here, once the split is done


Install and configure prerequisites
===================================

The Bare Metal service is a collection of components that provides support to
manage and provision physical machines. You can configure these components to
run on separate nodes or the same node. In this guide, the components run on
one node, typically the Compute Service's compute node.

This section shows you how to install and configure the components.

It assumes that the Identity, Image, Compute, and Networking services
have already been set up.

Configure the Identity service for the Bare Metal service
---------------------------------------------------------

#. Create the Bare Metal service user (for example,``ironic``).
   The service uses this to authenticate with the Identity service.
   Use the ``service`` tenant and give the user the ``admin`` role::

    keystone user-create --name=ironic --pass=<PASSWORD> --email=<EMAIL>
    keystone user-role-add --user=ironic --tenant=service --role=admin

#. You must register the Bare Metal service with the Identity service so that
   other OpenStack services can locate it. To register the service::

    keystone service-create --name=ironic --type=baremetal \
    --description="Ironic bare metal provisioning service"

#. Use the ``id`` property that is returned from the Identity service when
   registering the service (above), to create the endpoint,
   and replace IRONIC_NODE with your Bare Metal service's API node::

    keystone endpoint-create \
    --service-id=the_service_id_above \
    --publicurl=http://IRONIC_NODE:6385 \
    --internalurl=http://IRONIC_NODE:6385 \
    --adminurl=http://IRONIC_NODE:6385

.. error::
    If the keystone endpoint-create operation returns an error about not being
    able to find the region "regionOne", the error is due to this keystone bug:
    https://bugs.launchpad.net/keystone/+bug/1400589. As a workaround until
    that bug is fixed you can force the creation of "RegionOne" by passing
    --region=RegionOne as an argument to the keystone endpoint-create command.

Set up the database for Bare Metal
----------------------------------

The Bare Metal service stores information in a database. This guide uses the
MySQL database that is used by other OpenStack services.

#. In MySQL, create an ``ironic`` database that is accessible by the
   ``ironic`` user. Replace IRONIC_DBPASSWORD
   with a suitable password::

    # mysql -u root -p
    mysql> CREATE DATABASE ironic CHARACTER SET utf8;
    mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'localhost' \
    IDENTIFIED BY 'IRON<PASSWORD>DBPASSWORD';
    mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'%' \
    IDENTIFIED BY '<PASSWORD>';

Install the Bare Metal service
------------------------------

#. Install from packages::

    Ubuntu 14.04 (trusty) or higher:
        apt-get install ironic-api ironic-conductor python-ironicclient

    RHEL7/CentOS7/Fedora 21 or higher:
        yum install openstack-ironic-api openstack-ironic-conductor python-ironicclient


Configure the Bare Metal service
================================

The Bare Metal service is configured via its configuration file. This file<commit_msg>Update 'Installation Guide' for RHEL7/CentOS7/Fedora<commit_after>.. _install-guide:

=====================================
Bare Metal service Installation Guide
=====================================

This document pertains to the current code (on master branch) of OpenStack
Bare Metal service (ironic) and should be accurate for the Kilo (2015.1)
release of the Bare Metal service.
Users of earlier releases may encounter differences, and are encouraged
to look at earlier versions of this document for guidance.


Service overview
~~~~~~~~~~~~~~~~

The Bare Metal service is a collection of components that provides support to
manage and provision physical machines.

Also known as the ``ironic`` project, the Bare Metal service may, depending
upon configuration, interact with several other OpenStack services. This
includes:

- the OpenStack Telemetry module (ceilometer) for consuming the IPMI metrics
- the OpenStack Identity service (keystone) for request authentication and to
  locate other OpenStack services
- the OpenStack Image service (glance) from which to retrieve images and image meta-data
- the OpenStack Networking service (neutron) for DHCP and network configuration
- the OpenStack Compute service (nova) works with the Bare Metal service and acts as
  a user-facing API for instance management, while the Bare Metal service provides
  the admin/operator API for hardware management.
  The OpenStack Compute service also provides scheduling facilities (matching
  flavors <-> images <-> hardware), tenant quotas, IP assignment, and other
  services which the Bare Metal service does not, in and of itself, provide.

- the OpenStack Block Storage (cinder) provides volumes, but this aspect is not yet available.

The Bare Metal service includes the following components:

- ironic-api: A RESTful API that processes application requests by sending
  them to the ironic-conductor over RPC.
- ironic-conductor: Adds/edits/deletes nodes; powers on/off nodes with
  ipmi or ssh; provisions/deploys/decommissions bare metal nodes.
- ironic-python-agent: A python service which is run in a temporary ramdisk to
  provide ironic-conductor service(s) with remote access and in-band hardware
  control.
- python-ironicclient: A command-line interface (CLI) for interacting with
  the Bare Metal service.

Additionally, the Bare Metal service has certain external dependencies, which are
very similar to other OpenStack services:

- A database to store hardware information and state. You can set the database
  back-end type and location. A simple approach is to use the same database
  back end as the Compute service. Another approach is to use a separate
  database back-end to further isolate bare metal resources (and associated
  metadata) from users.
- A queue. A central hub for passing messages, such as RabbitMQ.
  It should use the same implementation as that of the Compute service.

Optionally, one may wish to utilize the following associated projects for
additional functionality:

- ironic-inspector_; An associated service which performs in-band hardware
  introspection by PXE booting unregistered hardware into a "discovery ramdisk".
- diskimage-builder_; May be used to customize machine images, create and
  discovery deploy ramdisks, if necessary.

.. _ironic-inspector: https://github.com/openstack/ironic-inspector
.. _diskimage-builder: https://github.com/openstack/diskimage-builder


.. todo: include coreos-image-builder reference here, once the split is done


Install and configure prerequisites
===================================

The Bare Metal service is a collection of components that provides support to
manage and provision physical machines. You can configure these components to
run on separate nodes or the same node. In this guide, the components run on
one node, typically the Compute Service's compute node.

This section shows you how to install and configure the components.

It assumes that the Identity, Image, Compute, and Networking services
have already been set up.

Configure the Identity service for the Bare Metal service
---------------------------------------------------------

#. Create the Bare Metal service user (for example,``ironic``).
   The service uses this to authenticate with the Identity service.
   Use the ``service`` tenant and give the user the ``admin`` role::

    keystone user-create --name=ironic --pass=<PASSWORD> --email=<EMAIL>
    keystone user-role-add --user=ironic --tenant=service --role=admin

#. You must register the Bare Metal service with the Identity service so that
   other OpenStack services can locate it. To register the service::

    keystone service-create --name=ironic --type=baremetal \
    --description="Ironic bare metal provisioning service"

#. Use the ``id`` property that is returned from the Identity service when
   registering the service (above), to create the endpoint,
   and replace IRONIC_NODE with your Bare Metal service's API node::

    keystone endpoint-create \
    --service-id=the_service_id_above \
    --publicurl=http://IRONIC_NODE:6385 \
    --internalurl=http://IRONIC_NODE:6385 \
    --adminurl=http://IRONIC_NODE:6385

.. error::
    If the keystone endpoint-create operation returns an error about not being
    able to find the region "regionOne", the error is due to this keystone bug:
    https://bugs.launchpad.net/keystone/+bug/1400589. As a workaround until
    that bug is fixed you can force the creation of "RegionOne" by passing
    --region=RegionOne as an argument to the keystone endpoint-create command.

Set up the database for Bare Metal
----------------------------------

The Bare Metal service stores information in a database. This guide uses the
MySQL database that is used by other OpenStack services.

#. In MySQL, create an ``ironic`` database that is accessible by the
   ``ironic`` user. Replace IRONIC_DBPASSWORD
   with a suitable password::

    # mysql -u root -p
    mysql> CREATE DATABASE ironic CHARACTER SET utf8;
    mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'localhost' \
    IDENTIFIED BY '<PASSWORD>';
    mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'%' \
    IDENTIFIED BY '<PASSWORD>IC_DBPASSWORD';

Install the Bare Metal service
------------------------------

#. Install from packages and configure services::

    Ubuntu 14.04 (trusty) or higher:
        sudo apt-get install ironic-api ironic-conductor python-ironicclient

    RHEL7/CentOS7/Fedora 21 or higher:
        sudo yum install openstack-ironic-api openstack-ironic-conductor \
        python-ironicclient
        sudo systemctl enable openstack-ironic-api openstack-ironic-conductor
        sudo systemctl start openstack-ironic-api openstack-ironic-conductor


Configure the Bare Metal service
================================

The Bare Metal service is configured via its configuration file. This file
{'fraction_non_alphanumeric': 0.09745449163830103, 'fraction_numerical': 0.005031818854521237, 'mean_word_length': 3.8755411255411256, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 21, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5507224', 'n_tokens_mistral': 3562, 'n_tokens_neox': 3295, 'n_words': 1654}