From 0445213bbbaca44346e4d1160134ae1ac57bd049 Mon Sep 17 00:00:00 2001 From: Mathieu Mitchell Date: Tue, 13 Sep 2016 21:56:08 -0400 Subject: [PATCH] [install-guide] Import "Enrollment" and "Troubleshooting" sections Change-Id: Ie8b570d2a54c38a9d04976a0430fe0d963db57b0 Partial-bug: #1612278 --- doc/source/deploy/install-guide.rst | 517 +----------------- install-guide/source/enrollment.rst | 398 ++++++++++++++ .../include/configure-neutron-networks.rst | 4 +- install-guide/source/index.rst | 3 +- install-guide/source/troubleshooting.rst | 126 +++++ install-guide/source/verify.rst | 10 - 6 files changed, 535 insertions(+), 523 deletions(-) create mode 100644 install-guide/source/enrollment.rst create mode 100644 install-guide/source/troubleshooting.rst delete mode 100644 install-guide/source/verify.rst diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst index 0e955069df..5a2f5ba139 100644 --- a/doc/source/deploy/install-guide.rst +++ b/doc/source/deploy/install-guide.rst @@ -622,397 +622,10 @@ Metal service Install Guide. Enrollment ========== -After all the services have been properly configured, you should enroll your -hardware with the Bare Metal service, and confirm that the Compute service sees -the available hardware. The nodes will be visible to the Compute service once -they are in the ``available`` provision state. +The `Enrollment`_ section has been moved to the Bare Metal service Install +Guide. -.. note:: - After enrolling nodes with the Bare Metal service, the Compute service - will not be immediately notified of the new resources. The Compute service's - resource tracker syncs periodically, and so any changes made directly to the - Bare Metal service's resources will become visible in the Compute service - only after the next run of that periodic task. - More information is in the `Troubleshooting`_ section below. - -.. note:: - Any bare metal node that is visible to the Compute service may have a - workload scheduled to it, if both the ``power`` and ``deploy`` interfaces - pass the ``validate`` check. - If you wish to exclude a node from the Compute service's scheduler, for - instance so that you can perform maintenance on it, you can set the node to - "maintenance" mode. - For more information see the `Maintenance Mode`_ section below. - -Enrollment process ------------------- - -This section describes the main steps to enroll a node and make it available -for provisioning. Some steps are shown separately for illustration purposes, -and may be combined if desired. - -#. Create a node in the Bare Metal service. At a minimum, you must - specify the driver name (for example, "pxe_ipmitool"). - This will return the node UUID along with other information - about the node. The node's provision state will be ``available``. (The - example assumes that the client is using the default API version.):: - - ironic node-create -d pxe_ipmitool - +--------------+--------------------------------------+ - | Property | Value | - +--------------+--------------------------------------+ - | uuid | dfc6189f-ad83-4261-9bda-b27258eb1987 | - | driver_info | {} | - | extra | {} | - | driver | pxe_ipmitool | - | chassis_uuid | | - | properties | {} | - | name | None | - +--------------+--------------------------------------+ - - ironic node-show dfc6189f-ad83-4261-9bda-b27258eb1987 - +------------------------+--------------------------------------+ - | Property | Value | - +------------------------+--------------------------------------+ - | target_power_state | None | - | extra | {} | - | last_error | None | - | maintenance_reason | None | - | provision_state | available | - | uuid | dfc6189f-ad83-4261-9bda-b27258eb1987 | - | console_enabled | False | - | target_provision_state | None | - | provision_updated_at | None | - | maintenance | False | - | power_state | None | - | driver | pxe_ipmitool | - | properties | {} | - | instance_uuid | None | - | name | None | - | driver_info | {} | - | ... | ... | - +------------------------+--------------------------------------+ - - Beginning with the Kilo release a node may also be referred to by a logical - name as well as its UUID. To utilize this new feature a name must be - assigned to the node. This can be done when the node is created by - adding the ``-n`` option to the ``node-create`` command or by updating an - existing node with the ``node-update`` command. See `Logical Names`_ for - examples. - - Beginning with the Liberty release, with API version 1.11 and above, a newly - created node will have an initial provision state of ``enroll`` as opposed to - ``available``. See `Enrolling a node`_ for more details. - -#. Update the node ``driver_info`` so that Bare Metal service can manage the - node. Different drivers may require different information about the node. - You can determine this with the ``driver-properties`` command, as follows:: - - ironic driver-properties pxe_ipmitool - +----------------------+-------------------------------------------------------------------------------------------------------------+ - | Property | Description | - +----------------------+-------------------------------------------------------------------------------------------------------------+ - | ipmi_address | IP address or hostname of the node. Required. | - | ipmi_password | password. Optional. | - | ipmi_username | username; default is NULL user. Optional. | - | ... | ... | - | deploy_kernel | UUID (from Glance) of the deployment kernel. Required. | - | deploy_ramdisk | UUID (from Glance) of the ramdisk that is mounted at boot time. Required. | - +----------------------+-------------------------------------------------------------------------------------------------------------+ - - ironic node-update $NODE_UUID add \ - driver_info/ipmi_username=$USER \ - driver_info/ipmi_password=$PASS \ - driver_info/ipmi_address=$ADDRESS - - .. note:: - If IPMI is running on a port other than 623 (the default). The port must - be added to ``driver_info`` by specifying the ``ipmi_port`` value. - Example:: - - ironic node-update $NODE_UUID add driver_info/ipmi_port=$PORT_NUMBER - - Note that you may also specify all ``driver_info`` parameters during - ``node-create`` by passing the **-i** option multiple times. - -#. Update the node's properties to match the bare metal flavor you created - earlier:: - - ironic node-update $NODE_UUID add \ - properties/cpus=$CPU \ - properties/memory_mb=$RAM_MB \ - properties/local_gb=$DISK_GB \ - properties/cpu_arch=$ARCH - - As above, these can also be specified at node creation by passing the **-p** - option to ``node-create`` multiple times. - -#. If you wish to perform more advanced scheduling of the instances based on - hardware capabilities, you may add metadata to each node that will be - exposed to the nova scheduler (see: `ComputeCapabilitiesFilter`_). A full - explanation of this is outside of the scope of this document. It can be done - through the special ``capabilities`` member of node properties:: - - ironic node-update $NODE_UUID add \ - properties/capabilities=key1:val1,key2:val2 - -#. As mentioned in the `Flavor Creation`_ section, if using the Kilo or later - release of Bare Metal service, you should specify a deploy kernel and - ramdisk which correspond to the node's driver, for example:: - - ironic node-update $NODE_UUID add \ - driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \ - driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID - -#. You must also 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. - These MAC addresses are passed to the Networking service during instance - provisioning and used to configure the network appropriately:: - - ironic port-create -n $NODE_UUID -a $MAC_ADDRESS - -#. To check if Bare Metal service has the minimum information necessary for - a node's driver to function, you may ``validate`` it:: - - ironic node-validate $NODE_UUID - - +------------+--------+--------+ - | Interface | Result | Reason | - +------------+--------+--------+ - | console | True | | - | deploy | True | | - | management | True | | - | power | True | | - +------------+--------+--------+ - - If the node fails validation, each driver will return information as to why - it failed:: - - ironic node-validate $NODE_UUID - - +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ - | Interface | Result | Reason | - +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ - | console | None | not supported | - | deploy | False | Cannot validate iSCSI deploy. Some parameters were missing in node's instance_info. Missing are: ['root_gb', 'image_source'] | - | management | False | Missing the following IPMI credentials in node's driver_info: ['ipmi_address']. | - | power | False | Missing the following IPMI credentials in node's driver_info: ['ipmi_address']. | - +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ - -#. If using API version 1.11 or above, the node was created in the ``enroll`` - provision state. In order for the node to be available for deploying a - workload (for example, by the Compute service), it needs to be in the - ``available`` provision state. To do this, it must be moved into the - ``manageable`` state and then moved into the ``available`` state. The - `API version 1.11 and above`_ section describes the commands for this. - -.. _ComputeCapabilitiesFilter: http://docs.openstack.org/developer/nova/devref/filter_scheduler.html?highlight=computecapabilitiesfilter - - -Enrolling a node ----------------- -In the Liberty cycle, starting with API version 1.11, the Bare Metal service -added a new initial provision state of ``enroll`` to its state machine. - -Existing automation tooling that use an API version lower than 1.11 are not -affected, since the initial provision state is still ``available``. -However, using API version 1.11 or above may break existing automation tooling -with respect to node creation. - -The default API version used by (the most recent) python-ironicclient is 1.9. - -The examples below set the API version for each command. To set the -API version for all commands, you can set the environment variable -``IRONIC_API_VERSION``. - -API version 1.10 and below -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Below is an example of creating a node with API version 1.10. After creation, -the node will be in the ``available`` provision state. -Other API versions below 1.10 may be substituted in place of 1.10. - -:: - - ironic --ironic-api-version 1.10 node-create -d agent_ilo -n pre11 - - +--------------+--------------------------------------+ - | Property | Value | - +--------------+--------------------------------------+ - | uuid | cc4998a0-f726-4927-9473-0582458c6789 | - | driver_info | {} | - | extra | {} | - | driver | agent_ilo | - | chassis_uuid | | - | properties | {} | - | name | pre11 | - +--------------+--------------------------------------+ - - - ironic --ironic-api-version 1.10 node-list - - +--------------------------------------+-------+---------------+-------------+--------------------+-------------+ - | UUID | Name | Instance UUID | Power State | Provisioning State | Maintenance | - +--------------------------------------+-------+---------------+-------------+--------------------+-------------+ - | cc4998a0-f726-4927-9473-0582458c6789 | pre11 | None | None | available | False | - +--------------------------------------+-------+---------------+-------------+--------------------+-------------+ - -API version 1.11 and above -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Beginning with API version 1.11, the initial provision state for newly created -nodes is ``enroll``. In the examples below, other API versions above 1.11 may be -substituted in place of 1.11. -:: - - ironic --ironic-api-version 1.11 node-create -d agent_ilo -n post11 - - +--------------+--------------------------------------+ - | Property | Value | - +--------------+--------------------------------------+ - | uuid | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | - | driver_info | {} | - | extra | {} | - | driver | agent_ilo | - | chassis_uuid | | - | properties | {} | - | name | post11 | - +--------------+--------------------------------------+ - - - ironic --ironic-api-version 1.11 node-list - - +--------------------------------------+--------+---------------+-------------+--------------------+-------------+ - | UUID | Name | Instance UUID | Power State | Provisioning State | Maintenance | - +--------------------------------------+--------+---------------+-------------+--------------------+-------------+ - | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | post11 | None | None | enroll | False | - +--------------------------------------+--------+---------------+-------------+--------------------+-------------+ - -In order for nodes to be available for deploying workloads on them, nodes -must be in the ``available`` provision state. To do this, nodes -created with API version 1.11 and above must be moved from the ``enroll`` state -to the ``manageable`` state and then to the ``available`` state. - -To move a node to a different provision state, use the -``node-set-provision-state`` command. - -.. note:: Since it is an asychronous call, the response for - ``ironic node-set-provision-state`` will not indicate whether the - transition succeeded or not. You can check the status of the - operation via ``ironic node-show``. If it was successful, - ``provision_state`` will be in the desired state. If it failed, - there will be information in the node's ``last_error``. - -After creating a node and before moving it from its initial provision state of -``enroll``, basic power and port information needs to be configured on the node. -The Bare Metal service needs this information because it verifies that it is -capable of controlling the node when transitioning the node from ``enroll`` to -``manageable`` state. - -To move a node from ``enroll`` to ``manageable`` provision state:: - - ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID manage - - ironic node-show $NODE_UUID - - +------------------------+--------------------------------------------------------------------+ - | Property | Value | - +------------------------+--------------------------------------------------------------------+ - | ... | ... | - | provision_state | manageable | <- verify correct state - | uuid | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | - | ... | ... | - +------------------------+--------------------------------------------------------------------+ - -When a node is moved from the ``manageable`` to ``available`` provision -state, the node will go through automated cleaning if configured to do so (see -:ref:`CleaningNetworkSetup`). -To move a node from ``manageable`` to ``available`` provision state:: - - ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID provide - - ironic node-show $NODE_UUID - - +------------------------+--------------------------------------------------------------------+ - | Property | Value | - +------------------------+--------------------------------------------------------------------+ - | ... | ... | - | provision_state | available | < - verify correct state - | uuid | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | - | ... | ... | - +------------------------+--------------------------------------------------------------------+ - - -For more details on the Bare Metal service's state machine, see the -`state machine `_ -documentation. - - -Logical names -------------- -Beginning with the Kilo release a Node may also be referred to by a -logical name as well as its UUID. Names can be assigned either when -creating the node by adding the ``-n`` option to the ``node-create`` command or -by updating an existing node with the ``node-update`` command. - -Node names must be unique, and conform to: - -- rfc952_ -- rfc1123_ -- wiki_hostname_ - -The node is named 'example' in the following examples: -:: - - ironic node-create -d agent_ipmitool -n example - -or:: - - ironic node-update $NODE_UUID add name=example - - -Once assigned a logical name, a node can then be referred to by name or -UUID interchangeably. -:: - - ironic node-create -d agent_ipmitool -n example - - +--------------+--------------------------------------+ - | Property | Value | - +--------------+--------------------------------------+ - | uuid | 71e01002-8662-434d-aafd-f068f69bb85e | - | driver_info | {} | - | extra | {} | - | driver | agent_ipmitool | - | chassis_uuid | | - | properties | {} | - | name | example | - +--------------+--------------------------------------+ - - - ironic node-show example - - +------------------------+--------------------------------------+ - | Property | Value | - +------------------------+--------------------------------------+ - | target_power_state | None | - | extra | {} | - | last_error | None | - | updated_at | 2015-04-24T16:23:46+00:00 | - | ... | ... | - | instance_info | {} | - +------------------------+--------------------------------------+ - -.. _rfc952: http://tools.ietf.org/html/rfc952 -.. _rfc1123: http://tools.ietf.org/html/rfc1123 -.. _wiki_hostname: http://en.wikipedia.org/wiki/Hostname - - -Hardware Inspection -------------------- - -Starting with the Kilo release, Bare Metal service supports hardware inspection -that simplifies enrolling nodes - please see :ref:`inspection` for details. +.. _`Enrollment`: http://docs.openstack.org/project-install-guide/baremetal/draft/enrollment.html Specifying the disk for deployment ================================== @@ -1515,6 +1128,8 @@ the `CoreOS tools`_ at: * `CoreOS deploy kernel `_ * `CoreOS deploy ramdisk `_ +.. _ironic-python-agent: http://docs.openstack.org/developer/ironic-python-agent/ + Building from source -------------------- @@ -1673,123 +1288,7 @@ with PXE and Nova: Troubleshooting =============== -Once all the services are running and configured properly, and a node has been -enrolled with the Bare Metal service and is in the ``available`` provision -state, the Compute service should detect the node -as an available resource and expose it to the scheduler. +The `Troubleshooting`_ section has been moved to the Bare Metal service Install +Guide. -.. note:: - There is a delay, and it may take up to a minute (one periodic task cycle) - for the Compute service to recognize any changes in the Bare Metal service's - resources (both additions and deletions). - -In addition to watching ``nova-compute`` log files, you can see the available -resources by looking at the list of Compute hypervisors. The resources reported -therein should match the bare metal node properties, and the Compute service flavor. - -Here is an example set of commands to compare the resources in Compute -service and Bare Metal service:: - - $ ironic node-list - +--------------------------------------+---------------+-------------+--------------------+-------------+ - | UUID | Instance UUID | Power State | Provisioning State | Maintenance | - +--------------------------------------+---------------+-------------+--------------------+-------------+ - | 86a2b1bb-8b29-4964-a817-f90031debddb | None | power off | available | False | - +--------------------------------------+---------------+-------------+--------------------+-------------+ - - $ ironic node-show 86a2b1bb-8b29-4964-a817-f90031debddb - +------------------------+----------------------------------------------------------------------+ - | Property | Value | - +------------------------+----------------------------------------------------------------------+ - | instance_uuid | None | - | properties | {u'memory_mb': u'1024', u'cpu_arch': u'x86_64', u'local_gb': u'10', | - | | u'cpus': u'1'} | - | maintenance | False | - | driver_info | { [SNIP] } | - | extra | {} | - | last_error | None | - | created_at | 2014-11-20T23:57:03+00:00 | - | target_provision_state | None | - | driver | pxe_ipmitool | - | updated_at | 2014-11-21T00:47:34+00:00 | - | instance_info | {} | - | chassis_uuid | 7b49bbc5-2eb7-4269-b6ea-3f1a51448a59 | - | provision_state | available | - | reservation | None | - | power_state | power off | - | console_enabled | False | - | uuid | 86a2b1bb-8b29-4964-a817-f90031debddb | - +------------------------+----------------------------------------------------------------------+ - - $ nova hypervisor-show 1 - +-------------------------+--------------------------------------+ - | Property | Value | - +-------------------------+--------------------------------------+ - | cpu_info | baremetal cpu | - | current_workload | 0 | - | disk_available_least | - | - | free_disk_gb | 10 | - | free_ram_mb | 1024 | - | host_ip | [ SNIP ] | - | hypervisor_hostname | 86a2b1bb-8b29-4964-a817-f90031debddb | - | hypervisor_type | ironic | - | hypervisor_version | 1 | - | id | 1 | - | local_gb | 10 | - | local_gb_used | 0 | - | memory_mb | 1024 | - | memory_mb_used | 0 | - | running_vms | 0 | - | service_disabled_reason | - | - | service_host | my-test-host | - | service_id | 6 | - | state | up | - | status | enabled | - | vcpus | 1 | - | vcpus_used | 0 | - +-------------------------+--------------------------------------+ - - -Maintenance mode ----------------- -Maintenance mode may be used if you need to take a node out of the resource -pool. Putting a node in maintenance mode will prevent Bare Metal service from -executing periodic tasks associated with the node. This will also prevent -Compute service from placing a tenant instance on the node by not exposing -the node to the nova scheduler. Nodes can be placed into maintenance mode -with the following command. -:: - - $ ironic node-set-maintenance $NODE_UUID on - -As of the Kilo release, a maintenance reason may be included with the optional -``--reason`` command line option. This is a free form text field that will be -displayed in the ``maintenance_reason`` section of the ``node-show`` command. -:: - - $ ironic node-set-maintenance $UUID on --reason "Need to add ram." - - $ ironic node-show $UUID - - +------------------------+--------------------------------------+ - | Property | Value | - +------------------------+--------------------------------------+ - | target_power_state | None | - | extra | {} | - | last_error | None | - | updated_at | 2015-04-27T15:43:58+00:00 | - | maintenance_reason | Need to add ram. | - | ... | ... | - | maintenance | True | - | ... | ... | - +------------------------+--------------------------------------+ - -To remove maintenance mode and clear any ``maintenance_reason`` use the -following command. -:: - - $ ironic node-set-maintenance $NODE_UUID off - - -.. _ironic-python-agent: http://docs.openstack.org/developer/ironic-python-agent/ -.. _diskimage-builder: http://docs.openstack.org/developer/diskimage-builder/ +.. _`Troubleshooting`: http://docs.openstack.org/project-install-guide/baremetal/draft/troubleshooting.html diff --git a/install-guide/source/enrollment.rst b/install-guide/source/enrollment.rst new file mode 100644 index 0000000000..49ff012d3c --- /dev/null +++ b/install-guide/source/enrollment.rst @@ -0,0 +1,398 @@ +.. _enrollment: + +Enrollment +========== + +After all the services have been properly configured, you should enroll your +hardware with the Bare Metal service, and confirm that the Compute service sees +the available hardware. The nodes will be visible to the Compute service once +they are in the ``available`` provision state. + +.. note:: + After enrolling nodes with the Bare Metal service, the Compute service + will not be immediately notified of the new resources. The Compute service's + resource tracker syncs periodically, and so any changes made directly to the + Bare Metal service's resources will become visible in the Compute service + only after the next run of that periodic task. + More information is in the :ref:`troubleshooting` section. + +.. note:: + Any bare metal node that is visible to the Compute service may have a + workload scheduled to it, if both the ``power`` and ``deploy`` interfaces + pass the ``validate`` check. + If you wish to exclude a node from the Compute service's scheduler, for + instance so that you can perform maintenance on it, you can set the node to + "maintenance" mode. + For more information see the :ref:`maintenance_mode` section. + +Enrollment process +------------------ + +This section describes the main steps to enroll a node and make it available +for provisioning. Some steps are shown separately for illustration purposes, +and may be combined if desired. + +#. Create a node in the Bare Metal service. At a minimum, you must + specify the driver name (for example, "pxe_ipmitool"). + This will return the node UUID along with other information + about the node. The node's provision state will be ``available``. (The + example assumes that the client is using the default API version.):: + + ironic node-create -d pxe_ipmitool + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | uuid | dfc6189f-ad83-4261-9bda-b27258eb1987 | + | driver_info | {} | + | extra | {} | + | driver | pxe_ipmitool | + | chassis_uuid | | + | properties | {} | + | name | None | + +--------------+--------------------------------------+ + + ironic node-show dfc6189f-ad83-4261-9bda-b27258eb1987 + +------------------------+--------------------------------------+ + | Property | Value | + +------------------------+--------------------------------------+ + | target_power_state | None | + | extra | {} | + | last_error | None | + | maintenance_reason | None | + | provision_state | available | + | uuid | dfc6189f-ad83-4261-9bda-b27258eb1987 | + | console_enabled | False | + | target_provision_state | None | + | provision_updated_at | None | + | maintenance | False | + | power_state | None | + | driver | pxe_ipmitool | + | properties | {} | + | instance_uuid | None | + | name | None | + | driver_info | {} | + | ... | ... | + +------------------------+--------------------------------------+ + + Beginning with the Kilo release a node may also be referred to by a logical + name as well as its UUID. To utilize this new feature a name must be + assigned to the node. This can be done when the node is created by + adding the ``-n`` option to the ``node-create`` command or by updating an + existing node with the ``node-update`` command. See `Logical Names`_ for + examples. + + Beginning with the Liberty release, with API version 1.11 and above, a newly + created node will have an initial provision state of ``enroll`` as opposed to + ``available``. See `Enrolling a node`_ for more details. + +#. Update the node ``driver_info`` so that Bare Metal service can manage the + node. Different drivers may require different information about the node. + You can determine this with the ``driver-properties`` command, as follows:: + + ironic driver-properties pxe_ipmitool + +----------------------+-------------------------------------------------------------------------------------------------------------+ + | Property | Description | + +----------------------+-------------------------------------------------------------------------------------------------------------+ + | ipmi_address | IP address or hostname of the node. Required. | + | ipmi_password | password. Optional. | + | ipmi_username | username; default is NULL user. Optional. | + | ... | ... | + | deploy_kernel | UUID (from Glance) of the deployment kernel. Required. | + | deploy_ramdisk | UUID (from Glance) of the ramdisk that is mounted at boot time. Required. | + +----------------------+-------------------------------------------------------------------------------------------------------------+ + + ironic node-update $NODE_UUID add \ + driver_info/ipmi_username=$USER \ + driver_info/ipmi_password=$PASS \ + driver_info/ipmi_address=$ADDRESS + + .. note:: + If IPMI is running on a port other than 623 (the default). The port must + be added to ``driver_info`` by specifying the ``ipmi_port`` value. + Example:: + + ironic node-update $NODE_UUID add driver_info/ipmi_port=$PORT_NUMBER + + Note that you may also specify all ``driver_info`` parameters during + ``node-create`` by passing the **-i** option multiple times. + +#. Update the node's properties to match the bare metal flavor you created + earlier:: + + ironic node-update $NODE_UUID add \ + properties/cpus=$CPU \ + properties/memory_mb=$RAM_MB \ + properties/local_gb=$DISK_GB \ + properties/cpu_arch=$ARCH + + As above, these can also be specified at node creation by passing the **-p** + option to ``node-create`` multiple times. + +#. If you wish to perform more advanced scheduling of the instances based on + hardware capabilities, you may add metadata to each node that will be + exposed to the nova scheduler (see: `ComputeCapabilitiesFilter`_). A full + explanation of this is outside of the scope of this document. It can be done + through the special ``capabilities`` member of node properties:: + + ironic node-update $NODE_UUID add \ + properties/capabilities=key1:val1,key2:val2 + +#. As mentioned in the :ref:`flavor-creation` section, if using the Kilo or later + release of Bare Metal service, you should specify a deploy kernel and + ramdisk which correspond to the node's driver, for example:: + + ironic node-update $NODE_UUID add \ + driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \ + driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID + +#. You must also 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. + These MAC addresses are passed to the Networking service during instance + provisioning and used to configure the network appropriately:: + + ironic port-create -n $NODE_UUID -a $MAC_ADDRESS + +#. To check if Bare Metal service has the minimum information necessary for + a node's driver to function, you may ``validate`` it:: + + ironic node-validate $NODE_UUID + + +------------+--------+--------+ + | Interface | Result | Reason | + +------------+--------+--------+ + | console | True | | + | deploy | True | | + | management | True | | + | power | True | | + +------------+--------+--------+ + + If the node fails validation, each driver will return information as to why + it failed:: + + ironic node-validate $NODE_UUID + + +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ + | Interface | Result | Reason | + +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ + | console | None | not supported | + | deploy | False | Cannot validate iSCSI deploy. Some parameters were missing in node's instance_info. Missing are: ['root_gb', 'image_source'] | + | management | False | Missing the following IPMI credentials in node's driver_info: ['ipmi_address']. | + | power | False | Missing the following IPMI credentials in node's driver_info: ['ipmi_address']. | + +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ + +#. If using API version 1.11 or above, the node was created in the ``enroll`` + provision state. In order for the node to be available for deploying a + workload (for example, by the Compute service), it needs to be in the + ``available`` provision state. To do this, it must be moved into the + ``manageable`` state and then moved into the ``available`` state. The + `API version 1.11 and above`_ section describes the commands for this. + +.. _ComputeCapabilitiesFilter: http://docs.openstack.org/developer/nova/devref/filter_scheduler.html?highlight=computecapabilitiesfilter + + +Enrolling a node +---------------- +In the Liberty cycle, starting with API version 1.11, the Bare Metal service +added a new initial provision state of ``enroll`` to its state machine. + +Existing automation tooling that use an API version lower than 1.11 are not +affected, since the initial provision state is still ``available``. +However, using API version 1.11 or above may break existing automation tooling +with respect to node creation. + +The default API version used by (the most recent) python-ironicclient is 1.9. + +The examples below set the API version for each command. To set the +API version for all commands, you can set the environment variable +``IRONIC_API_VERSION``. + +API version 1.10 and below +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Below is an example of creating a node with API version 1.10. After creation, +the node will be in the ``available`` provision state. +Other API versions below 1.10 may be substituted in place of 1.10. + +:: + + ironic --ironic-api-version 1.10 node-create -d agent_ilo -n pre11 + + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | uuid | cc4998a0-f726-4927-9473-0582458c6789 | + | driver_info | {} | + | extra | {} | + | driver | agent_ilo | + | chassis_uuid | | + | properties | {} | + | name | pre11 | + +--------------+--------------------------------------+ + + + ironic --ironic-api-version 1.10 node-list + + +--------------------------------------+-------+---------------+-------------+--------------------+-------------+ + | UUID | Name | Instance UUID | Power State | Provisioning State | Maintenance | + +--------------------------------------+-------+---------------+-------------+--------------------+-------------+ + | cc4998a0-f726-4927-9473-0582458c6789 | pre11 | None | None | available | False | + +--------------------------------------+-------+---------------+-------------+--------------------+-------------+ + +API version 1.11 and above +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Beginning with API version 1.11, the initial provision state for newly created +nodes is ``enroll``. In the examples below, other API versions above 1.11 may be +substituted in place of 1.11. +:: + + ironic --ironic-api-version 1.11 node-create -d agent_ilo -n post11 + + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | uuid | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | + | driver_info | {} | + | extra | {} | + | driver | agent_ilo | + | chassis_uuid | | + | properties | {} | + | name | post11 | + +--------------+--------------------------------------+ + + + ironic --ironic-api-version 1.11 node-list + + +--------------------------------------+--------+---------------+-------------+--------------------+-------------+ + | UUID | Name | Instance UUID | Power State | Provisioning State | Maintenance | + +--------------------------------------+--------+---------------+-------------+--------------------+-------------+ + | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | post11 | None | None | enroll | False | + +--------------------------------------+--------+---------------+-------------+--------------------+-------------+ + +In order for nodes to be available for deploying workloads on them, nodes +must be in the ``available`` provision state. To do this, nodes +created with API version 1.11 and above must be moved from the ``enroll`` state +to the ``manageable`` state and then to the ``available`` state. + +To move a node to a different provision state, use the +``node-set-provision-state`` command. + +.. note:: Since it is an asychronous call, the response for + ``ironic node-set-provision-state`` will not indicate whether the + transition succeeded or not. You can check the status of the + operation via ``ironic node-show``. If it was successful, + ``provision_state`` will be in the desired state. If it failed, + there will be information in the node's ``last_error``. + +After creating a node and before moving it from its initial provision state of +``enroll``, basic power and port information needs to be configured on the node. +The Bare Metal service needs this information because it verifies that it is +capable of controlling the node when transitioning the node from ``enroll`` to +``manageable`` state. + +To move a node from ``enroll`` to ``manageable`` provision state:: + + ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID manage + + ironic node-show $NODE_UUID + + +------------------------+--------------------------------------------------------------------+ + | Property | Value | + +------------------------+--------------------------------------------------------------------+ + | ... | ... | + | provision_state | manageable | <- verify correct state + | uuid | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | + | ... | ... | + +------------------------+--------------------------------------------------------------------+ + +When a node is moved from the ``manageable`` to ``available`` provision +state, the node will go through automated cleaning if configured to do so (see +:ref:`configure-cleaning`). +To move a node from ``manageable`` to ``available`` provision state:: + + ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID provide + + ironic node-show $NODE_UUID + + +------------------------+--------------------------------------------------------------------+ + | Property | Value | + +------------------------+--------------------------------------------------------------------+ + | ... | ... | + | provision_state | available | < - verify correct state + | uuid | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | + | ... | ... | + +------------------------+--------------------------------------------------------------------+ + + +For more details on the Bare Metal service's state machine, see the +`state machine `_ +documentation. + + +Logical names +------------- +Beginning with the Kilo release a Node may also be referred to by a +logical name as well as its UUID. Names can be assigned either when +creating the node by adding the ``-n`` option to the ``node-create`` command or +by updating an existing node with the ``node-update`` command. + +Node names must be unique, and conform to: + +- rfc952_ +- rfc1123_ +- wiki_hostname_ + +The node is named 'example' in the following examples: +:: + + ironic node-create -d agent_ipmitool -n example + +or:: + + ironic node-update $NODE_UUID add name=example + + +Once assigned a logical name, a node can then be referred to by name or +UUID interchangeably. +:: + + ironic node-create -d agent_ipmitool -n example + + +--------------+--------------------------------------+ + | Property | Value | + +--------------+--------------------------------------+ + | uuid | 71e01002-8662-434d-aafd-f068f69bb85e | + | driver_info | {} | + | extra | {} | + | driver | agent_ipmitool | + | chassis_uuid | | + | properties | {} | + | name | example | + +--------------+--------------------------------------+ + + + ironic node-show example + + +------------------------+--------------------------------------+ + | Property | Value | + +------------------------+--------------------------------------+ + | target_power_state | None | + | extra | {} | + | last_error | None | + | updated_at | 2015-04-24T16:23:46+00:00 | + | ... | ... | + | instance_info | {} | + +------------------------+--------------------------------------+ + +.. _rfc952: http://tools.ietf.org/html/rfc952 +.. _rfc1123: http://tools.ietf.org/html/rfc1123 +.. _wiki_hostname: http://en.wikipedia.org/wiki/Hostname + + +Hardware Inspection +------------------- + +Starting with the Kilo release, Bare Metal service supports hardware inspection +that simplifies enrolling nodes - please see `inspection`_ for details. + +.. _`inspection`: http://docs.openstack.org/developer/ironic/deploy/inspection.html#inspection diff --git a/install-guide/source/include/configure-neutron-networks.rst b/install-guide/source/include/configure-neutron-networks.rst index 861580d451..0c2339a27f 100644 --- a/install-guide/source/include/configure-neutron-networks.rst +++ b/install-guide/source/include/configure-neutron-networks.rst @@ -11,9 +11,7 @@ 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 `Enrollment`_ section. - -.. _`Enrollment`: http://docs.openstack.org/developer/ironic/deploy/install-guide.html#enrollment +An example of this is shown in the :ref:`enrollment` section. #. Edit ``/etc/neutron/plugins/ml2/ml2_conf.ini`` and modify these: diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst index 112b089529..c49ceb78ab 100644 --- a/install-guide/source/index.rst +++ b/install-guide/source/index.rst @@ -10,8 +10,9 @@ Bare Metal service configure-integration.rst configure-cleaning.rst configure-tenant-networks.rst + enrollment.rst advanced.rst - verify.rst + troubleshooting.rst next-steps.rst The Bare Metal service is a collection of components that provides support to diff --git a/install-guide/source/troubleshooting.rst b/install-guide/source/troubleshooting.rst new file mode 100644 index 0000000000..7740f0e81a --- /dev/null +++ b/install-guide/source/troubleshooting.rst @@ -0,0 +1,126 @@ +.. _troubleshooting: + +=============== +Troubleshooting +=============== + +Once all the services are running and configured properly, and a node has been +enrolled with the Bare Metal service and is in the ``available`` provision +state, the Compute service should detect the node +as an available resource and expose it to the scheduler. + +.. note:: + There is a delay, and it may take up to a minute (one periodic task cycle) + for the Compute service to recognize any changes in the Bare Metal service's + resources (both additions and deletions). + +In addition to watching ``nova-compute`` log files, you can see the available +resources by looking at the list of Compute hypervisors. The resources reported +therein should match the bare metal node properties, and the Compute service flavor. + +Here is an example set of commands to compare the resources in Compute +service and Bare Metal service:: + + $ ironic node-list + +--------------------------------------+---------------+-------------+--------------------+-------------+ + | UUID | Instance UUID | Power State | Provisioning State | Maintenance | + +--------------------------------------+---------------+-------------+--------------------+-------------+ + | 86a2b1bb-8b29-4964-a817-f90031debddb | None | power off | available | False | + +--------------------------------------+---------------+-------------+--------------------+-------------+ + + $ ironic node-show 86a2b1bb-8b29-4964-a817-f90031debddb + +------------------------+----------------------------------------------------------------------+ + | Property | Value | + +------------------------+----------------------------------------------------------------------+ + | instance_uuid | None | + | properties | {u'memory_mb': u'1024', u'cpu_arch': u'x86_64', u'local_gb': u'10', | + | | u'cpus': u'1'} | + | maintenance | False | + | driver_info | { [SNIP] } | + | extra | {} | + | last_error | None | + | created_at | 2014-11-20T23:57:03+00:00 | + | target_provision_state | None | + | driver | pxe_ipmitool | + | updated_at | 2014-11-21T00:47:34+00:00 | + | instance_info | {} | + | chassis_uuid | 7b49bbc5-2eb7-4269-b6ea-3f1a51448a59 | + | provision_state | available | + | reservation | None | + | power_state | power off | + | console_enabled | False | + | uuid | 86a2b1bb-8b29-4964-a817-f90031debddb | + +------------------------+----------------------------------------------------------------------+ + + $ nova hypervisor-show 1 + +-------------------------+--------------------------------------+ + | Property | Value | + +-------------------------+--------------------------------------+ + | cpu_info | baremetal cpu | + | current_workload | 0 | + | disk_available_least | - | + | free_disk_gb | 10 | + | free_ram_mb | 1024 | + | host_ip | [ SNIP ] | + | hypervisor_hostname | 86a2b1bb-8b29-4964-a817-f90031debddb | + | hypervisor_type | ironic | + | hypervisor_version | 1 | + | id | 1 | + | local_gb | 10 | + | local_gb_used | 0 | + | memory_mb | 1024 | + | memory_mb_used | 0 | + | running_vms | 0 | + | service_disabled_reason | - | + | service_host | my-test-host | + | service_id | 6 | + | state | up | + | status | enabled | + | vcpus | 1 | + | vcpus_used | 0 | + +-------------------------+--------------------------------------+ + +.. _maintenance_mode: + +Maintenance mode +---------------- +Maintenance mode may be used if you need to take a node out of the resource +pool. Putting a node in maintenance mode will prevent Bare Metal service from +executing periodic tasks associated with the node. This will also prevent +Compute service from placing a tenant instance on the node by not exposing +the node to the nova scheduler. Nodes can be placed into maintenance mode +with the following command. +:: + + $ ironic node-set-maintenance $NODE_UUID on + +As of the Kilo release, a maintenance reason may be included with the optional +``--reason`` command line option. This is a free form text field that will be +displayed in the ``maintenance_reason`` section of the ``node-show`` command. +:: + + $ ironic node-set-maintenance $UUID on --reason "Need to add ram." + + $ ironic node-show $UUID + + +------------------------+--------------------------------------+ + | Property | Value | + +------------------------+--------------------------------------+ + | target_power_state | None | + | extra | {} | + | last_error | None | + | updated_at | 2015-04-27T15:43:58+00:00 | + | maintenance_reason | Need to add ram. | + | ... | ... | + | maintenance | True | + | ... | ... | + +------------------------+--------------------------------------+ + +To remove maintenance mode and clear any ``maintenance_reason`` use the +following command. +:: + + $ ironic node-set-maintenance $NODE_UUID off + + +.. _ironic-python-agent: http://docs.openstack.org/developer/ironic-python-agent/ diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst deleted file mode 100644 index 5a3b96278a..0000000000 --- a/install-guide/source/verify.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _verify: - -================ -Verify operation -================ - -To verify the operation of the Bare Metal service, please see the -`Troubleshooting`_ section of the legacy installation guide. - -.. _`Troubleshooting`: http://docs.openstack.org/developer/ironic/deploy/install-guide.html#troubleshooting