diff options
Diffstat (limited to 'install-guide/source/include')
14 files changed, 1070 insertions, 0 deletions
diff --git a/install-guide/source/include/common-configure.rst b/install-guide/source/include/common-configure.rst new file mode 100644 index 000000000..3a2ead9b9 --- /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 <https://git.openstack.org/cgit/openstack/ironic/tree/etc/ironic/ironic.conf.sample?stable%2Fnewton>`_ +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 new file mode 100644 index 000000000..edaca46d0 --- /dev/null +++ b/install-guide/source/include/common-prerequisites.rst @@ -0,0 +1,29 @@ +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. + +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-glance-images.rst b/install-guide/source/include/configure-glance-images.rst new file mode 100644 index 000000000..9b6213559 --- /dev/null +++ b/install-guide/source/include/configure-glance-images.rst @@ -0,0 +1,114 @@ +.. _image-requirements: + +Create and add images to the Image service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bare Metal provisioning requires two sets of images: the deploy images +and the user images. The deploy images are used by the Bare Metal service +to prepare the bare metal server for actual OS deployment. Whereas the +user images are installed on the bare metal server to be used by the +end user. Below are the steps to create the required images and add +them to the Image service: + +#. The `disk-image-builder`_ can be used to create images required for + deployment and the actual OS which the user is going to run. + + .. _disk-image-builder: http://docs.openstack.org/developer/diskimage-builder/ + + - Install diskimage-builder package (use virtualenv, if you don't + want to install anything globally): + + .. code-block:: console + + # pip install diskimage-builder + + - Build the image your users will run (Ubuntu image has been taken as + an example): + + - Partition images + + .. code-block:: console + + $ disk-image-create ubuntu baremetal dhcp-all-interfaces grub2 -o my-image + + + - Whole disk images + + .. code-block:: console + + $ disk-image-create ubuntu vm dhcp-all-interfaces -o my-image + + The partition image command creates ``my-image.qcow2``, + ``my-image.vmlinuz`` and ``my-image.initrd`` files. The ``grub2`` element + in the partition image creation command is only needed if local boot will + be used to deploy ``my-image.qcow2``, otherwise the images + ``my-image.vmlinuz`` and ``my-image.initrd`` will be used for PXE booting + after deploying the bare metal with ``my-image.qcow2``. + + If you want to use Fedora image, replace ``ubuntu`` with ``fedora`` in the + chosen command. + + .. note:: To build the deploy image take a look at the :ref:`deploy-ramdisk` + section. + +#. Add the user images to the Image service + + Load all the images created in the below steps into the Image service, + and note the image UUIDs in the Image service for each one as it is + generated. + + - Add the kernel and ramdisk images to the Image service: + + .. code-block:: console + + $ glance image-create --name my-kernel --visibility public \ + --disk-format aki --container-format aki < my-image.vmlinuz + + Store the image uuid obtained from the above step as ``MY_VMLINUZ_UUID``. + + .. code-block:: console + + $ glance image-create --name my-image.initrd --visibility public \ + --disk-format ari --container-format ari < my-image.initrd + + Store the image UUID obtained from the above step as ``MY_INITRD_UUID``. + + - Add the *my-image* to the Image service which is going to be the OS + that the user is going to run. Also associate the above created + images with this OS image. These two operations can be done by + executing the following command: + + .. code-block:: console + + $ glance image-create --name my-image --visibility public \ + --disk-format qcow2 --container-format bare --property \ + kernel_id=$MY_VMLINUZ_UUID --property \ + ramdisk_id=$MY_INITRD_UUID < my-image.qcow2 + + .. note:: To deploy a whole disk image, a kernel_id and a ramdisk_id + shouldn't be associated with the image. For example, + + .. code-block:: console + + $ glance image-create --name my-whole-disk-image --visibility public \ + --disk-format qcow2 \ + --container-format bare < my-whole-disk-image.qcow2 + +#. Add the deploy images to the Image service + + Add the *my-deploy-ramdisk.kernel* and *my-deploy-ramdisk.initramfs* images + to the Image service: + + .. code-block:: console + + $ glance image-create --name deploy-vmlinuz --visibility public \ + --disk-format aki --container-format aki < my-deploy-ramdisk.kernel + + Store the image UUID obtained from the above step as ``DEPLOY_VMLINUZ_UUID``. + + .. code-block:: console + + $ glance image-create --name deploy-initrd --visibility public \ + --disk-format ari --container-format ari < my-deploy-ramdisk.initramfs + + Store the image UUID obtained from the above step as ``DEPLOY_INITRD_UUID``. diff --git a/install-guide/source/include/configure-identity.rst b/install-guide/source/include/configure-identity.rst new file mode 100644 index 000000000..d2788e6ee --- /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 000000000..9b6a5da0d --- /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 ``<apache-configuration-dir>/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 000000000..2b949c590 --- /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 000000000..79c01bf7f --- /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 <http://docs.openstack.org/developer/ironic/newton/deploy/radosgw.html#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 <http://docs.openstack.org/developer/ironic/newton/deploy/cleaning.html>`_ + 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 <http://docs.openstack.org/developer/ironic/newton/deploy/install-guide.html#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-neutron-networks.rst b/install-guide/source/include/configure-neutron-networks.rst new file mode 100644 index 000000000..0c2339a27 --- /dev/null +++ b/install-guide/source/include/configure-neutron-networks.rst @@ -0,0 +1,111 @@ +.. _configure-networking: + +Configure Networking to communicate with the bare metal server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You need to configure Networking so that the bare metal server can communicate +with the Networking service for DHCP, PXE boot and other requirements. +This section covers configuring Networking for a single flat network for bare +metal provisioning. + +You will also need to provide Bare Metal service with the MAC address(es) of +each node that it is provisioning; Bare Metal service in turn will pass this +information to Networking service for DHCP and PXE boot configuration. +An example of this is shown in the :ref:`enrollment` section. + +#. Edit ``/etc/neutron/plugins/ml2/ml2_conf.ini`` and modify these: + + .. code-block:: ini + + [ml2] + type_drivers = flat + tenant_network_types = flat + mechanism_drivers = openvswitch + + [ml2_type_flat] + flat_networks = physnet1 + + [securitygroup] + firewall_driver = neutron.agent.linux.iptables_firewall.OVSHybridIptablesFirewallDriver + enable_security_group = True + + [ovs] + bridge_mappings = physnet1:br-eth2 + # Replace eth2 with the interface on the neutron node which you + # are using to connect to the bare metal server + +#. If neutron-openvswitch-agent runs with ``ovs_neutron_plugin.ini`` as the input + config-file, edit ``ovs_neutron_plugin.ini`` to configure the bridge mappings + by adding the [ovs] section described in the previous step, and restart the + neutron-openvswitch-agent. + +#. Add the integration bridge to Open vSwitch: + + .. code-block:: console + + $ ovs-vsctl add-br br-int + +#. Create the br-eth2 network bridge to handle communication between the + OpenStack services (and the Bare Metal services) and the bare metal nodes + using eth2. + Replace eth2 with the interface on the network node which you are using to + connect to the Bare Metal service: + + .. code-block:: console + + $ ovs-vsctl add-br br-eth2 + $ ovs-vsctl add-port br-eth2 eth2 + +#. Restart the Open vSwitch agent: + + .. code-block:: console + + # service neutron-plugin-openvswitch-agent restart + +#. On restarting the Networking service Open vSwitch agent, the veth pair + between the bridges br-int and br-eth2 is automatically created. + + Your Open vSwitch bridges should look something like this after + following the above steps: + + .. code-block:: console + + $ ovs-vsctl show + + Bridge br-int + fail_mode: secure + Port "int-br-eth2" + Interface "int-br-eth2" + type: patch + options: {peer="phy-br-eth2"} + Port br-int + Interface br-int + type: internal + Bridge "br-eth2" + Port "phy-br-eth2" + Interface "phy-br-eth2" + type: patch + options: {peer="int-br-eth2"} + Port "eth2" + Interface "eth2" + Port "br-eth2" + Interface "br-eth2" + type: internal + ovs_version: "2.3.0" + +#. Create the flat network on which you are going to launch the + instances: + + .. code-block:: console + + $ neutron net-create --tenant-id $TENANT_ID sharednet1 --shared \ + --provider:network_type flat --provider:physical_network physnet1 + +#. Create the subnet on the newly created network: + + .. code-block:: console + + $ neutron subnet-create sharednet1 $NETWORK_CIDR --name $SUBNET_NAME \ + --ip-version=4 --gateway=$GATEWAY_IP --allocation-pool \ + start=$START_IP,end=$END_IP --enable-dhcp + 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 000000000..6198bd038 --- /dev/null +++ b/install-guide/source/include/configure-nova-compute.rst @@ -0,0 +1,112 @@ +Configure Compute to use the Bare Metal service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Compute service needs to be configured to use the Bare Metal service's +driver. The configuration file for the Compute service is typically located at +``/etc/nova/nova.conf``. + +.. note:: + This configuration file must be modified on the Compute service's + controller nodes and compute nodes. + +#. Change these configuration options in the ``default`` section, as follows: + + .. code-block:: ini + + [default] + + # Driver to use for controlling virtualization. Options + # include: libvirt.LibvirtDriver, xenapi.XenAPIDriver, + # fake.FakeDriver, baremetal.BareMetalDriver, + # vmwareapi.VMwareESXDriver, vmwareapi.VMwareVCDriver (string + # value) + #compute_driver=<None> + compute_driver=ironic.IronicDriver + + # Firewall driver (defaults to hypervisor specific iptables + # driver) (string value) + #firewall_driver=<None> + firewall_driver=nova.virt.firewall.NoopFirewallDriver + + # The scheduler host manager class to use (string value) + #scheduler_host_manager=host_manager + scheduler_host_manager=ironic_host_manager + + # Virtual ram to physical ram allocation ratio which affects + # all ram filters. This configuration specifies a global ratio + # for RamFilter. For AggregateRamFilter, it will fall back to + # this configuration value if no per-aggregate setting found. + # (floating point value) + #ram_allocation_ratio=1.5 + ram_allocation_ratio=1.0 + + # Amount of disk in MB to reserve for the host (integer value) + #reserved_host_disk_mb=0 + reserved_host_memory_mb=0 + + # Flag to decide whether to use baremetal_scheduler_default_filters or not. + # (boolean value) + #scheduler_use_baremetal_filters=False + scheduler_use_baremetal_filters=True + + # Determines if the Scheduler tracks changes to instances to help with + # its filtering decisions (boolean value) + #scheduler_tracks_instance_changes=True + scheduler_tracks_instance_changes=False + + # New instances will be scheduled on a host chosen randomly from a subset + # of the N best hosts, where N is the value set by this option. Valid + # values are 1 or greater. Any value less than one will be treated as 1. + # For ironic, this should be set to a number >= the number of ironic nodes + # to more evenly distribute instances across the nodes. + #scheduler_host_subset_size=1 + scheduler_host_subset_size=9999999 + +#. Change these configuration options in the ``ironic`` section. + Replace: + + - ``IRONIC_PASSWORD`` with the password you chose for the ``ironic`` + user in the Identity Service + - ``IRONIC_NODE`` with the hostname or IP address of the ironic-api node + - ``IDENTITY_IP`` with the IP of the Identity server + + .. code-block:: ini + + [ironic] + + # Ironic keystone admin name + admin_username=ironic + + #Ironic keystone admin password. + admin_password=IRONIC_PASSWORD + + # keystone API endpoint + admin_url=http://IDENTITY_IP:35357/v2.0 + + # Ironic keystone tenant name. + admin_tenant_name=service + + # URL for Ironic API endpoint. + api_endpoint=http://IRONIC_NODE:6385/v1 + +#. On the Compute service's controller nodes, restart the ``nova-scheduler`` + process: + + .. code-block:: console + + Fedora/RHEL7/CentOS7: + sudo systemctl restart openstack-nova-scheduler + + Ubuntu: + sudo service nova-scheduler restart + +#. On the Compute service's compute nodes, restart the ``nova-compute`` + process: + + .. code-block:: console + + Fedora/RHEL7/CentOS7: + sudo systemctl restart openstack-nova-compute + + Ubuntu: + sudo service nova-compute restart diff --git a/install-guide/source/include/configure-nova-flavors.rst b/install-guide/source/include/configure-nova-flavors.rst new file mode 100644 index 000000000..62cf42a9b --- /dev/null +++ b/install-guide/source/include/configure-nova-flavors.rst @@ -0,0 +1,39 @@ +.. _flavor-creation: + +Create Compute flavors for use with the Bare Metal service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You'll need to create a special bare metal flavor in the Compute service. +The flavor is mapped to the bare metal node through the hardware specifications. + +#. Change these to match your hardware: + + .. code-block:: console + + $ RAM_MB=1024 + $ CPU=2 + $ DISK_GB=100 + $ ARCH={i686|x86_64} + +#. Create the bare metal flavor by executing the following command: + + .. code-block:: console + + $ nova flavor-create my-baremetal-flavor auto $RAM_MB $DISK_GB $CPU + + .. note:: You can replace ``auto`` with your own flavor id. + +#. Set the architecture as extra_specs information of the flavor. This + will be used to match against the properties of bare metal nodes: + + .. code-block:: console + + $ nova flavor-key my-baremetal-flavor set cpu_arch=$ARCH + +#. Associate the deploy ramdisk and kernel images with the ironic node: + + .. code-block:: console + + $ ironic node-update $NODE_UUID add \ + driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \ + driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID diff --git a/install-guide/source/include/kernel-boot-parameters.rst b/install-guide/source/include/kernel-boot-parameters.rst new file mode 100644 index 000000000..7ecf85eff --- /dev/null +++ b/install-guide/source/include/kernel-boot-parameters.rst @@ -0,0 +1,69 @@ +.. _kernel-boot-parameters: + +Appending kernel parameters to boot instances +--------------------------------------------- + +The Bare Metal service supports passing custom kernel parameters to boot instances to fit +users' requirements. The way to append the kernel parameters is depending on how to boot instances. + + +Network boot +============ + +Currently, the Bare Metal service supports assigning unified kernel parameters to PXE +booted instances by: + +* Modifying the ``[pxe]/pxe_append_params`` configuration option, for example:: + + [pxe] + + pxe_append_params = quiet splash + +* Copying a template from shipped templates to another place, for example:: + + https://git.openstack.org/cgit/openstack/ironic/tree/ironic/drivers/modules/pxe_config.template?stable%2Fnewton + + Making the modifications and pointing to the custom template via the configuration + options: ``[pxe]/pxe_config_template`` and ``[pxe]/uefi_pxe_config_template``. + + +Local boot +========== + +For local boot instances, users can make use of configuration drive +(see :ref:`configdrive`) to pass a custom +script to append kernel parameters when creating an instance. This is more +flexible and can vary per instance. +Here is an example for grub2 with ubuntu, users can customize it +to fit their use case: + + .. code:: python + + #!/usr/bin/env python + import os + + # Default grub2 config file in Ubuntu + grub_file = '/etc/default/grub' + # Add parameters here to pass to instance. + kernel_parameters = ['quiet', 'splash'] + grub_cmd = 'GRUB_CMDLINE_LINUX' + old_grub_file = grub_file+'~' + os.rename(grub_file, old_grub_file) + cmdline_existed = False + with open(grub_file, 'w') as writer, \ + open(old_grub_file, 'r') as reader: + for line in reader: + key = line.split('=')[0] + if key == grub_cmd: + #If there is already some value: + if line.strip()[-1] == '"': + line = line.strip()[:-1] + ' ' + ' '.join(kernel_parameters) + '"' + cmdline_existed = True + writer.write(line) + if not cmdline_existed: + line = grub_cmd + '=' + '"' + ' '.join(kernel_parameters) + '"' + writer.write(line) + + os.remove(old_grub_file) + os.system('update-grub') + os.system('reboot') diff --git a/install-guide/source/include/local-boot-partition-images.rst b/install-guide/source/include/local-boot-partition-images.rst new file mode 100644 index 000000000..a45c8e69b --- /dev/null +++ b/install-guide/source/include/local-boot-partition-images.rst @@ -0,0 +1,59 @@ +.. _local-boot-partition-images: + +Local boot with partition images +-------------------------------- + +Starting with the Kilo release, Bare Metal service supports local boot with +partition images, meaning that after the deployment the node's subsequent +reboots won't happen via PXE or Virtual Media. Instead, it will boot from a +local boot loader installed on the disk. + +It's important to note that in order for this to work the image being +deployed with Bare Metal service **must** contain ``grub2`` installed within it. + +Enabling the local boot is different when Bare Metal service is used with +Compute service and without it. +The following sections will describe both methods. + +.. note:: + The local boot feature is dependent upon a updated deploy ramdisk built + with diskimage-builder_ **version >= 0.1.42** or ironic-python-agent_ + in the kilo-era. + +.. _diskimage-builder: http://docs.openstack.org/developer/diskimage-builder/ +.. _ironic-python-agent: http://docs.openstack.org/developer/ironic-python-agent/newton/ + + +Enabling local boot with Compute service +======================================== + +To enable local boot we need to set a capability on the bare metal node, +for example:: + + ironic node-update <node-uuid> add properties/capabilities="boot_option:local" + + +Nodes having ``boot_option`` set to ``local`` may be requested by adding +an ``extra_spec`` to the Compute service flavor, for example:: + + nova flavor-key baremetal set capabilities:boot_option="local" + + +.. note:: + If the node is configured to use ``UEFI``, Bare Metal service will create + an ``EFI partition`` on the disk and switch the partition table format to + ``gpt``. The ``EFI partition`` will be used later by the boot loader + (which is installed from the deploy ramdisk). + +.. _local-boot-without-compute: + +Enabling local boot without Compute +=================================== + +Since adding ``capabilities`` to the node's properties is only used by +the nova scheduler to perform more advanced scheduling of instances, +we need a way to enable local boot when Compute is not present. To do that +we can simply specify the capability via the ``instance_info`` attribute +of the node, for example:: + + ironic node-update <node-uuid> add instance_info/capabilities='{"boot_option": "local"}' diff --git a/install-guide/source/include/root-device-hints.rst b/install-guide/source/include/root-device-hints.rst new file mode 100644 index 000000000..879371aba --- /dev/null +++ b/install-guide/source/include/root-device-hints.rst @@ -0,0 +1,51 @@ +.. _root-device-hints: + +Specifying the disk for deployment (root device hints) +------------------------------------------------------ + +Starting with the Kilo release, Bare Metal service supports passing +hints to the deploy ramdisk about which disk it should pick for the +deployment. The list of support hints is: + +* model (STRING): device identifier +* vendor (STRING): device vendor +* serial (STRING): disk serial number +* size (INT): size of the device in GiB + + .. note:: + A node's 'local_gb' property is often set to a value 1 GiB less than the + actual disk size to account for partitioning (this is how DevStack, TripleO + and Ironic Inspector work, to name a few). However, in this case ``size`` + should be the actual size. For example, for a 128 GiB disk ``local_gb`` + will be 127, but size hint will be 128. + +* wwn (STRING): unique storage identifier +* wwn_with_extension (STRING): unique storage identifier with the vendor extension appended +* wwn_vendor_extension (STRING): unique vendor storage identifier +* rotational (BOOLEAN): whether it's a rotational device or not. This + hint makes it easier to distinguish HDDs (rotational) and SSDs (not + rotational) when choosing which disk Ironic should deploy the image onto. +* name (STRING): the device name, e.g /dev/md0 + + + .. warning:: + The root device hint name should only be used for devices with + constant names (e.g RAID volumes). For SATA, SCSI and IDE disk + controllers this hint is not recommended because the order in which + the device nodes are added in Linux is arbitrary, resulting in + devices like /dev/sda and /dev/sdb `switching around at boot time + <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Storage_Administration_Guide/persistent_naming.html>`_. + + +To associate one or more hints with a node, update the node's properties +with a ``root_device`` key, for example:: + + ironic node-update <node-uuid> add properties/root_device='{"wwn": "0x4000cca77fc4dba1"}' + + +That will guarantee that Bare Metal service will pick the disk device that +has the ``wwn`` equal to the specified wwn value, or fail the deployment if it +can not be found. + +.. note:: + If multiple hints are specified, a device must satisfy all the hints. diff --git a/install-guide/source/include/trusted-boot.rst b/install-guide/source/include/trusted-boot.rst new file mode 100644 index 000000000..e7be5fdc9 --- /dev/null +++ b/install-guide/source/include/trusted-boot.rst @@ -0,0 +1,71 @@ +.. _trusted-boot: + +Trusted boot with partition image +--------------------------------- + +Starting with the Liberty release, Ironic supports trusted boot with partition +image. This means at the end of the deployment process, when the node is +rebooted with the new user image, ``trusted boot`` will be performed. It will +measure the node's BIOS, boot loader, Option ROM and the Kernel/Ramdisk, to +determine whether a bare metal node deployed by Ironic should be trusted. + +It's important to note that in order for this to work the node being deployed +**must** have Intel `TXT`_ hardware support. The image being deployed with +Ironic must have ``oat-client`` installed within it. + +The following will describe how to enable ``trusted boot`` and boot +with PXE and Nova: + +#. Create a customized user image with ``oat-client`` installed:: + + disk-image-create -u fedora baremetal oat-client -o $TRUST_IMG + + For more information on creating customized images, see :ref:`image-requirements`. + +#. Enable VT-x, VT-d, TXT and TPM on the node. This can be done manually through + the BIOS. Depending on the platform, several reboots may be needed. + +#. Enroll the node and update the node capability value:: + + ironic node-create -d pxe_ipmitool + + ironic node-update $NODE_UUID add properties/capabilities={'trusted_boot':true} + +#. Create a special flavor:: + + nova flavor-key $TRUST_FLAVOR_UUID set 'capabilities:trusted_boot'=true + +#. Prepare `tboot`_ and mboot.c32 and put them into tftp_root or http_root + directory on all nodes with the ironic-conductor processes:: + + Ubuntu: + cp /usr/lib/syslinux/mboot.c32 /tftpboot/ + + Fedora: + cp /usr/share/syslinux/mboot.c32 /tftpboot/ + + *Note: The actual location of mboot.c32 varies among different distribution versions.* + + tboot can be downloaded from + https://sourceforge.net/projects/tboot/files/latest/download + +#. Install an OAT Server. An `OAT Server`_ should be running and configured correctly. + +#. Boot an instance with Nova:: + + nova boot --flavor $TRUST_FLAVOR_UUID --image $TRUST_IMG --user-data $TRUST_SCRIPT trusted_instance + + *Note* that the node will be measured during ``trusted boot`` and the hash values saved + into `TPM`_. An example of TRUST_SCRIPT can be found in `trust script example`_. + +#. Verify the result via OAT Server. + + This is outside the scope of Ironic. At the moment, users can manually verify the result + by following the `manual verify steps`_. + +.. _`TXT`: http://en.wikipedia.org/wiki/Trusted_Execution_Technology +.. _`tboot`: https://sourceforge.net/projects/tboot +.. _`TPM`: http://en.wikipedia.org/wiki/Trusted_Platform_Module +.. _`OAT Server`: https://github.com/OpenAttestation/OpenAttestation/wiki +.. _`trust script example`: https://wiki.openstack.org/wiki/Bare-metal-trust#Trust_Script_Example +.. _`manual verify steps`: https://wiki.openstack.org/wiki/Bare-metal-trust#Manual_verify_result |