From e26c71bcf6d25e5c73c6aeb0f9893e57d49f2abf Mon Sep 17 00:00:00 2001 From: Mathieu Mitchell Date: Wed, 7 Sep 2016 08:39:28 -0400 Subject: [PATCH] [install-guide] Import Install and configure sections The following sections of the legacy install guide were imported: * Install and configure prerequisites * Install the Bare Metal service * Configure the Bare Metal service Only changes made to the documentation are the following: * Formatting changes (code-block, proper lists, etc.) * Structure changes (installation and configuration are now under a single section) * Heading titles formatting [0] [0] http://docs.openstack.org/contributor-guide/rst-conv/titles.html Change-Id: I0f1f5dacd4ed31ccfb4ac38c1ff2ecfc94e99ca4 Partial-bug: #1612278 --- doc/source/deploy/install-guide.rst | 417 +----------------- .../source/configure-integration.rst | 7 + .../source/include/common-configure.rst | 12 + .../source/include/common-prerequisites.rst | 33 +- .../source/include/configure-identity.rst | 93 ++++ .../include/configure-ironic-api-mod_wsgi.rst | 63 +++ .../source/include/configure-ironic-api.rst | 95 ++++ .../include/configure-ironic-conductor.rst | 152 +++++++ .../source/include/configure-nova-compute.rst | 7 + install-guide/source/index.rst | 1 + install-guide/source/install-obs.rst | 17 +- install-guide/source/install-rdo.rst | 34 +- install-guide/source/install-ubuntu.rst | 23 +- install-guide/source/install.rst | 6 +- install-guide/source/next-steps.rst | 3 +- install-guide/source/verify.rst | 3 +- 16 files changed, 535 insertions(+), 431 deletions(-) create mode 100644 install-guide/source/configure-integration.rst create mode 100644 install-guide/source/include/common-configure.rst create mode 100644 install-guide/source/include/configure-identity.rst create mode 100644 install-guide/source/include/configure-ironic-api-mod_wsgi.rst create mode 100644 install-guide/source/include/configure-ironic-api.rst create mode 100644 install-guide/source/include/configure-ironic-conductor.rst create mode 100644 install-guide/source/include/configure-nova-compute.rst diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst index b9642f032b..b73c5a3538 100644 --- a/doc/source/deploy/install-guide.rst +++ b/doc/source/deploy/install-guide.rst @@ -21,424 +21,27 @@ Install Guide. 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. +The `prerequisites`_ section has been moved to the Bare Metal service Install +Guide. -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:: - - openstack user create --password IRONIC_PASSWORD \ - --email ironic@example.com ironic - openstack role add --project service --user ironic admin - -#. You must register the Bare Metal service with the Identity service so that - other OpenStack services can locate it. To register the service:: - - openstack service create --name ironic --description \ - "Ironic baremetal provisioning service" baremetal - -#. 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:: - - openstack endpoint create --region RegionOne \ - baremetal admin http://IRONIC_NODE:6385 - openstack endpoint create --region RegionOne \ - baremetal public http://IRONIC_NODE:6385 - openstack endpoint create --region RegionOne \ - baremetal internal http://IRONIC_NODE:6385 - - If only keystone v2 API is available, use this command instead:: - - openstack endpoint create --region RegionOne \ - --publicurl http://IRONIC_NODE:6385 \ - --internalurl http://IRONIC_NODE:6385 \ - --adminurl http://IRONIC_NODE:6385 \ - baremetal - -#. You may delegate limited privileges related to the Bare Metal service - to your Users by creating Roles with the OpenStack Identity service. By - default, the Bare Metal service expects the "baremetal_admin" and - "baremetal_observer" Roles to exist, in addition to the default "admin" - Role. There is no negative consequence if you choose not to create these - Roles. They can be created with the following commands:: - - openstack role create baremetal_admin - openstack role create baremetal_observer - - If you choose to customize the names of Roles used with the Bare Metal - service, do so by changing the "is_member", "is_observer", and "is_admin" - policy settings in ``/etc/ironic/policy.json``. - - More complete documentation on managing Users and Roles within your - OpenStack deployment are outside the scope of this document, but may be - found here_. - -#. You can further restrict access to the Bare Metal service by creating a - separate "baremetal" Project, so that Bare Metal resources (Nodes, Ports, - etc) are only accessible to members of this Project:: - - openstack project create baremetal - - At this point, you may grant read-only access to the Bare Metal service API - without granting any other access by issuing the following commands:: - - openstack user create \ - --domain default --project-domain default --project baremetal \ - --password PASSWORD USERNAME - openstack role add \ - --user-domain default --project-domain default --project baremetal\ - --user USERNAME baremetal_observer - -#. Further documentation is available elsewhere for the ``openstack`` - `command-line client`_ and the Identity_ service. A policy.json.sample_ - file, which enumerates the service's default policies, is provided for - your convenience with the Bare Metal Service. - -.. _Identity: http://docs.openstack.org/admin-guide/identity-management.html -.. _`command-line client`: http://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html -.. _here: http://docs.openstack.org/admin-guide/identity-concepts.html#user-management -.. _policy.json.sample: https://github.com/openstack/ironic/blob/master/etc/ironic/policy.json.sample - - -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 'IRONIC_DBPASSWORD'; - mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'%' \ - IDENTIFIED BY 'IRONIC_DBPASSWORD'; +.. _`prerequisites`: http://docs.openstack.org/project-install-guide/baremetal/draft/install-ubuntu.html#prerequisites Install the Bare Metal service ------------------------------- +============================== -#. Install from packages and configure services:: +The `Install and configure components`_ section has been moved to the Bare +Metal service Install Guide. - Ubuntu 14.04 (trusty) or higher: - sudo apt-get install ironic-api ironic-conductor python-ironicclient - - Fedora 21/RHEL7/CentOS7: - 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 - - Fedora 22 or higher: - sudo dnf 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 +.. _`Install and configure components`: http://docs.openstack.org/project-install-guide/baremetal/draft/install-ubuntu.html#install-and-configure-components Configure the Bare Metal service ================================ -The Bare Metal service is configured via its configuration file. This file -is typically located at ``/etc/ironic/ironic.conf``. +The `Install and configure components`_ section has been moved to the Bare +Metal service Install Guide. -Although some configuration options are mentioned here, it is recommended that -you review all the `available options `_ -so that the Bare Metal service is configured for your needs. - -It is possible to set up an ironic-api and an ironic-conductor services on the -same host or different hosts. Users also can add new ironic-conductor hosts -to deal with an increasing number of bare metal nodes. But the additional ironic-conductor -services should be at the same version as that of existing ironic-conductor services. - -Configuring ironic-api service ------------------------------- - -#. The Bare Metal service stores information in a database. This guide uses the - MySQL database that is used by other OpenStack services. - - Configure the location of the database via the ``connection`` option. In the - following, replace IRONIC_DBPASSWORD with the password of your ``ironic`` - user, and replace DB_IP with the IP address where the DB server is located:: - - [database] - ... - # The SQLAlchemy connection string used to connect to the - # database (string value) - connection = mysql+pymysql://ironic:IRONIC_DBPASSWORD@DB_IP/ironic?charset=utf8 - -#. Configure the ironic-api service to use the RabbitMQ message broker by - setting one or more of these options. Replace RABBIT_HOST with the - address of the RabbitMQ server:: - - [DEFAULT] - ... - # The messaging driver to use, defaults to rabbit. Other - # drivers include qpid and zmq. (string value) - #rpc_backend=rabbit - - [oslo_messaging_rabbit] - ... - # The RabbitMQ broker address where a single node is used - # (string value) - rabbit_host=RABBIT_HOST - - # The RabbitMQ userid (string value) - #rabbit_userid=guest - - # The RabbitMQ password (string value) - #rabbit_password=guest - -#. Configure the ironic-api service to use these credentials with the Identity - service. Replace IDENTITY_IP with the IP of the Identity server, and - replace IRONIC_PASSWORD with the password you chose for the ``ironic`` - user in the Identity service:: - - [DEFAULT] - ... - # Authentication strategy used by ironic-api: one of - # "keystone" or "noauth". "noauth" should not be used in a - # production environment because all authentication will be - # disabled. (string value) - auth_strategy=keystone - - [keystone_authtoken] - ... - # Authentication type to load (string value) - auth_type = v3password - - # Complete public Identity API endpoint (string value) - auth_uri=http://PUBLIC_IDENTITY_IP:5000/v3/ - - # Complete admin Identity API endpoint. (string value) - auth_url=http://PRIVATE_IDENTITY_IP:35357/v3/ - - # Service username. (string value) - admin_user=ironic - - # Service account password. (string value) - admin_password=IRONIC_PASSWORD - - # Service tenant name. (string value) - admin_tenant_name=service - -#. Create the Bare Metal service database tables:: - - ironic-dbsync --config-file /etc/ironic/ironic.conf create_schema - -#. Restart the ironic-api service:: - - Fedora/RHEL7/CentOS7: - sudo systemctl restart openstack-ironic-api - - Ubuntu: - sudo service ironic-api restart - - -Configuring ironic-conductor service ------------------------------------- - -#. Replace HOST_IP with IP of the conductor host, and replace DRIVERS with a - comma-separated list of drivers you chose for the conductor service as - follows:: - - [DEFAULT] - ... - # IP address of this host. If unset, will determine the IP - # programmatically. If unable to do so, will use "127.0.0.1". - # (string value) - my_ip = HOST_IP - - # Specify the list of drivers to load during service - # initialization. Missing drivers, or drivers which fail to - # initialize, will prevent the conductor service from - # starting. The option default is a recommended set of - # production-oriented drivers. A complete list of drivers - # present on your system may be found by enumerating the - # "ironic.drivers" entrypoint. An example may be found in the - # developer documentation online. (list value) - enabled_drivers=DRIVERS - - .. note:: - If a conductor host has multiple IPs, ``my_ip`` should - be set to the IP which is on the same network as the bare metal nodes. - -#. Configure the ironic-api service URL. Replace IRONIC_API_IP with IP of - ironic-api service as follows:: - - [conductor] - ... - # URL of Ironic API service. If not set ironic can get the - # current value from the keystone service catalog. (string - # value) - api_url=http://IRONIC_API_IP:6385 - -#. Configure the location of the database. Ironic-conductor should use the same - configuration as ironic-api. Replace IRONIC_DBPASSWORD with the password of - your ``ironic`` user, and replace DB_IP with the IP address where the DB server - is located:: - - [database] - ... - # The SQLAlchemy connection string to use to connect to the - # database. (string value) - connection = mysql+pymysql://ironic:IRONIC_DBPASSWORD@DB_IP/ironic?charset=utf8 - -#. Configure the ironic-conductor service to use the RabbitMQ message broker by - setting one or more of these options. Ironic-conductor should use the same - configuration as ironic-api. Replace RABBIT_HOST with the address of the RabbitMQ - server:: - - [DEFAULT] - ... - # The messaging driver to use, defaults to rabbit. Other - # drivers include qpid and zmq. (string value) - #rpc_backend=rabbit - - [oslo_messaging_rabbit] - ... - # The RabbitMQ broker address where a single node is used. - # (string value) - rabbit_host=RABBIT_HOST - - # The RabbitMQ userid. (string value) - #rabbit_userid=guest - - # The RabbitMQ password. (string value) - #rabbit_password=guest - -#. Configure the ironic-conductor service so that it can communicate with the - Image service. Replace GLANCE_IP with the hostname or IP address of - the Image service:: - - [glance] - ... - # Default glance hostname or IP address. (string value) - glance_host=GLANCE_IP - - .. note:: - Swift backend for the Image service should be installed and configured - for ``agent_*`` drivers. Starting with Mitaka the Bare Metal service also - supports Ceph Object Gateway (RADOS Gateway) as the Image service's backend - (:ref:`radosgw support`). - -#. Set the URL (replace NEUTRON_IP) for connecting to the Networking service, - to be the Networking service endpoint:: - - [neutron] - ... - # URL for connecting to neutron. (string value) - url=http://NEUTRON_IP:9696 - - To configure the network for ironic-conductor service to perform node cleaning, see - `CleaningNetworkSetup`_. - -#. Configure the ironic-conductor service to use these credentials with the Identity - service. Ironic-conductor should use the same configuration as ironic-api. - Replace IDENTITY_IP with the IP of the Identity server, and replace IRONIC_PASSWORD - with the password you chose for the ``ironic`` user in the Identity service:: - - [keystone_authtoken] - ... - # Complete public Identity API endpoint (string value) - auth_uri=http://IDENTITY_IP:5000/ - - # Complete admin Identity API endpoint. This should specify - # the unversioned root endpoint e.g. https://localhost:35357/ - # (string value) - identity_uri=http://IDENTITY_IP:35357/ - - # Service username. (string value) - admin_user=ironic - - # Service account password. (string value) - admin_password=IRONIC_PASSWORD - - # Service tenant name. (string value) - admin_tenant_name=service - -#. Make sure that ``qemu-img`` and ``iscsiadm`` (in the case of using iscsi-deploy driver) - binaries are installed and prepare the host system as described at - `Setup the drivers for the Bare Metal service`_ - -#. Restart the ironic-conductor service:: - - Fedora/RHEL7/CentOS7: - sudo systemctl restart openstack-ironic-conductor - - Ubuntu: - sudo service ironic-conductor restart - - -Configuring ironic-api behind mod_wsgi --------------------------------------- - -Bare Metal service comes with an example file for configuring the -``ironic-api`` service to run behind Apache with mod_wsgi. - -1. Install the apache service:: - - Fedora 21/RHEL7/CentOS7: - sudo yum install httpd - - Fedora 22 (or higher): - sudo dnf install httpd - - Debian/Ubuntu: - apt-get install apache2 - - -2. Copy the ``etc/apache2/ironic`` file under the apache sites:: - - Fedora/RHEL7/CentOS7: - sudo cp etc/apache2/ironic /etc/httpd/conf.d/ironic.conf - - Debian/Ubuntu: - sudo cp etc/apache2/ironic /etc/apache2/sites-available/ironic.conf - - -3. Edit the recently copied ``/ironic.conf``: - - - Modify the ``WSGIDaemonProcess``, ``APACHE_RUN_USER`` and - ``APACHE_RUN_GROUP`` directives to set the user and group values to - an appropriate user on your server. - - - Modify the ``WSGIScriptAlias`` directive to point to the - *ironic/api/app.wsgi* script. - - - Modify the ``Directory`` directive to set the path to the Ironic API code. - - - Modify the ``ErrorLog`` and ``CustomLog`` to redirect the logs - to the right directory (on Red Hat systems this is usually under - /var/log/httpd). - -4. Enable the apache ``ironic`` in site and reload:: - - Fedora/RHEL7/CentOS7: - sudo systemctl reload httpd - - Debian/Ubuntu: - sudo a2ensite ironic - sudo service apache2 reload - - -.. note:: - The file ironic/api/app.wsgi is installed with the rest of the Bare Metal - service application code, and should not need to be modified. +.. _`Install and configure components`: http://docs.openstack.org/project-install-guide/baremetal/draft/install-ubuntu.html#install-and-configure-components Configure Compute to use the Bare Metal service diff --git a/install-guide/source/configure-integration.rst b/install-guide/source/configure-integration.rst new file mode 100644 index 0000000000..d9dfe0f245 --- /dev/null +++ b/install-guide/source/configure-integration.rst @@ -0,0 +1,7 @@ +========================================= +Integration with other OpenStack services +========================================= + +.. include:: include/configure-identity.rst + +.. include:: include/configure-nova-compute.rst diff --git a/install-guide/source/include/common-configure.rst b/install-guide/source/include/common-configure.rst new file mode 100644 index 0000000000..3536ebe5fd --- /dev/null +++ b/install-guide/source/include/common-configure.rst @@ -0,0 +1,12 @@ +The Bare Metal service is configured via its configuration file. This file +is typically located at ``/etc/ironic/ironic.conf``. + +Although some configuration options are mentioned here, it is recommended that +you review all the `available options `_ +so that the Bare Metal service is configured for your needs. + +It is possible to set up an ironic-api and an ironic-conductor services on the +same host or different hosts. Users also can add new ironic-conductor hosts +to deal with an increasing number of bare metal nodes. But the additional +ironic-conductor services should be at the same version as that of existing +ironic-conductor services. diff --git a/install-guide/source/include/common-prerequisites.rst b/install-guide/source/include/common-prerequisites.rst index a6701b8f41..edaca46d05 100644 --- a/install-guide/source/include/common-prerequisites.rst +++ b/install-guide/source/include/common-prerequisites.rst @@ -1,6 +1,29 @@ -Prerequisites -------------- +Install and configure prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Before you install and configure the Bare Metal service, -you must follow the `install and configure the prerequisites `_ -section of the legacy installation guide. +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. + +It assumes that the Identity, Image, Compute, and Networking services +have already been set up. + + +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: + + .. code-block:: console + + # mysql -u root -p + mysql> CREATE DATABASE ironic CHARACTER SET utf8; + mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'localhost' \ + IDENTIFIED BY 'IRONIC_DBPASSWORD'; + mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'%' \ + IDENTIFIED BY 'IRONIC_DBPASSWORD'; diff --git a/install-guide/source/include/configure-identity.rst b/install-guide/source/include/configure-identity.rst new file mode 100644 index 0000000000..d2788e6eed --- /dev/null +++ b/install-guide/source/include/configure-identity.rst @@ -0,0 +1,93 @@ +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: + + .. code-block:: console + + $ openstack user create --password IRONIC_PASSWORD \ + --email ironic@example.com ironic + $ openstack role add --project service --user ironic admin + +#. You must register the Bare Metal service with the Identity service so that + other OpenStack services can locate it. To register the service: + + .. code-block:: console + + $ openstack service create --name ironic --description \ + "Ironic baremetal provisioning service" baremetal + +#. 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: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + baremetal admin http://$IRONIC_NODE:6385 + $ openstack endpoint create --region RegionOne \ + baremetal public http://$IRONIC_NODE:6385 + $ openstack endpoint create --region RegionOne \ + baremetal internal http://$IRONIC_NODE:6385 + + If only keystone v2 API is available, use this command instead: + + .. code-block:: console + + $ openstack endpoint create --region RegionOne \ + --publicurl http://$IRONIC_NODE:6385 \ + --internalurl http://$IRONIC_NODE:6385 \ + --adminurl http://$IRONIC_NODE:6385 \ + baremetal + +#. You may delegate limited privileges related to the Bare Metal service + to your Users by creating Roles with the OpenStack Identity service. By + default, the Bare Metal service expects the "baremetal_admin" and + "baremetal_observer" Roles to exist, in addition to the default "admin" + Role. There is no negative consequence if you choose not to create these + Roles. They can be created with the following commands: + + .. code-block:: console + + $ openstack role create baremetal_admin + $ openstack role create baremetal_observer + + If you choose to customize the names of Roles used with the Bare Metal + service, do so by changing the "is_member", "is_observer", and "is_admin" + policy settings in ``/etc/ironic/policy.json``. + + More complete documentation on managing Users and Roles within your + OpenStack deployment are outside the scope of this document, but may be + found here_. + +#. You can further restrict access to the Bare Metal service by creating a + separate "baremetal" Project, so that Bare Metal resources (Nodes, Ports, + etc) are only accessible to members of this Project: + + .. code-block:: console + + $ openstack project create baremetal + + At this point, you may grant read-only access to the Bare Metal service API + without granting any other access by issuing the following commands: + + .. code-block:: console + + $ openstack user create \ + --domain default --project-domain default --project baremetal \ + --password PASSWORD USERNAME + $ openstack role add \ + --user-domain default --project-domain default --project baremetal \ + --user USERNAME baremetal_observer + +#. Further documentation is available elsewhere for the ``openstack`` + `command-line client`_ and the Identity_ service. A policy.json.sample_ + file, which enumerates the service's default policies, is provided for + your convenience with the Bare Metal Service. + +.. _Identity: http://docs.openstack.org/admin-guide/identity-management.html +.. _`command-line client`: http://docs.openstack.org/admin-guide/cli-manage-projects-users-and-roles.html +.. _here: http://docs.openstack.org/admin-guide/identity-concepts.html#user-management +.. _policy.json.sample: https://github.com/openstack/ironic/blob/master/etc/ironic/policy.json.sample diff --git a/install-guide/source/include/configure-ironic-api-mod_wsgi.rst b/install-guide/source/include/configure-ironic-api-mod_wsgi.rst new file mode 100644 index 0000000000..9b6a5da0dd --- /dev/null +++ b/install-guide/source/include/configure-ironic-api-mod_wsgi.rst @@ -0,0 +1,63 @@ +Configuring ironic-api behind mod_wsgi +-------------------------------------- + +Bare Metal service comes with an example file for configuring the +``ironic-api`` service to run behind Apache with mod_wsgi. + +#. Install the apache service: + + .. TODO(mmitchell): Split this based on operating system + .. code-block:: console + + Fedora 21/RHEL7/CentOS7: + sudo yum install httpd + + Fedora 22 (or higher): + sudo dnf install httpd + + Debian/Ubuntu: + apt-get install apache2 + + +#. Copy the ``etc/apache2/ironic`` file under the apache sites: + + .. TODO(mmitchell): Split this based on operating system + .. code-block:: console + + Fedora/RHEL7/CentOS7: + sudo cp etc/apache2/ironic /etc/httpd/conf.d/ironic.conf + + Debian/Ubuntu: + sudo cp etc/apache2/ironic /etc/apache2/sites-available/ironic.conf + + +#. Edit the recently copied ``/ironic.conf``: + + #. Modify the ``WSGIDaemonProcess``, ``APACHE_RUN_USER`` and + ``APACHE_RUN_GROUP`` directives to set the user and group values to + an appropriate user on your server. + + #. Modify the ``WSGIScriptAlias`` directive to point to the + ``ironic/api/app.wsgi`` script. + + #. Modify the ``Directory`` directive to set the path to the Ironic API code. + + #. Modify the ``ErrorLog`` and ``CustomLog`` to redirect the logs + to the right directory (on Red Hat systems this is usually under + /var/log/httpd). + +#. Enable the apache ``ironic`` in site and reload: + + .. TODO(mmitchell): Split this based on operating system + .. code-block:: console + + Fedora/RHEL7/CentOS7: + sudo systemctl reload httpd + + Debian/Ubuntu: + sudo a2ensite ironic + sudo service apache2 reload + +.. note:: + The file ``ironic/api/app.wsgi`` is installed with the rest of the Bare Metal + service application code, and should not need to be modified. diff --git a/install-guide/source/include/configure-ironic-api.rst b/install-guide/source/include/configure-ironic-api.rst new file mode 100644 index 0000000000..2b949c5907 --- /dev/null +++ b/install-guide/source/include/configure-ironic-api.rst @@ -0,0 +1,95 @@ +Configuring ironic-api service +------------------------------ + +#. The Bare Metal service stores information in a database. This guide uses the + MySQL database that is used by other OpenStack services. + + Configure the location of the database via the ``connection`` option. In the + following, replace ``IRONIC_DBPASSWORD`` with the password of your + ``ironic`` user, and replace ``DB_IP`` with the IP address where the DB + server is located: + + .. code-block:: ini + + [database] + + # The SQLAlchemy connection string used to connect to the + # database (string value) + connection=mysql+pymysql://ironic:IRONIC_DBPASSWORD@DB_IP/ironic?charset=utf8 + +#. Configure the ironic-api service to use the RabbitMQ message broker by + setting one or more of these options. Replace ``RABBIT_HOST`` with the + address of the RabbitMQ server: + + .. code-block:: ini + + [DEFAULT] + + # The messaging driver to use, defaults to rabbit. Other + # drivers include qpid and zmq. (string value) + #rpc_backend=rabbit + + [oslo_messaging_rabbit] + + # The RabbitMQ broker address where a single node is used + # (string value) + rabbit_host=RABBIT_HOST + + # The RabbitMQ userid (string value) + #rabbit_userid=guest + + # The RabbitMQ password (string value) + #rabbit_password=guest + +#. Configure the ironic-api service to use these credentials with the Identity + service. Replace ``PUBLIC_IDENTITY_IP`` with the public IP of the Identity + server, ``PRIVATE_IDENTITY_IP`` with the private IP of the Identity server + and replace ``IRONIC_PASSWORD`` with the password you chose for the + ``ironic`` user in the Identity service: + + .. code-block:: ini + + [DEFAULT] + + # Authentication strategy used by ironic-api: one of + # "keystone" or "noauth". "noauth" should not be used in a + # production environment because all authentication will be + # disabled. (string value) + auth_strategy=keystone + + [keystone_authtoken] + + # Authentication type to load (string value) + auth_type=v3password + + # Complete public Identity API endpoint (string value) + auth_uri=http://PUBLIC_IDENTITY_IP:5000/v3/ + + # Complete admin Identity API endpoint. (string value) + auth_url=http://PRIVATE_IDENTITY_IP:35357/v3/ + + # Service username. (string value) + admin_user=ironic + + # Service account password. (string value) + admin_password=IRONIC_PASSWORD + + # Service tenant name. (string value) + admin_tenant_name=service + +#. Create the Bare Metal service database tables: + + .. code-block:: bash + + $ ironic-dbsync --config-file /etc/ironic/ironic.conf create_schema + +#. Restart the ironic-api service: + + .. TODO(mmitchell): Split this based on operating system + .. code-block:: console + + Fedora/RHEL7/CentOS7: + sudo systemctl restart openstack-ironic-api + + Ubuntu: + sudo service ironic-api restart diff --git a/install-guide/source/include/configure-ironic-conductor.rst b/install-guide/source/include/configure-ironic-conductor.rst new file mode 100644 index 0000000000..7b8fefda5e --- /dev/null +++ b/install-guide/source/include/configure-ironic-conductor.rst @@ -0,0 +1,152 @@ +Configuring ironic-conductor service +------------------------------------ + +#. Replace ``HOST_IP`` with IP of the conductor host, and replace ``DRIVERS`` + with a comma-separated list of drivers you chose for the conductor service + as follows: + + .. code-block:: ini + + [DEFAULT] + + # IP address of this host. If unset, will determine the IP + # programmatically. If unable to do so, will use "127.0.0.1". + # (string value) + my_ip=HOST_IP + + # Specify the list of drivers to load during service + # initialization. Missing drivers, or drivers which fail to + # initialize, will prevent the conductor service from + # starting. The option default is a recommended set of + # production-oriented drivers. A complete list of drivers + # present on your system may be found by enumerating the + # "ironic.drivers" entrypoint. An example may be found in the + # developer documentation online. (list value) + enabled_drivers=DRIVERS + + .. note:: + If a conductor host has multiple IPs, ``my_ip`` should + be set to the IP which is on the same network as the bare metal nodes. + +#. Configure the ironic-api service URL. Replace ``IRONIC_API_IP`` with IP of + ironic-api service as follows: + + .. code-block:: ini + + [conductor] + + # URL of Ironic API service. If not set ironic can get the + # current value from the keystone service catalog. (string + # value) + api_url=http://IRONIC_API_IP:6385 + +#. Configure the location of the database. Ironic-conductor should use the same + configuration as ironic-api. Replace ``IRONIC_DBPASSWORD`` with the password + of your ``ironic`` user, and replace DB_IP with the IP address where the DB + server is located: + + .. code-block:: ini + + [database] + + # The SQLAlchemy connection string to use to connect to the + # database. (string value) + connection=mysql+pymysql://ironic:IRONIC_DBPASSWORD@DB_IP/ironic?charset=utf8 + +#. Configure the ironic-conductor service to use the RabbitMQ message broker by + setting one or more of these options. Ironic-conductor should use the same + configuration as ironic-api. Replace ``RABBIT_HOST`` with the address of the + RabbitMQ server: + + .. code-block:: ini + + [DEFAULT] + + # The messaging driver to use, defaults to rabbit. Other + # drivers include qpid and zmq. (string value) + #rpc_backend=rabbit + + [oslo_messaging_rabbit] + + # The RabbitMQ broker address where a single node is used. + # (string value) + rabbit_host=RABBIT_HOST + + # The RabbitMQ userid. (string value) + #rabbit_userid=guest + + # The RabbitMQ password. (string value) + #rabbit_password=guest + +#. Configure the ironic-conductor service so that it can communicate with the + Image service. Replace ``GLANCE_IP`` with the hostname or IP address of + the Image service: + + .. code-block:: ini + + [glance] + + # Default glance hostname or IP address. (string value) + glance_host=GLANCE_IP + + .. note:: + Swift backend for the Image service should be installed and configured + for ``agent_*`` drivers. Starting with Mitaka the Bare Metal service also + supports Ceph Object Gateway (RADOS Gateway) as the Image service's backend + (`radosgw support `_). + +#. Set the URL (replace ``NEUTRON_IP``) for connecting to the Networking + service, to be the Networking service endpoint: + + .. code-block:: ini + + [neutron] + + # URL for connecting to neutron. (string value) + url=http://NEUTRON_IP:9696 + + To configure the network for ironic-conductor service to perform node + cleaning, see `CleaningNetworkSetup `_ + from the Ironic deploy guide. + +#. Configure the ironic-conductor service to use these credentials with the + Identity service. Ironic-conductor should use the same configuration as + ironic-api. Replace ``IDENTITY_IP`` with the IP of the Identity server, + and replace ``IRONIC_PASSWORD`` with the password you chose for the + ``ironic`` user in the Identity service: + + .. code-block:: ini + + [keystone_authtoken] + + # Complete public Identity API endpoint (string value) + auth_uri=http://IDENTITY_IP:5000/ + + # Complete admin Identity API endpoint. This should specify + # the unversioned root endpoint e.g. https://localhost:35357/ + # (string value) + identity_uri=http://IDENTITY_IP:35357/ + + # Service username. (string value) + admin_user=ironic + + # Service account password. (string value) + admin_password=IRONIC_PASSWORD + + # Service tenant name. (string value) + admin_tenant_name=service + +#. Make sure that ``qemu-img`` and ``iscsiadm`` (in the case of using iscsi-deploy driver) + binaries are installed and prepare the host system as described at + `Setup the drivers for the Bare Metal service `_ + +#. Restart the ironic-conductor service: + + .. TODO(mmitchell): Split this based on operating system + .. code-block:: console + + Fedora/RHEL7/CentOS7: + sudo systemctl restart openstack-ironic-conductor + + Ubuntu: + sudo service ironic-conductor restart diff --git a/install-guide/source/include/configure-nova-compute.rst b/install-guide/source/include/configure-nova-compute.rst new file mode 100644 index 0000000000..1f2219c154 --- /dev/null +++ b/install-guide/source/include/configure-nova-compute.rst @@ -0,0 +1,7 @@ +Configure Compute to use the Bare Metal service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please read the `Configure Compute to use the Bare Metal service`_ section from +the legacy installation guide. + +.. _`Configure Compute to use the Bare Metal service`: http://docs.openstack.org/developer/ironic/deploy/install-guide.html#configure-compute-to-use-the-bare-metal-service diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst index a3af6efb50..b917975d58 100644 --- a/install-guide/source/index.rst +++ b/install-guide/source/index.rst @@ -7,6 +7,7 @@ Bare Metal service get_started.rst install.rst + configure-integration.rst verify.rst next-steps.rst diff --git a/install-guide/source/install-obs.rst b/install-guide/source/install-obs.rst index 96b1e30c2d..948c2e64c2 100644 --- a/install-guide/source/install-obs.rst +++ b/install-guide/source/install-obs.rst @@ -1,15 +1,16 @@ .. _install-obs: - +============================================================ Install and configure for openSUSE and SUSE Linux Enterprise -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================================================ This section describes how to install and configure the Bare Metal service for openSUSE Leap 42.1 and SUSE Linux Enterprise Server 12 SP1. -.. include:: include/common-prerequisites.rst - -Install and configure components --------------------------------- - -Please follow the `Install the Bare Metal service `_ section of the legacy installation guide. +.. note:: + Installation of the Bare Metal service on openSUSE and SUSE Linux Enterprise + Server is not officially supported. Nevertheless, installation should be + possible by following the general steps from another operating system, such + as :ref:`Red Hat Enterprise Linux `. The instructions might + need adjustments, especially around package manager instructions and system + paths. diff --git a/install-guide/source/install-rdo.rst b/install-guide/source/install-rdo.rst index a24d4d45eb..1c2d082148 100644 --- a/install-guide/source/install-rdo.rst +++ b/install-guide/source/install-rdo.rst @@ -1,7 +1,8 @@ .. _install-rdo: +============================================================= Install and configure for Red Hat Enterprise Linux and CentOS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================================================= This section describes how to install and configure the Bare Metal service @@ -10,6 +11,33 @@ for Red Hat Enterprise Linux 7 and CentOS 7. .. include:: include/common-prerequisites.rst Install and configure components --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Please follow the `Install the Bare Metal service `_ section of the legacy installation guide. +#. Install from packages + + - Using ``dnf`` + + .. code-block:: console + + # dnf install openstack-ironic-api openstack-ironic-conductor python-ironicclient + + - Using ``yum`` + + .. code-block:: console + + # yum install openstack-ironic-api openstack-ironic-conductor python-ironicclient + +#. Enable services + + .. code-block:: console + + # systemctl enable openstack-ironic-api openstack-ironic-conductor + # systemctl start openstack-ironic-api openstack-ironic-conductor + +.. include:: include/common-configure.rst + +.. include:: include/configure-ironic-api.rst + +.. include:: include/configure-ironic-api-mod_wsgi.rst + +.. include:: include/configure-ironic-conductor.rst diff --git a/install-guide/source/install-ubuntu.rst b/install-guide/source/install-ubuntu.rst index 459898a07d..28dbd6b035 100644 --- a/install-guide/source/install-ubuntu.rst +++ b/install-guide/source/install-ubuntu.rst @@ -1,7 +1,8 @@ .. _install-ubuntu: +================================ Install and configure for Ubuntu -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================ This section describes how to install and configure the Bare Metal service for Ubuntu 14.04 (LTS). @@ -9,6 +10,22 @@ service for Ubuntu 14.04 (LTS). .. include:: include/common-prerequisites.rst Install and configure components --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Please follow the `Install the Bare Metal service `_ section of the legacy installation guide. +#. Install from packages (using apt-get) + + .. code-block:: console + + # apt-get install ironic-api ironic-conductor python-ironicclient + +#. Enable services + + Services are enabled by default on Ubuntu. + +.. include:: include/common-configure.rst + +.. include:: include/configure-ironic-api.rst + +.. include:: include/configure-ironic-api-mod_wsgi.rst + +.. include:: include/configure-ironic-conductor.rst diff --git a/install-guide/source/install.rst b/install-guide/source/install.rst index e379330b9c..75a9b8f39a 100644 --- a/install-guide/source/install.rst +++ b/install-guide/source/install.rst @@ -1,7 +1,7 @@ .. _install: -Install and configure -~~~~~~~~~~~~~~~~~~~~~ +Install and configure the Bare Metal service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section describes how to install and configure the Bare Metal service, code-named ironic. @@ -11,6 +11,6 @@ Note that installation and configuration vary by distribution. .. toctree:: :maxdepth: 2 - install-obs.rst install-rdo.rst install-ubuntu.rst + install-obs.rst diff --git a/install-guide/source/next-steps.rst b/install-guide/source/next-steps.rst index 84223e66bb..3f44bd2dfd 100644 --- a/install-guide/source/next-steps.rst +++ b/install-guide/source/next-steps.rst @@ -1,6 +1,7 @@ .. _next-steps: +========== Next steps -~~~~~~~~~~ +========== Your OpenStack environment now includes the Bare Metal service. diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst index 37c2762421..5a3b96278a 100644 --- a/install-guide/source/verify.rst +++ b/install-guide/source/verify.rst @@ -1,7 +1,8 @@ .. _verify: +================ Verify operation -~~~~~~~~~~~~~~~~ +================ To verify the operation of the Bare Metal service, please see the `Troubleshooting`_ section of the legacy installation guide.