1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
How it works
============
Integration with Ironic
-----------------------
For information on how to install and configure Ironic drivers, including
drivers for IPA, see the :ironic-doc:`Ironic drivers documentation
</admin/drivers/ipa.html>`.
Lookup
~~~~~~
On startup, the agent performs a lookup in Ironic to determine its node UUID
by sending a hardware profile to the Ironic lookup endpoint:
`/v1/lookup
<https://docs.openstack.org/api-ref/baremetal/?expanded=agent-lookup-detail#agent-lookup>`_.
Heartbeat
~~~~~~~~~
After successfully looking up its node, the agent heartbeats via
`/v1/heartbeat/{node_ident}
<https://docs.openstack.org/api-ref/baremetal/?expanded=agent-heartbeat-detail#agent-heartbeat>`_
every N seconds, where N is the Ironic conductor's ``agent.heartbeat_timeout``
value multiplied by a number between .3 and .6.
For example, if your conductor's ironic.conf contains::
[agent]
heartbeat_timeout = 60
IPA will heartbeat between every 20 and 36 seconds. This is to ensure jitter
for any agents reconnecting after a network or API disruption.
After the agent heartbeats, the conductor performs any actions needed against
the node, including querying status of an already run command. For example,
initiating in-band cleaning tasks or deploying an image to the node.
Inspection
----------
IPA can conduct hardware inspection on start up and post data to the
:ironic-inspector-doc:`Ironic Inspector <>` via the `/v1/continue
<https://docs.openstack.org/api-ref/baremetal-introspection/?expanded=ramdisk-callback-detail#ramdisk-callback>`_
endpoint.
Edit your default PXE/iPXE configuration or IPA options baked in the image, and
set ``ipa-inspection-callback-url`` to the full endpoint of Ironic Inspector,
for example::
ipa-inspection-callback-url=http://IP:5050/v1/continue
Make sure your DHCP environment is set to boot IPA by default.
For the cases where the infrastructure operator and cloud user are the same,
an additional tool exists that can be installed alongside the agent inside
a running instance. This is the ``ironic-collect-introspection-data``
command which allows for a node in ``ACTIVE`` state to publish updated
introspection data to ironic-inspector. This ability requires ironic-inspector
to be configured with ``[processing]permit_active_introspection`` set to
``True``. For example::
ironic-collect-introspection-data --inspection_callback_url http://IP:5050/v1/continue
Alternatively, this command may also be used with multicast DNS
functionality to identify the Ironic Inspector service endpoint. For example::
ironic-collect-introspection-data --inspection_callback_url mdns
An additional daemon mode may be useful for some operators who wish to receive
regular updates, in the form of the ``[DEFAULT]introspection_daemon`` boolean
configuration option.
For example::
ironic-collect-introspection-data --inspection_callback_url mdns --introspection_daemon
The above command will attempt to connect to introspection and will then enter
a loop to publish every 300 seconds. This can be tuned with the
``[DEFAULT]introspection_daemon_post_interval`` configuration option.
Inspection Data
~~~~~~~~~~~~~~~
As part of the inspection process, data is collected on the machine and sent
back to :ironic-inspector-doc:`Ironic Inspector <>` for storage. It can be
accessed via the `introspection data API
<https://docs.openstack.org/api-ref/baremetal-introspection/?expanded=get-introspection-data-detail#get-introspection-data>`_.
The exact format of the data depends on the enabled *collectors*, which can be
configured using the ``ipa-inspection-collectors`` kernel parameter. Each
collector appends information to the resulting JSON object. The in-tree
collectors are:
``default``
The default enabled collectors. Collects the following keys:
* ``inventory`` - `Hardware Inventory`_.
* ``root_disk`` - The default root device for this machine, which will be
used for deployment if root device hints are not provided.
* ``configuration`` - Inspection configuration, an object with two keys:
* ``collectors`` - List of enabled collectors.
* ``managers`` - List of enabled :ref:`Hardware Managers`: items with
keys ``name`` and ``version``.
* ``boot_interface`` - Deprecated, use the
``inventory.boot.pxe_interface`` field.
``logs``
Collect system logs. To yield useful results it must always go last in the
list of collectors. Provides one key:
* ``logs`` - base64 encoded tarball with various logs.
``pci-devices``
Collects the list of PCI devices. Provides one key:
* ``pci_devices`` - list of objects with keys ``vendor_id`` and
``product_id``.
``extra-hardware``
Collects a vast list of facts about the systems, using the hardware_
library, which is a required dependency for this collector. Adds one key:
* ``data`` - raw data from the ``hardware-collect`` utility. Is a list of
lists with 4 items each. It is recommended to use this collector together
with the ``extra_hardware`` processing hook on the Ironic Inspector
side to convert it to a nested dictionary in the ``extra`` key.
If ``ipa-inspection-benchmarks`` is set, the corresponding benchmarks are
executed and their result is also provided.
``dmi-decode``
Collects information from ``dmidecode``. Provides one key:
* ``dmi`` DMI information in three keys: ``bios``, ``cpu`` and ``memory``.
.. TODO(dtantsur): figure out details
``numa-topology``
Collects NUMA_ topology information. Provides one key:
* ``numa_topology`` with three nested keys:
* ``ram`` - list of objects with keys ``numa_node`` (node ID) and
``size_kb``.
* ``cpus`` - list of objects with keys ``cpu`` (CPU ID), ``numa_node``
(node ID) and ``thread_siblings`` (list of sibling threads).
* ``nics`` - list of objects with keys ``name`` (NIC name) and
``numa_node`` (node ID).
``lldp``
Collects information about the network connectivity using LLDP_. Provides
one key:
* ``lldp_raw`` - mapping of interface names to lists of raw
type-length-value (TLV) records.
.. _hardware: https://pypi.org/project/hardware/
.. _NUMA: https://en.wikipedia.org/wiki/Non-uniform_memory_access
.. _LLDP: https://en.wikipedia.org/wiki/Link_Layer_Discovery_Protocol
.. _hardware-inventory:
Hardware Inventory
------------------
IPA collects various hardware information using its
:doc:`Hardware Managers <../contributor/hardware_managers>`,
and sends it to Ironic on lookup and to Ironic Inspector on Inspection_.
The exact format of the inventory depends on the hardware manager used.
Here is the basic format expected to be provided by all hardware managers.
The inventory is a dictionary (JSON object), containing at least the following
fields:
``cpu``
CPU information: ``model_name``, ``frequency``, ``count``,
``architecture`` and ``flags``.
``memory``
RAM information: ``total`` (total size in bytes), ``physical_mb``
(physically installed memory size in MiB, optional).
.. note::
The difference is that the latter includes the memory region reserved
by the kernel and is always slightly bigger. It also matches what
the Nova flavor would contain for this node and thus is used by the
inspection process instead of ``total``.
``bmc_address``
IPv4 address of the node's BMC (aka IPMI v4 address), optional.
``bmc_v6address``
IPv6 address of the node's BMC (aka IPMI v6 address), optional.
``disks``
list of disk block devices with fields: ``name``, ``model``,
``size`` (in bytes), ``rotational`` (boolean), ``wwn``, ``serial``,
``uuid``, ``vendor``, ``wwn_with_extension``, ``wwn_vendor_extension``,
``hctl`` and ``by_path`` (the full disk path, in the form
``/dev/disk/by-path/<rest-of-path>``).
``interfaces``
list of network interfaces with fields: ``name``, ``mac_address``,
``ipv4_address``, ``lldp``, ``vendor``, ``product``, and optionally
``biosdevname`` (BIOS given NIC name).
.. note::
For backward compatibility, interfaces may contain ``lldp`` fields.
They are deprecated, consumers should rely on the ``lldp`` inspection
collector instead.
``system_vendor``
system vendor information from SMBIOS as reported by ``dmidecode``:
``product_name``, ``serial_number`` and ``manufacturer``, as well as
a ``firmware`` structure with fields ``vendor``, ``version`` and
``build_date``.
``boot``
boot information with fields: ``current_boot_mode`` (boot mode used for
the current boot - BIOS or UEFI) and ``pxe_interface`` (interface used
for PXE booting, if any).
``hostname``
hostname for the system
.. note::
This is most likely to be set by the DHCP server. Could be localhost
if the DHCP server does not set it.
Image Checksums
---------------
As part of the process of downloading images to be written to disk as part of
image deployment, a series of fields are utilized to determine if the
image which has been downloaded matches what the user stated as the expected
image checksum utilizing the ``instance_info/image_checksum`` value.
OpenStack, as a whole, has replaced the "legacy" ``checksum`` field with
``os_hash_value`` and ``os_hash_algo`` fields, which allows for an image
checksum and value to be asserted. An advantage of this is a variety of
algorithms are available, if a user/operator is so-inclined.
For the purposes of Ironic, we continue to support the pass-through checksum
field as we support the checksum being retrieved via a URL.
We also support determining the checksum by length.
The field can be utilized to designate:
* A URL to retreive a checksum from.
* MD5 (Disabled by default, see ``[DEFAULT]md5_enabled`` in the agent
configuration file.)
* SHA-2 based SHA256
* SHA-2 based SHA512
SHA-3 based checksums are not supported for auto-determination as they can
have a variable length checksum result. At of when this documentation was
added, SHA-2 based checksum algorithms have not been withdrawn from from
approval. If you need to force use of SHA-3 based checksums, you *must*
utilize the ``os_hash_algo`` setting along with the ``os_hash_value``
setting.
|
