diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst index 5a2f5ba139..91bb905fc5 100644 --- a/doc/source/deploy/install-guide.rst +++ b/doc/source/deploy/install-guide.rst @@ -630,52 +630,10 @@ Guide. Specifying the disk for deployment ================================== -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: +The `Specifying the disk for deployment`_ section has been moved to the Bare +Metal service Install Guide. -* 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 - `_. - - -To associate one or more hints with a node, update the node's properties -with a ``root_device`` key, for example:: - - ironic node-update 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. +.. _`Specifying the disk for deployment`: http://docs.openstack.org/project-install-guide/baremetal/draft/advanced.html#specifying-the-disk-for-deployment-root-device-hints .. _EnableHTTPSinSwift: @@ -683,253 +641,49 @@ can not be found. Enabling HTTPS in Swift ======================= -The drivers using virtual media use swift for storing boot images -and node configuration information (contains sensitive information for Ironic -conductor to provision bare metal hardware). By default, HTTPS is not enabled -in swift. HTTPS is required to encrypt all communication between swift and Ironic -conductor and swift and bare metal (via virtual media). It can be enabled in one -of the following ways: +The `Enabling HTTPS in Swift`_ section has been moved to the Bare Metal service +Install Guide. -* `Using an SSL termination proxy - `_ +.. _`Enabling HTTPS in Swift`: http://docs.openstack.org/project-install-guide/baremetal/draft/enabling-https.html#enabling-https-in-swift -* `Using native SSL support in swift - `_ - (recommended only for testing purpose by swift). .. _EnableHTTPSinGlance: Enabling HTTPS in Image service =============================== -Ironic drivers usually use Image service during node provisioning. By default, -image service does not use HTTPS, but it is required for secure communication. -It can be enabled by making the following changes to ``/etc/glance/glance-api.conf``: +The `Enabling HTTPS in Image service`_ section has been moved to the Bare Metal +service Install Guide. -#. `Configuring SSL support - `_ +.. _`Enabling HTTPS in Image service`: http://docs.openstack.org/project-install-guide/baremetal/draft/enabling-https.html#enabling-https-in-image-service -#. Restart the glance-api service:: - - Fedora/RHEL7/CentOS7: - sudo systemctl restart openstack-glance-api - - Debian/Ubuntu: - sudo service glance-api restart - -See the `Glance `_ documentation, -for more details on the Image service. Enabling HTTPS communication between Image service and Object storage ===================================================================== -This section describes the steps needed to enable secure HTTPS communication between -Image service and Object storage when Object storage is used as the Backend. +The `Enabling HTTPS communication between Image service and Object storage`_ +section has been moved to the Bare Metal service Install Guide. -To enable secure HTTPS communication between Image service and Object storage follow these steps: +.. _`Enabling HTTPS communication between Image service and Object storage`: http://docs.openstack.org/project-install-guide/baremetal/draft/enabling-https.html#enabling-https-communication-between-image-service-and-object-storage -#. :ref:`EnableHTTPSinSwift`. - -#. `Configure Swift Storage Backend - `_ - -#. :ref:`EnableHTTPSinGlance` Enabling HTTPS communication between Image service and Bare Metal service ========================================================================= -This section describes the steps needed to enable secure HTTPS communication between -Image service and Bare Metal service. +The `Enabling HTTPS communication between Image service and Bare Metal +service`_ section has been moved to the Bare Metal service Install Guide. -To enable secure HTTPS communication between Bare Metal service and Image service follow these steps: +.. _`Enabling HTTPS communication between Image service and Bare Metal service`: http://docs.openstack.org/project-install-guide/baremetal/draft/enabling-https.html#enabling-https-communication-between-image-service-and-bare-metal-service -#. Edit ``/etc/ironic/ironic.conf``:: - - [glance] - ... - glance_cafile=/path/to/certfile - glance_protocol=https - glance_api_insecure=False - - .. note:: - 'glance_cafile' is a optional path to a CA certificate bundle to be used to validate the SSL certificate - served by Image service. - -#. Restart ironic-conductor service:: - - Fedora/RHEL7/CentOS7: - sudo systemctl restart openstack-ironic-conductor - - Debian/Ubuntu: - sudo service ironic-conductor restart Using Bare Metal service as a standalone service ================================================ -Starting with the Kilo release, it's possible to use Bare Metal service without -other OpenStack services. -You should make the following changes to ``/etc/ironic/ironic.conf``: +The `Using Bare Metal service as a standalone service`_ section has been moved +to the Bare Metal service Install Guide. -#. To disable usage of Identity service tokens:: - - [DEFAULT] - ... - auth_strategy=none - -#. If you want to disable the Networking service, you should have your network - pre-configured to serve DHCP and TFTP for machines that you're deploying. - To disable it, change the following lines:: - - [dhcp] - ... - dhcp_provider=none - - .. note:: - If you disabled the Networking service and the driver that you use is - supported by at most one conductor, PXE boot will still work for your - nodes without any manual config editing. This is because you know all - the DHCP options that will be used for deployment and can set up your - DHCP server appropriately. - - If you have multiple conductors per driver, it would be better to use - Networking since it will do all the dynamically changing configurations - for you. - -If you don't use Image service, it's possible to provide images to Bare Metal -service via hrefs. - -.. note:: - At the moment, only two types of hrefs are acceptable instead of Image - service UUIDs: HTTP(S) hrefs (for example, "http://my.server.net/images/img") - and file hrefs (file:///images/img). - -There are however some limitations for different drivers: - -* If you're using one of the drivers that use agent deploy method (namely, - ``agent_ilo``, ``agent_ipmitool``, ``agent_pyghmi``, ``agent_ssh`` or - ``agent_vbox``) you have to know MD5 checksum for your instance image. To - compute it, you can use the following command:: - - md5sum image.qcow2 - ed82def8730f394fb85aef8a208635f6 image.qcow2 - - Apart from that, because of the way the agent deploy method works, image - hrefs can use only HTTP(S) protocol. - -* If you're using ``iscsi_ilo`` or ``agent_ilo`` driver, Object Storage service - is required, as these drivers need to store floppy image that is used to pass - parameters to deployment iso. For this method also only HTTP(S) hrefs are - acceptable, as HP iLO servers cannot attach other types of hrefs as virtual - media. - -* Other drivers use PXE deploy method and there are no special requirements - in this case. - -Steps to start a deployment are pretty similar to those when using Compute: - -#. To use the `ironic CLI `_, - set up these environment variables. Since no authentication strategy is - being used, the value can be any string for OS_AUTH_TOKEN. IRONIC_URL is - the URL of the ironic-api process. - For example:: - - export OS_AUTH_TOKEN=fake-token - export IRONIC_URL=http://localhost:6385/ - -#. Create a node in Bare Metal service. At minimum, you must specify the driver - name (for example, "pxe_ipmitool"). You can also specify all the required - driver parameters in one command. This will return the node UUID:: - - ironic node-create -d pxe_ipmitool -i ipmi_address=ipmi.server.net \ - -i ipmi_username=user -i ipmi_password=pass \ - -i deploy_kernel=file:///images/deploy.vmlinuz \ - -i deploy_ramdisk=http://my.server.net/images/deploy.ramdisk - - +--------------+--------------------------------------------------------------------------+ - | Property | Value | - +--------------+--------------------------------------------------------------------------+ - | uuid | be94df40-b80a-4f63-b92b-e9368ee8d14c | - | driver_info | {u'deploy_ramdisk': u'http://my.server.net/images/deploy.ramdisk', | - | | u'deploy_kernel': u'file:///images/deploy.vmlinuz', u'ipmi_address': | - | | u'ipmi.server.net', u'ipmi_username': u'user', u'ipmi_password': | - | | u'******'} | - | extra | {} | - | driver | pxe_ipmitool | - | chassis_uuid | | - | properties | {} | - +--------------+--------------------------------------------------------------------------+ - - Note that here deploy_kernel and deploy_ramdisk contain links to - images instead of Image service UUIDs. - -#. As in case of Compute service, you can also provide ``capabilities`` to node - properties, but they will be used only by Bare Metal service (for example, - boot mode). Although you don't need to add properties like ``memory_mb``, - ``cpus`` etc. as Bare Metal service will require UUID of a node you're - going to deploy. - -#. Then create a port to inform Bare Metal service of the network interface - cards which are part of the node by creating a port with each NIC's MAC - address. In this case, they're used for naming of PXE configs for a node:: - - ironic port-create -n $NODE_UUID -a $MAC_ADDRESS - -#. As there is no Compute service flavor and instance image is not provided with - nova boot command, you also need to specify some fields in ``instance_info``. - For PXE deployment, they are ``image_source``, ``kernel``, ``ramdisk``, - ``root_gb``:: - - ironic node-update $NODE_UUID add instance_info/image_source=$IMG \ - instance_info/kernel=$KERNEL instance_info/ramdisk=$RAMDISK \ - instance_info/root_gb=10 - - Here $IMG, $KERNEL, $RAMDISK can also be HTTP(S) or file hrefs. For agent - drivers, you don't need to specify kernel and ramdisk, but MD5 checksum of - instance image is required:: - - ironic node-update $NODE_UUID add instance_info/image_checksum=$MD5HASH - -#. Validate that all parameters are correct:: - - ironic node-validate $NODE_UUID - - +------------+--------+----------------------------------------------------------------+ - | Interface | Result | Reason | - +------------+--------+----------------------------------------------------------------+ - | console | False | Missing 'ipmi_terminal_port' parameter in node's driver_info. | - | deploy | True | | - | management | True | | - | power | True | | - +------------+--------+----------------------------------------------------------------+ - -#. Now you can start the deployment, run:: - - ironic node-set-provision-state $NODE_UUID active - - You can manage provisioning by issuing this command. Valid provision states - are ``active``, ``rebuild`` and ``deleted``. - -For iLO drivers, fields that should be provided are: - -* ``ilo_deploy_iso`` under ``driver_info``; - -* ``ilo_boot_iso``, ``image_source``, ``root_gb`` under ``instance_info``. - -.. note:: - Before Liberty release Ironic was not able to track non-Glance images' - content changes. Starting with Liberty, it is possible to do so using image - modification date. For example, for HTTP image, if 'Last-Modified' header - value from response to a HEAD request to - "http://my.server.net/images/deploy.ramdisk" is greater than cached image - modification time, Ironic will re-download the content. For "file://" - images, the file system modification time is used. - - -Other references ----------------- - -* `Enabling local boot without Compute`_ +.. _`Using Bare Metal service as a standalone service`: http://docs.openstack.org/project-install-guide/baremetal/draft/standalone.html .. _`Enabling local boot without Compute`: http://docs.openstack.org/project-install-guide/baremetal/draft/local-boot-partition-images.html#enabling-local-boot-without-compute diff --git a/install-guide/source/advanced.rst b/install-guide/source/advanced.rst index 68b3291998..bba9796f3c 100644 --- a/install-guide/source/advanced.rst +++ b/install-guide/source/advanced.rst @@ -4,3 +4,5 @@ Advanced features ~~~~~~~~~~~~~~~~~ .. include:: include/local-boot-partition-images.rst + +.. include:: include/root-device-hints.rst diff --git a/install-guide/source/enabling-https.rst b/install-guide/source/enabling-https.rst new file mode 100644 index 0000000000..df13b18f11 --- /dev/null +++ b/install-guide/source/enabling-https.rst @@ -0,0 +1,89 @@ +.. _enabling-https: + +Enabling HTTPS +-------------- + +.. _EnableHTTPSinSwift: + +Enabling HTTPS in Swift +======================= + +The drivers using virtual media use swift for storing boot images +and node configuration information (contains sensitive information for Ironic +conductor to provision bare metal hardware). By default, HTTPS is not enabled +in swift. HTTPS is required to encrypt all communication between swift and Ironic +conductor and swift and bare metal (via virtual media). It can be enabled in one +of the following ways: + +* `Using an SSL termination proxy + `_ + +* `Using native SSL support in swift + `_ + (recommended only for testing purpose by swift). + +.. _EnableHTTPSinGlance: + +Enabling HTTPS in Image service +=============================== + +Ironic drivers usually use Image service during node provisioning. By default, +image service does not use HTTPS, but it is required for secure communication. +It can be enabled by making the following changes to ``/etc/glance/glance-api.conf``: + +#. `Configuring SSL support + `_ + +#. Restart the glance-api service:: + + Fedora/RHEL7/CentOS7: + sudo systemctl restart openstack-glance-api + + Debian/Ubuntu: + sudo service glance-api restart + +See the `Glance `_ documentation, +for more details on the Image service. + +Enabling HTTPS communication between Image service and Object storage +===================================================================== + +This section describes the steps needed to enable secure HTTPS communication between +Image service and Object storage when Object storage is used as the Backend. + +To enable secure HTTPS communication between Image service and Object storage follow these steps: + +#. :ref:`EnableHTTPSinSwift` + +#. `Configure Swift Storage Backend + `_ + +#. :ref:`EnableHTTPSinGlance` + +Enabling HTTPS communication between Image service and Bare Metal service +========================================================================= + +This section describes the steps needed to enable secure HTTPS communication between +Image service and Bare Metal service. + +To enable secure HTTPS communication between Bare Metal service and Image service follow these steps: + +#. Edit ``/etc/ironic/ironic.conf``:: + + [glance] + ... + glance_cafile=/path/to/certfile + glance_protocol=https + glance_api_insecure=False + + .. note:: + 'glance_cafile' is a optional path to a CA certificate bundle to be used to validate the SSL certificate + served by Image service. + +#. Restart ironic-conductor service:: + + Fedora/RHEL7/CentOS7: + sudo systemctl restart openstack-ironic-conductor + + Debian/Ubuntu: + sudo service ironic-conductor restart diff --git a/install-guide/source/include/local-boot-partition-images.rst b/install-guide/source/include/local-boot-partition-images.rst index e12ac85dc8..f23cb541cb 100644 --- a/install-guide/source/include/local-boot-partition-images.rst +++ b/install-guide/source/include/local-boot-partition-images.rst @@ -45,6 +45,7 @@ an ``extra_spec`` to the Compute service flavor, for example:: ``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 =================================== 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 0000000000..879371abaf --- /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 + `_. + + +To associate one or more hints with a node, update the node's properties +with a ``root_device`` key, for example:: + + ironic node-update 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/index.rst b/install-guide/source/index.rst index c49ceb78ab..83e6bd24c5 100644 --- a/install-guide/source/index.rst +++ b/install-guide/source/index.rst @@ -11,6 +11,8 @@ Bare Metal service configure-cleaning.rst configure-tenant-networks.rst enrollment.rst + enabling-https.rst + standalone.rst advanced.rst troubleshooting.rst next-steps.rst diff --git a/install-guide/source/standalone.rst b/install-guide/source/standalone.rst new file mode 100644 index 0000000000..1faeb99ee4 --- /dev/null +++ b/install-guide/source/standalone.rst @@ -0,0 +1,169 @@ + +Using Bare Metal service as a standalone service +================================================ + +Starting with the Kilo release, it's possible to use Bare Metal service without +other OpenStack services. + +You should make the following changes to ``/etc/ironic/ironic.conf``: + +#. To disable usage of Identity service tokens:: + + [DEFAULT] + ... + auth_strategy=none + +#. If you want to disable the Networking service, you should have your network + pre-configured to serve DHCP and TFTP for machines that you're deploying. + To disable it, change the following lines:: + + [dhcp] + ... + dhcp_provider=none + + .. note:: + If you disabled the Networking service and the driver that you use is + supported by at most one conductor, PXE boot will still work for your + nodes without any manual config editing. This is because you know all + the DHCP options that will be used for deployment and can set up your + DHCP server appropriately. + + If you have multiple conductors per driver, it would be better to use + Networking since it will do all the dynamically changing configurations + for you. + +If you don't use Image service, it's possible to provide images to Bare Metal +service via hrefs. + +.. note:: + At the moment, only two types of hrefs are acceptable instead of Image + service UUIDs: HTTP(S) hrefs (for example, "http://my.server.net/images/img") + and file hrefs (file:///images/img). + +There are however some limitations for different drivers: + +* If you're using one of the drivers that use agent deploy method (namely, + ``agent_ilo``, ``agent_ipmitool``, ``agent_pyghmi``, ``agent_ssh`` or + ``agent_vbox``) you have to know MD5 checksum for your instance image. To + compute it, you can use the following command:: + + md5sum image.qcow2 + ed82def8730f394fb85aef8a208635f6 image.qcow2 + + Apart from that, because of the way the agent deploy method works, image + hrefs can use only HTTP(S) protocol. + +* If you're using ``iscsi_ilo`` or ``agent_ilo`` driver, Object Storage service + is required, as these drivers need to store floppy image that is used to pass + parameters to deployment iso. For this method also only HTTP(S) hrefs are + acceptable, as HP iLO servers cannot attach other types of hrefs as virtual + media. + +* Other drivers use PXE deploy method and there are no special requirements + in this case. + +Steps to start a deployment are pretty similar to those when using Compute: + +#. To use the `ironic CLI `_, + set up these environment variables. Since no authentication strategy is + being used, the value can be any string for OS_AUTH_TOKEN. IRONIC_URL is + the URL of the ironic-api process. + For example:: + + export OS_AUTH_TOKEN=fake-token + export IRONIC_URL=http://localhost:6385/ + +#. Create a node in Bare Metal service. At minimum, you must specify the driver + name (for example, "pxe_ipmitool"). You can also specify all the required + driver parameters in one command. This will return the node UUID:: + + ironic node-create -d pxe_ipmitool -i ipmi_address=ipmi.server.net \ + -i ipmi_username=user -i ipmi_password=pass \ + -i deploy_kernel=file:///images/deploy.vmlinuz \ + -i deploy_ramdisk=http://my.server.net/images/deploy.ramdisk + + +--------------+--------------------------------------------------------------------------+ + | Property | Value | + +--------------+--------------------------------------------------------------------------+ + | uuid | be94df40-b80a-4f63-b92b-e9368ee8d14c | + | driver_info | {u'deploy_ramdisk': u'http://my.server.net/images/deploy.ramdisk', | + | | u'deploy_kernel': u'file:///images/deploy.vmlinuz', u'ipmi_address': | + | | u'ipmi.server.net', u'ipmi_username': u'user', u'ipmi_password': | + | | u'******'} | + | extra | {} | + | driver | pxe_ipmitool | + | chassis_uuid | | + | properties | {} | + +--------------+--------------------------------------------------------------------------+ + + Note that here deploy_kernel and deploy_ramdisk contain links to + images instead of Image service UUIDs. + +#. As in case of Compute service, you can also provide ``capabilities`` to node + properties, but they will be used only by Bare Metal service (for example, + boot mode). Although you don't need to add properties like ``memory_mb``, + ``cpus`` etc. as Bare Metal service will require UUID of a node you're + going to deploy. + +#. Then create a port to inform Bare Metal service of the network interface + cards which are part of the node by creating a port with each NIC's MAC + address. In this case, they're used for naming of PXE configs for a node:: + + ironic port-create -n $NODE_UUID -a $MAC_ADDRESS + +#. As there is no Compute service flavor and instance image is not provided with + nova boot command, you also need to specify some fields in ``instance_info``. + For PXE deployment, they are ``image_source``, ``kernel``, ``ramdisk``, + ``root_gb``:: + + ironic node-update $NODE_UUID add instance_info/image_source=$IMG \ + instance_info/kernel=$KERNEL instance_info/ramdisk=$RAMDISK \ + instance_info/root_gb=10 + + Here $IMG, $KERNEL, $RAMDISK can also be HTTP(S) or file hrefs. For agent + drivers, you don't need to specify kernel and ramdisk, but MD5 checksum of + instance image is required:: + + ironic node-update $NODE_UUID add instance_info/image_checksum=$MD5HASH + +#. Validate that all parameters are correct:: + + ironic node-validate $NODE_UUID + + +------------+--------+----------------------------------------------------------------+ + | Interface | Result | Reason | + +------------+--------+----------------------------------------------------------------+ + | console | False | Missing 'ipmi_terminal_port' parameter in node's driver_info. | + | deploy | True | | + | management | True | | + | power | True | | + +------------+--------+----------------------------------------------------------------+ + +#. Now you can start the deployment, run:: + + ironic node-set-provision-state $NODE_UUID active + + You can manage provisioning by issuing this command. Valid provision states + are ``active``, ``rebuild`` and ``deleted``. + +For iLO drivers, fields that should be provided are: + +* ``ilo_deploy_iso`` under ``driver_info``; + +* ``ilo_boot_iso``, ``image_source``, ``root_gb`` under ``instance_info``. + +.. note:: + Before Liberty release Ironic was not able to track non-Glance images' + content changes. Starting with Liberty, it is possible to do so using image + modification date. For example, for HTTP image, if 'Last-Modified' header + value from response to a HEAD request to + "http://my.server.net/images/deploy.ramdisk" is greater than cached image + modification time, Ironic will re-download the content. For "file://" + images, the file system modification time is used. + + +Other references +---------------- + +* :ref:`local-boot-without-compute` +