Bare Metal API¶

API 版本¶

概念¶

为了随着时间的推移为用户带来新功能，Ironic API 支持版本控制。Ironic 中有两种类型的版本。

‘’主要版本’’, 它们具有专用的 URL。
‘’微版本’’, 可以通过使用 X-OpenStack-Ironic-API-Version 头或新的标准单数头 OpenStack-API-Version: baremetal <version> 来请求。

版本 API 的工作方式与其他 API 不同，因为它们不需要身份验证。

在 Dalmatian 版本发布后，所有 API 请求都支持新的标准单数头 OpenStack-API-Version: baremetal <version>。如果未提供该头，我们将回退到旧的头。

从 Kilo 版本开始，所有 API 请求都支持 X-OpenStack-Ironic-API-Version 头。应该在每个请求中提供此头；如果没有此头，则将每个请求视为来自较旧的 Kilo 之前的客户端。这是为了保留向后兼容性，因为我们在服务器中引入了新功能。

如果您尝试使用 API 版本早于该功能引入时的功能，ironic 服务将响应，就好像该功能不存在一样。例如，如果添加了新的 API URL，并且您尝试使用旧的 API 版本发出请求，那么您将收到 Not Found (404) 错误，或者如果将新字段添加到现有的 API 并且您请求旧的 API 版本，那么您将收到 Invalid Parameter 响应。

GET

列出 API 版本

这将获取部署中所有已知主要 API 版本的所有信息。将为每个主要 API 版本提供指向更具体信息的链接，以及有关支持的最小和最大微版本的信息。

正常响应代码：200

请求¶

响应示例¶

名称	入参	类型	描述
description	body	字符串	关于 Ironic 服务的描述性文本。
versions	body	数组	当前支持的版本信息的数组。
版本	body	字符串	此 API 响应的版本，例如“1.22”。
id	body	字符串	主要的 API 版本，例如“v1”
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
min_version	标头	字符串	此端点支持的最小 API 微版本，例如“1.1”

{
  "default_version": {
    "id": "v1",
    "links": [
      {
        "href": "http://127.0.0.1:6385/v1/",
        "rel": "self"
      }
    ],
    "min_version": "1.1",
    "status": "CURRENT",
    "version": "1.37"
  },
  "description": "Ironic is an OpenStack project which enables the provision and management of baremetal machines.",
  "name": "OpenStack Ironic API",
  "versions": [
    {
      "id": "v1",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/",
          "rel": "self"
        }
      ],
      "min_version": "1.1",
      "status": "CURRENT",
      "version": "1.37"
    }
  ]
}

GET

/v1/

显示 v1 API

显示 Ironic v1 API 中的所有资源。

正常响应代码：200

请求¶

响应示例¶

名称	入参	类型	描述
id	body	字符串	主要的 API 版本，例如“v1”
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
openstack-request-id (可选)	标头	字符串	用于跟踪请求的唯一 ID。与该请求关联的请求 ID 出现在该请求的日志行中。默认情况下，中间件配置可确保请求 ID 出现在日志文件中。
x-openstack-ironic-api-version	标头	字符串	用于生成此响应的特定 API 微版本。
x-openstack-ironic-api-min-version	标头	字符串	此端点支持的最小 API 微版本，例如“1.1”
x-openstack-ironic-api-max-version	标头	字符串	此端点支持的最大 API 微版本，例如“1.22”

{
  "chassis": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/",
      "rel": "bookmark"
    }
  ],
  "drivers": [
    {
      "href": "http://127.0.0.1:6385/v1/drivers/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/drivers/",
      "rel": "bookmark"
    }
  ],
  "heartbeat": [
    {
      "href": "http://127.0.0.1:6385/v1/heartbeat/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/heartbeat/",
      "rel": "bookmark"
    }
  ],
  "id": "v1",
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/",
      "rel": "self"
    },
    {
      "href": "https://docs.openstack.org/ironic/2025.2/contributor/webapi.html",
      "rel": "describedby",
      "type": "text/html"
    }
  ],
  "lookup": [
    {
      "href": "http://127.0.0.1:6385/v1/lookup/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/lookup/",
      "rel": "bookmark"
    }
  ],
  "media_types": [
    {
      "base": "application/json",
      "type": "application/vnd.openstack.ironic.v1+json"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/",
      "rel": "bookmark"
    }
  ],
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/",
      "rel": "bookmark"
    }
  ],
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/",
      "rel": "bookmark"
    }
  ]
}

节点 (nodes)¶

通过 /v1/nodes 资源完成对 bare metal 节点资源的列出、搜索、创建、更新和删除。还有几个子资源，允许对 bare metal 节点执行进一步的操作。

节点是可分配服务器的规范表示形式，能够运行操作系统。每个节点必须与 driver 关联；这告知 Ironic 在管理节点时使用什么协议。

版本 1.6 中更改：节点可以通过其 UUID 和任何请求中的唯一的人类可读“名称”来引用。在整个文档中，这被称为 node_ident。响应清楚地表明给定的字段是 uuid 还是 name。

版本 1.91 中更改：在较旧的 API 版本中，我们启用了一个 pecan 功能，该功能会从资源引用查询的末尾删除 .json 扩展名，并将其视为仅通过其 UUID 或 node_ident 引用。例如，0178-0c2c-9c26-ca69-3011-a9dd.json，被视为 0178-0c2c-9c26-ca69-3011-a9dd。此功能现在在较新的 API 版本中已禁用。

根据分配给经过身份验证的 OpenStack 用户的作用以及 Bare Metal 服务的配置，API 响应可能会发生变化。例如，“show_password”设置的默认值导致所有 API 响应在 driver_info 中用文字字符串“******”屏蔽密码。

POST

/v1/nodes

创建节点

创建一个新的节点资源。

此方法要求在请求主体中提供 driver。节点的许多子资源（例如，properties、driver_info 等）可以在创建节点时提供，也可以稍后更新资源。

版本 1.2 中添加：添加了 available 状态名称，它取代了 None 作为未配置节点的状态。所有客户端都应更新为使用新的 available 状态名称。处于 available 状态的节点可以为其配置工作负载；它们“可用”于使用。

版本 1.5 中添加：引入了 name 字段。

版本 1.7 中添加：引入了 clean_step 字段。

版本 1.11 中更改：新创建的节点的默认初始状态从 available 更改为 enroll。这为用户提供了一个工作流程，用于验证节点的管理能力并执行必要的操作功能（例如，构建 RAID 阵列），然后再使节点可用于配置。

版本 1.12 中添加：引入了对 raid_config 和 target_raid_config 字段的支持。

版本 1.20 中添加：引入了 network_interface 字段。如果创建节点时未提供此字段，则将使用默认值。

版本 1.21 中添加：引入了 resource_class 字段，可用于将资源指定存储到提议的 OpenStack Placement Engine。此字段在 Ironic 中没有效果。

版本 1.31 中添加：引入了 boot_interface、deploy_interface、management_interface、power_interface、inspect_interface、console_interface、vendor_interface 和 raid_interface 字段。如果创建节点时未提供这些字段中的任何一个，则将使用其默认值。

版本 1.31 中更改：如果指定的驱动程序是动态驱动程序，则所有接口（boot_interface、deploy_interface 等）都将设置为该驱动程序的默认接口，除非在创建请求中指定了另一个启用的接口。

版本 1.33 中添加：引入了 storage_interface 字段。如果创建节点时未提供此字段，则将使用默认值。

版本 1.38 中添加：引入了 rescue_interface 字段。如果创建节点时未提供此字段，则将使用默认值。

版本 1.44 中添加：引入了 deploy_step 字段。

版本 1.46 中添加：引入了 conductor_group 字段。

版本 1.50 中添加：引入了 owner 字段。

版本 1.51 中添加：引入了 description 字段。

版本 1.52 中添加：引入了 allocation_uuid 字段。

版本 1.65 中添加：引入了 lessee 字段。

版本 1.82 中添加：引入了 shard 字段。

版本 1.83 中添加：引入了 parent_node 字段。

版本 1.95 中添加：引入了 disable_power_off 字段。

版本 1.104 中添加：引入了 instance_name 字段。

正常响应代码：201

错误代码：400,403,406

请求¶

名称	入参	类型	描述
boot_interface (可选)	body	字符串	节点的启动接口，例如“pxe”。
conductor_group (可选)	body	字符串	节点的 conductor 组。最多 255 个字符的区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
console_interface (可选)	body	字符串	节点的控制台接口，例如“no-console”。
deploy_interface (可选)	body	字符串	节点的部署接口，例如“iscsi”。
disable_power_off (可选)	body	布尔值	如果设置为 `true`，则明确禁用节点的关机功能，而是使用重启代替开/关电。此外，如果可能，节点将被禁用（即，其 API 代理将变得不可用，并且将删除网络配置），而不是关机。
driver_info (可选)	body	JSON	驱动程序管理此节点所需的所有元数据。字段列表因驱动程序而异，可以从 `/v1/drivers/<DRIVER_NAME>/properties` 资源中检索。
driver	body	字符串	用于管理此节点的驱动程序的名称。
extra (可选)	body	对象	一组或多组任意元数据键值对。
inspect_interface (可选)	body	字符串	用于节点检查的接口，例如“no-inspect”。
management_interface (可选)	body	字符串	用于节点带外管理的接口，例如“ipmitool”。
name (可选)	body	字符串	节点的资源的易于理解的标识符。可以是未定义的。某些单词是保留的。
network_interface (可选)	body	字符串	在部署和清理期间用于此节点的网络接口提供程序。
power_interface (可选)	body	字符串	用于对节点执行电源操作的接口，例如“ipmitool”。
properties (可选)	body	JSON	此节点的物理特性。如果在执行检查时执行，则填充。可以随时通过 REST API 进行编辑。
raid_interface (可选)	body	字符串	用于在此节点上配置 RAID 的接口，例如“no-raid”。
rescue_interface (可选)	body	字符串	用于节点救援的接口，例如“no-rescue”。
resource_class (可选)	body	字符串	一个字符串，可供外部调度程序将此节点识别为特定类型的资源的单元。
storage_interface (可选)	body	字符串	用于在此节点上附加和分离卷的接口，例如“cinder”。
uuid (可选)	body	字符串	资源的 UUID。
vendor_interface (可选)	body	字符串	用于此节点上特定于供应商的功能的接口，例如“no-vendor”。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
description (可选)	body	字符串	关于此节点的说明性文本。
lessee (可选)	body	字符串	租赁该对象的租户的字符串或 UUID。
shard (可选)	body	字符串	一个字符串，指示此节点所属的分片。
automated_clean (可选)	body	布尔值	指示节点是否将执行自动清理。
bios_interface (可选)	body	字符串	要用于此节点的 BIOS 接口。
chassis_uuid (可选)	body	字符串	与此节点关联的机箱的 UUID。可以为空或 None。
instance_info (可选)	body	JSON	用于自定义已部署镜像的信息。可能包括根分区大小、base64 编码的 config drive 和其他元数据。请注意，此字段在删除实例时会自动擦除（这是通过请求将节点置备状态更改为 DELETED 来完成的）。
instance_uuid (可选)	body	字符串	与此节点关联的 Nova 实例的 UUID。注意此字段不遵循标准的 JSON PATCH RFC 6902 行为。 “add” 操作符无法替换现有的 instance_uuid 值。尝试这样做将导致 409 Conflict 错误（NodeAssociated 异常）。此保护可防止多个 Nova 计算代理尝试关联相同的节点时发生竞争条件。
instance_name (可选)	body	字符串	部署在此节点上的实例的人类可读名称。为了与节点的 `instance_info` 中的 `display_name` 同步，以便与 Nova 保持向后兼容。
maintenance (可选)	body	布尔值	指示此节点是否当前处于“维护模式”。将节点置于维护模式会将其从可用资源池中删除并停止某些内部自动化。这可以手动完成（例如，通过 API 请求），也可以在 Ironic 检测到阻止与机器通信的硬件故障时自动完成。
maintenance_reason (可选)	body	字符串	用户可设置的描述，说明为什么将此节点置于维护模式
network_data (可选)	body	JSON	在部署和清理期间使用的 OpenStack 网络数据格式的静态网络配置。需要专门构建的 ramdisk，请参阅 DHCP-less 文档。
parent_node (可选)	body	字符串	一个可选的 UUID，可用于表示“父”baremetal 节点。
protected (可选)	body	布尔值	是否保护节点免于取消配置、重建和删除。
protected_reason (可选)	body	字符串	节点被标记为受保护的原因。
retired (可选)	body	布尔值	节点是否已退役，因此不再能被提供，即从 `manageable` 变为 `available`，并在清理后最终变为 `manageable`（而不是 `available`）。
retired_reason (可选)	body	字符串	节点被标记为退役的原因。

使用动态驱动程序的节点创建请求示例

{
    "name": "test_node_dynamic",
    "driver": "ipmi",
    "driver_info": {
        "ipmi_username": "ADMIN",
        "ipmi_password": "password"
    },
    "power_interface": "ipmitool",
    "resource_class": "bm-large"
}

响应¶

响应将包含完整的节点记录，其中包含提供的数据以及为未指定字段添加的任何默认值。大多数字段默认为“null”或“”。

以下列表和示例代表 API 微版本 1.95 时的响应。

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name (可选)	body	字符串	节点的资源的易于理解的标识符。可以是未定义的。某些单词是保留的。
power_state	body	字符串	此节点的当前电源状态。通常为“power on”（开机）或“power off”（关机），但如果 Ironic 无法确定电源状态（例如，由于硬件故障），则可能是“None”。
target_power_state	body	字符串	如果已请求电源状态转换，则此字段表示请求的（即“目标”）状态，可以是“power on”（开机）或“power off”（关机）。
provision_state	body	字符串	此节点的当前配置状态。
target_provision_state	body	字符串	如果已请求配置操作，则此字段表示请求的（即“目标”）状态。请注意，节点在过渡到此目标状态时可能会经历几个状态。例如，当请求将实例部署到 AVAILABLE 节点时，节点可能会经历以下状态更改过程：AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
maintenance	body	布尔值	指示此节点是否当前处于“维护模式”。将节点置于维护模式会将其从可用资源池中删除并停止某些内部自动化。这可以手动完成（例如，通过 API 请求），也可以在 Ironic 检测到阻止与机器通信的硬件故障时自动完成。
maintenance_reason (可选)	body	字符串	用户可设置的描述，说明为什么将此节点置于维护模式
fault (可选)	body	字符串	故障指示 ironic 检测到的活动故障，通常节点处于“维护模式”。None 表示 ironic 未检测到任何故障。“power failure”（电源故障）表示 ironic 无法从此节点检索电源状态。还有其他可能的类型，例如“clean failure”（清理失败）和“rescue abort failure”（救援中止失败）。
last_error	body	字符串	最近一次启动但未能完成的事务中的任何错误。
reservation	body	字符串	如果持有锁，则为持有此节点锁的 Ironic Conductor 主机的 `name`。通常为“null”，但此字段对于调试很有用。
driver	body	字符串	驱动程序的名称。
driver_info	body	JSON	驱动程序管理此节点所需的所有元数据。字段列表因驱动程序而异，可以从 `/v1/drivers/<DRIVER_NAME>/properties` 资源中检索。
driver_internal_info (可选)	body	JSON	由节点的驱动程序设置和存储的内部元数据。此字段为只读。
properties	body	JSON	此节点的物理特性。在检查期间填充。可以随时通过 REST API 进行编辑。
instance_info	body	JSON	用于自定义已部署镜像的信息。可能包括根分区大小、base64 编码的 config drive 和其他元数据。请注意，此字段在删除实例时会自动擦除（这是通过请求将节点置备状态更改为 DELETED 来完成的）。
instance_uuid	body	字符串	与此节点关联的 Nova 实例的 UUID。注意此字段不遵循标准的 JSON PATCH RFC 6902 行为。 “add” 操作符无法替换现有的 instance_uuid 值。尝试这样做将导致 409 Conflict 错误（NodeAssociated 异常）。此保护可防止多个 Nova 计算代理尝试关联相同的节点时发生竞争条件。
instance_name (可选)	body	字符串	部署在此节点上的实例的人类可读名称。为了与节点的 `instance_info` 中的 `display_name` 同步，以便与 Nova 保持向后兼容。
chassis_uuid	body	字符串	与此节点关联的机箱的 UUID。可以为空或 None。
extra	body	对象	一组或多组任意元数据键值对。
console_enabled	body	布尔值	指示在此节点上是否启用或禁用控制台访问。
raid_config (可选)	body	JSON	表示节点的当前 RAID 配置。随清理功能引入。
target_raid_config	body	JSON	表示节点的请求的 RAID 配置，将在节点下次通过 CLEANING 状态转换时应用。随清理功能引入。
clean_step (可选)	body	字符串	当前的清理步骤。随清理功能引入。
deploy_step (可选)	body	字符串	当前的部署步骤。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	指向此节点上端口集合的链接
portgroups	body	数组	指向此节点上端口组集合的链接。
states	body	数组	指向状态集合的链接。请注意，此资源也用于请求状态转换。
resource_class	body	字符串	可由外部调度程序用作特定类型资源单元的此节点的标识符的字符串。有关更多详细信息，请参阅：https://docs.openstack.org/ironic/2025.2/install/configure-nova-flavors.html
boot_interface	body	字符串	节点的启动接口，例如“pxe”。
console_interface	body	字符串	节点的控制台接口，例如“no-console”。
deploy_interface	body	字符串	节点的部署接口，例如“iscsi”。
inspect_interface	body	字符串	用于节点检查的接口，例如“no-inspect”。
management_interface	body	字符串	用于节点带外管理的接口，例如“ipmitool”。
network_interface	body	字符串	在部署和清理期间用于此节点的网络接口提供程序。
power_interface	body	字符串	用于对节点执行电源操作的接口，例如“ipmitool”。
raid_interface	body	字符串	用于在此节点上配置 RAID 的接口，例如“no-raid”。
rescue_interface	body	字符串	用于节点救援的接口，例如“no-rescue”。
storage_interface	body	字符串	用于在此节点上附加和分离卷的接口，例如“cinder”。
traits	body	数组	此节点的特征列表。
vendor_interface	body	字符串	用于此节点上特定于供应商的功能的接口，例如“no-vendor”。
volume	body	数组	指向卷资源的链接。
conductor_group	body	字符串	节点的 conductor 组。最多 255 个字符的区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
parent_node (可选)	body	字符串	一个可选的 UUID，可用于表示“父”baremetal 节点。
protected (可选)	body	布尔值	是否保护节点免于取消配置、重建和删除。
protected_reason (可选)	body	字符串	节点被标记为受保护的原因。
conductor (可选)	body	字符串	当前服务于节点的 Conductor。此字段为只读。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
lessee (可选)	body	字符串	租赁该对象的租户的字符串或 UUID。
shard (可选)	body	字符串	一个字符串，指示此节点所属的分片。
description	body	字符串	关于此节点的说明性文本。
allocation_uuid	body	字符串	与节点关联的分配的 UUID。如果不是 `null`，将与 `instance_uuid` 相同（反之不一定成立）。与 `instance_uuid` 不同，此字段为只读。请使用 Allocation API 删除分配。
automated_clean	body	布尔值	指示节点是否将执行自动清理。
bios_interface	body	字符串	要用于此节点的 BIOS 接口。
network_data (可选)	body	JSON	在部署和清理期间使用的 OpenStack 网络数据格式的静态网络配置。需要专门构建的 ramdisk，请参阅 DHCP-less 文档。
retired (可选)	body	布尔值	节点是否已退役，因此不再能被提供，即从 `manageable` 变为 `available`，并在清理后最终变为 `manageable`（而不是 `available`）。
retired_reason (可选)	body	字符串	节点被标记为退役的原因。
disable_power_off (可选)	body	布尔值	如果设置为 true，则明确禁用节点的关机，而是使用重启代替开机/关机。此外，如果可能，节点将被禁用（即，其 API 代理将变得不可用，并且将删除网络配置），而不是被关机。

Node 的示例 JSON 表示形式

{
  "allocation_uuid": null,
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "conductor_group": "group-1",
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": null,
  "deploy_step": {},
  "description": null,
  "driver": "agent_ipmitool",
  "driver_info": {
    "ipmi_password": "******",
    "ipmi_username": "ADMIN"
  },
  "driver_internal_info": {},
  "extra": {},
  "inspect_interface": null,
  "inspection_finished_at": null,
  "inspection_started_at": null,
  "instance_info": {},
  "instance_uuid": null,
  "instance_name": null,
  "last_error": null,
  "lessee": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "bookmark"
    }
  ],
  "maintenance": false,
  "maintenance_reason": null,
  "management_interface": null,
  "name": "test_node_classic",
  "network_data": {},
  "network_interface": "flat",
  "owner": null,
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "bookmark"
    }
  ],
  "power_interface": null,
  "power_state": null,
  "properties": {},
  "protected": false,
  "protected_reason": null,
  "provision_state": "enroll",
  "provision_updated_at": null,
  "raid_config": {},
  "raid_interface": null,
  "rescue_interface": null,
  "reservation": null,
  "resource_class": "bm-large",
  "retired": false,
  "retired_reason": null,
  "states": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "bookmark"
    }
  ],
  "storage_interface": "noop",
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "traits": [],
  "updated_at": null,
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null,
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "bookmark"
    }
  ]
}

GET

/v1/nodes

列出节点

返回一个裸机节点列表，其中包含有关每个节点的有用信息。可以通过在请求中传递标志来进行一些过滤。

默认情况下，此查询将返回每个节点的名称、uuid、实例 uuid、电源状态、配置状态和维护设置。

版本 1.8 中添加：添加了 fields 请求参数。如果指定，这将导致响应的内容仅包含指定的字段，而不是默认集合。

版本 1.9 中添加：添加了 provision_state 请求参数，允许按其当前状态过滤返回的节点列表。

版本 1.16 中添加：添加了 driver 请求参数，允许按驱动程序名称过滤返回的节点列表。

版本 1.21 中添加：添加了 resource_class 请求参数，允许按此字段过滤返回的节点列表。

版本 1.42 中添加：引入了 fault 字段。

版本 1.43 中添加：添加了 detail 布尔请求参数。如果指定 True，这将导致响应包含每个节点的完整详细信息，如“列出节点详细信息”部分中所示。

版本 1.46 中添加：引入了 conductor_group 请求参数，以允许按 Conductor 组过滤返回的节点列表。

版本 1.49 中添加：引入了 conductor 请求参数，以允许按 Conductor 过滤返回的节点列表。

版本 1.50 中添加：引入了 owner 字段。

版本 1.51 中添加：引入了 description 字段。

版本 1.65 中添加：引入了 lessee 字段。

版本 1.82 中添加：引入了 shard 字段。引入了 sharded 请求参数。

版本 1.83 中添加：引入了 parent_node 字段和查询参数，以识别匹配的节点。引入了 include_children 参数，该参数允许枚举所有子节点，通常子节点不打算由最终用户直接使用。

版本 1.104 中添加：引入了 instance_name 查询参数和响应字段。

正常响应代码：200

错误代码：400,403,406

请求¶

名称	入参	类型	描述
instance_uuid (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有此特定实例 UUID 的节点，或者如果未找到则返回空集。
instance_name (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有此特定实例名称的节点，或者如果未找到则返回空集。
maintenance (可选)	查询	布尔值	过滤返回的节点列表，并仅返回 `maintenance` 设置为 `True` 或 `False` 的节点。
associated (可选)	查询	布尔值	过滤返回的节点列表，并仅返回与 `instance_uuid` 关联的节点，或者不关联的节点。
provision_state (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `provision_state` 的节点。
driver (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `driver` 的节点。
resource_class (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的资源类的节点。
conductor_group (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `conductor_group` 的节点。最多 255 个字符的不区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
conductor (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `conductor` 的节点。
fault (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `fault` 的节点。可能的值由 ironic 支持的故障确定，例如 `power failure`、“`clean failure`”或“`rescue abort failure`”。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
lessee (可选)	body	字符串	租赁该对象的租户的字符串或 UUID。
shard (可选)	body	数组	过滤返回的节点列表，并仅返回与此特定分片（或分片）关联的节点，或者如果未找到则返回空集。
sharded (可选)	body	布尔值	如果为 true，则过滤返回的节点列表，并仅返回具有非空 `shard` 值的节点。如果为 false，则执行反向过滤。
description_contains (可选)	查询	字符串	过滤返回的节点列表，并仅返回包含 `description_contains` 指定的子字符串的节点。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。
parent_node (可选)	body	字符串	一个可选的 UUID，可用于表示“父”baremetal 节点。
include_children (可选)	查询	布尔值	是否在节点列表中显示子节点，通常子节点是隐藏的。

Response¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name (可选)	body	字符串	节点的资源的易于理解的标识符。可以是未定义的。某些单词是保留的。
instance_uuid	body	字符串	与此节点关联的 Nova 实例的 UUID。注意此字段不遵循标准的 JSON PATCH RFC 6902 行为。 “add” 操作符无法替换现有的 instance_uuid 值。尝试这样做将导致 409 Conflict 错误（NodeAssociated 异常）。此保护可防止多个 Nova 计算代理尝试关联相同的节点时发生竞争条件。
power_state	body	字符串	此节点的当前电源状态。通常为“power on”（开机）或“power off”（关机），但如果 Ironic 无法确定电源状态（例如，由于硬件故障），则可能是“None”。
provision_state	body	字符串	此节点的当前配置状态。
maintenance	body	布尔值	指示此节点是否当前处于“维护模式”。将节点置于维护模式会将其从可用资源池中删除并停止某些内部自动化。这可以手动完成（例如，通过 API 请求），也可以在 Ironic 检测到阻止与机器通信的硬件故障时自动完成。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

节点列表示例

{
  "nodes": [
    {
      "instance_uuid": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "name": "test_node_classic",
      "power_state": "power off",
      "provision_state": "available",
      "uuid": "6d85703a-565d-469a-96ce-30b6de53079d"
    },
    {
      "instance_uuid": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "name": "test_node_dynamic",
      "power_state": null,
      "provision_state": "enroll",
      "uuid": "2b045129-a906-46af-bc1a-092b294b3428"
    }
  ]
}

GET

/v1/nodes/detail

列出节点详细信息

版本 Use: ?detail=True 查询字符串代替。

返回带有完整详细信息的裸机节点列表。可以通过在请求中传递标志来进行一些过滤。

此方法特别适用于找到与给定 Nova 实例关联的节点，例如使用请求 v1/nodes/detail?instance_uuid={NOVA INSTANCE UUID}

版本 1.37 中添加：引入了 traits 字段。

版本 1.38 中添加：引入了 rescue_interface 字段。

版本 1.42 中添加：引入了 fault 字段。

版本 1.46 中添加：引入了 conductor_group 字段。

版本 1.48 中添加：引入了 protected 和 protected_reason 字段。

版本 1.49 中添加：引入了 conductor 请求参数和 conductor 字段。

版本 1.50 中添加：引入了 owner 字段。

版本 1.51 中添加：引入了 description 字段。

版本 1.52 中添加：引入了 allocation_uuid 字段。

版本 1.65 中添加：引入了 lessee 字段。

版本 1.82 中添加：引入了 shard 字段。引入了 sharded 请求参数。

版本 1.104 中添加：引入了 instance_name 字段。

正常响应代码：200

错误代码：400,403,406

请求¶

名称	入参	类型	描述
instance_uuid (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有此特定实例 UUID 的节点，或者如果未找到则返回空集。
instance_name (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有此特定实例名称的节点，或者如果未找到则返回空集。
maintenance (可选)	查询	布尔值	过滤返回的节点列表，并仅返回 `maintenance` 设置为 `True` 或 `False` 的节点。
fault (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `fault` 的节点。可能的值由 ironic 支持的故障确定，例如 `power failure`、“`clean failure`”或“`rescue abort failure`”。
associated (可选)	查询	布尔值	过滤返回的节点列表，并仅返回与 `instance_uuid` 关联的节点，或者不关联的节点。
provision_state (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `provision_state` 的节点。
driver (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `driver` 的节点。
resource_class (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的资源类的节点。
conductor_group (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `conductor_group` 的节点。最多 255 个字符的不区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
conductor (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的 `conductor` 的节点。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
lessee (可选)	body	字符串	租赁该对象的租户的字符串或 UUID。
shard (可选)	body	数组	过滤返回的节点列表，并仅返回与此特定分片（或分片）关联的节点，或者如果未找到则返回空集。
sharded (可选)	body	布尔值	如果为 true，则过滤返回的节点列表，并仅返回具有非空 `shard` 值的节点。如果为 false，则执行反向过滤。
description_contains (可选)	查询	字符串	过滤返回的节点列表，并仅返回包含 `description_contains` 指定的子字符串的节点。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name (可选)	body	字符串	节点的资源的易于理解的标识符。可以是未定义的。某些单词是保留的。
power_state	body	字符串	此节点的当前电源状态。通常为“power on”（开机）或“power off”（关机），但如果 Ironic 无法确定电源状态（例如，由于硬件故障），则可能是“None”。
target_power_state	body	字符串	如果已请求电源状态转换，则此字段表示请求的（即“目标”）状态，可以是“power on”（开机）或“power off”（关机）。
provision_state	body	字符串	此节点的当前配置状态。
target_provision_state	body	字符串	如果已请求配置操作，则此字段表示请求的（即“目标”）状态。请注意，节点在过渡到此目标状态时可能会经历几个状态。例如，当请求将实例部署到 AVAILABLE 节点时，节点可能会经历以下状态更改过程：AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
maintenance	body	布尔值	指示此节点是否当前处于“维护模式”。将节点置于维护模式会将其从可用资源池中删除并停止某些内部自动化。这可以手动完成（例如，通过 API 请求），也可以在 Ironic 检测到阻止与机器通信的硬件故障时自动完成。
maintenance_reason (可选)	body	字符串	用户可设置的描述，说明为什么将此节点置于维护模式
fault (可选)	body	字符串	故障指示 ironic 检测到的活动故障，通常节点处于“维护模式”。None 表示 ironic 未检测到任何故障。“power failure”（电源故障）表示 ironic 无法从此节点检索电源状态。还有其他可能的类型，例如“clean failure”（清理失败）和“rescue abort failure”（救援中止失败）。
last_error	body	字符串	最近一次启动但未能完成的事务中的任何错误。
reservation	body	字符串	如果持有锁，则为持有此节点锁的 Ironic Conductor 主机的 `name`。通常为“null”，但此字段对于调试很有用。
driver	body	字符串	驱动程序的名称。
driver_info	body	JSON	驱动程序管理此节点所需的所有元数据。字段列表因驱动程序而异，可以从 `/v1/drivers/<DRIVER_NAME>/properties` 资源中检索。
driver_internal_info (可选)	body	JSON	由节点的驱动程序设置和存储的内部元数据。此字段为只读。
properties	body	JSON	此节点的物理特性。在检查期间填充。可以随时通过 REST API 进行编辑。
instance_info	body	JSON	用于自定义已部署镜像的信息。可能包括根分区大小、base64 编码的 config drive 和其他元数据。请注意，此字段在删除实例时会自动擦除（这是通过请求将节点置备状态更改为 DELETED 来完成的）。
instance_uuid	body	字符串	与此节点关联的 Nova 实例的 UUID。注意此字段不遵循标准的 JSON PATCH RFC 6902 行为。 “add” 操作符无法替换现有的 instance_uuid 值。尝试这样做将导致 409 Conflict 错误（NodeAssociated 异常）。此保护可防止多个 Nova 计算代理尝试关联相同的节点时发生竞争条件。
instance_name (可选)	body	字符串	部署在此节点上的实例的人类可读名称。为了与节点的 `instance_info` 中的 `display_name` 同步，以便与 Nova 保持向后兼容。
chassis_uuid	body	字符串	与此节点关联的机箱的 UUID。可以为空或 None。
extra	body	对象	一组或多组任意元数据键值对。
console_enabled	body	布尔值	指示在此节点上是否启用或禁用控制台访问。
raid_config (可选)	body	JSON	表示节点的当前 RAID 配置。随清理功能引入。
target_raid_config	body	JSON	表示节点的请求的 RAID 配置，将在节点下次通过 CLEANING 状态转换时应用。随清理功能引入。
clean_step (可选)	body	字符串	当前的清理步骤。随清理功能引入。
deploy_step (可选)	body	字符串	当前的部署步骤。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	指向此节点上端口集合的链接
portgroups	body	数组	指向此节点上端口组集合的链接。
states	body	数组	指向状态集合的链接。请注意，此资源也用于请求状态转换。
resource_class	body	字符串	可由外部调度程序用作特定类型资源单元的此节点的标识符的字符串。有关更多详细信息，请参阅：https://docs.openstack.org/ironic/2025.2/install/configure-nova-flavors.html
bios_interface	body	字符串	要用于此节点的 BIOS 接口。
boot_interface	body	字符串	节点的启动接口，例如“pxe”。
console_interface	body	字符串	节点的控制台接口，例如“no-console”。
deploy_interface	body	字符串	节点的部署接口，例如“iscsi”。
inspect_interface	body	字符串	用于节点检查的接口，例如“no-inspect”。
management_interface	body	字符串	用于节点带外管理的接口，例如“ipmitool”。
network_interface	body	字符串	在部署和清理期间用于此节点的网络接口提供程序。
power_interface	body	字符串	用于对节点执行电源操作的接口，例如“ipmitool”。
raid_interface	body	字符串	用于在此节点上配置 RAID 的接口，例如“no-raid”。
rescue_interface	body	字符串	用于节点救援的接口，例如“no-rescue”。
storage_interface	body	字符串	用于在此节点上附加和分离卷的接口，例如“cinder”。
traits	body	数组	此节点的特征列表。
vendor_interface	body	字符串	用于此节点上特定于供应商的功能的接口，例如“no-vendor”。
volume	body	数组	指向卷资源的链接。
conductor_group	body	字符串	节点的 conductor 组。最多 255 个字符的区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
parent_node (可选)	body	字符串	一个可选的 UUID，可用于表示“父”baremetal 节点。
protected (可选)	body	布尔值	是否保护节点免于取消配置、重建和删除。
protected_reason (可选)	body	字符串	节点被标记为受保护的原因。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
lessee (可选)	body	字符串	租赁该对象的租户的字符串或 UUID。
shard (可选)	body	字符串	一个字符串，指示此节点所属的分片。
description	body	字符串	关于此节点的说明性文本。
conductor (可选)	body	字符串	当前服务于节点的 Conductor。此字段为只读。
allocation_uuid	body	字符串	与节点关联的分配的 UUID。如果不是 `null`，将与 `instance_uuid` 相同（反之不一定成立）。与 `instance_uuid` 不同，此字段为只读。请使用 Allocation API 删除分配。
retired (可选)	body	布尔值	节点是否已退役，因此不再能被提供，即从 `manageable` 变为 `available`，并在清理后最终变为 `manageable`（而不是 `available`）。
retired_reason (可选)	body	字符串	节点被标记为退役的原因。
network_data (可选)	body	JSON	在部署和清理期间使用的 OpenStack 网络数据格式的静态网络配置。需要专门构建的 ramdisk，请参阅 DHCP-less 文档。
automated_clean	body	布尔值	指示节点是否将执行自动清理。
service_step	body	JSON	一个字典，包含要在节点上执行的接口和步骤。该字典必须包含“interface”和“step”键。如果指定，则“args”的值是传递给清理步骤方法的关键字变量参数字典。
firmware_interface	body	字符串	节点的固件接口，例如“redfish”。
provision_updated_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。如果节点未被配置，则为“null”。
inspection_started_at	body	字符串	硬件检查开始的 UTC 日期和时间，ISO 8601 格式。可能为“null”。
inspection_finished_at	body	字符串	最后一次硬件检查成功完成的 UTC 日期和时间，ISO 8601 格式。可能为“null”。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
disable_power_off (可选)	body	布尔值	如果设置为 true，则明确禁用节点的关机，而是使用重启代替开机/关机。此外，如果可能，节点将被禁用（即，其 API 代理将变得不可用，并且将删除网络配置），而不是被关机。

节点详细列表示例

{
  "nodes": [
    {
      "allocation_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
      "boot_interface": null,
      "chassis_uuid": null,
      "clean_step": {},
      "conductor": "compute1.localdomain",
      "conductor_group": "group-1",
      "console_enabled": false,
      "console_interface": null,
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "deploy_interface": null,
      "deploy_step": {},
      "description": null,
      "driver": "fake",
      "driver_info": {
        "ipmi_password": "******",
        "ipmi_username": "ADMIN"
      },
      "driver_internal_info": {
        "clean_steps": null
      },
      "extra": {},
      "inspect_interface": null,
      "inspection_finished_at": null,
      "inspection_started_at": null,
      "instance_info": {},
      "instance_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
      "instance_name": "my-test-instance",
      "last_error": null,
      "lessee": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "maintenance_reason": null,
      "management_interface": null,
      "name": "test_node_classic",
      "network_data": {},
      "network_interface": "flat",
      "owner": "john doe",
      "portgroups": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
          "rel": "bookmark"
        }
      ],
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
          "rel": "bookmark"
        }
      ],
      "power_interface": null,
      "power_state": "power off",
      "properties": {},
      "protected": false,
      "protected_reason": null,
      "provision_state": "available",
      "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
      "raid_config": {},
      "raid_interface": null,
      "rescue_interface": null,
      "reservation": null,
      "resource_class": null,
      "retired": false,
      "retired_reason": null,
      "states": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
          "rel": "bookmark"
        }
      ],
      "storage_interface": "noop",
      "target_power_state": null,
      "target_provision_state": null,
      "target_raid_config": {},
      "traits": [],
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "vendor_interface": null,
      "volume": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
          "rel": "bookmark"
        }
      ]
    },
    {
      "allocation_uuid": null,
      "boot_interface": "pxe",
      "chassis_uuid": null,
      "clean_step": {},
      "conductor": "compute1.localdomain",
      "conductor_group": "",
      "console_enabled": false,
      "console_interface": "no-console",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "deploy_interface": "direct",
      "deploy_step": {},
      "driver": "ipmi",
      "driver_info": {
        "ipmi_password": "******",
        "ipmi_username": "ADMIN"
      },
      "driver_internal_info": {},
      "extra": {},
      "inspect_interface": "no-inspect",
      "inspection_finished_at": null,
      "inspection_started_at": null,
      "instance_info": {},
      "instance_uuid": null,
      "instance_name": null,
      "last_error": null,
      "lessee": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "maintenance_reason": null,
      "management_interface": "ipmitool",
      "name": "test_node_dynamic",
      "network_data": {},
      "network_interface": "flat",
      "owner": "43e61ec9-8e42-4dcb-bc45-30d66aa93e5b",
      "portgroups": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/portgroups",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/portgroups",
          "rel": "bookmark"
        }
      ],
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/ports",
          "rel": "bookmark"
        }
      ],
      "power_interface": "ipmitool",
      "power_state": null,
      "properties": {},
      "protected": false,
      "protected_reason": null,
      "provision_state": "enroll",
      "provision_updated_at": null,
      "raid_config": {},
      "raid_interface": "no-raid",
      "rescue_interface": "no-rescue",
      "reservation": null,
      "resource_class": null,
      "retired": false,
      "retired_reason": null,
      "states": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/states",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/states",
          "rel": "bookmark"
        }
      ],
      "storage_interface": "noop",
      "target_power_state": null,
      "target_provision_state": null,
      "target_raid_config": {},
      "traits": [],
      "updated_at": null,
      "uuid": "2b045129-a906-46af-bc1a-092b294b3428",
      "vendor_interface": "no-vendor",
      "volume": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/volume",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/volume",
          "rel": "bookmark"
        }
      ]
    }
  ]
}

GET

/v1/nodes/{node_ident}

显示节点详细信息

显示节点的详细信息。默认情况下，这将返回资源的完整表示形式；可以提供可选的 fields 参数以仅返回指定的集合。

版本 1.37 中添加：引入了 traits 字段。

版本 1.38 中添加：引入了 rescue_interface 字段。

版本 1.42 中添加：引入了 fault 字段。

版本 1.46 中添加：引入了 conductor_group 字段。

版本 1.48 中添加：引入了 protected 和 protected_reason 字段。

版本 1.49 中添加：引入了 conductor 字段

版本 1.50 中添加：引入了 owner 字段。

版本 1.51 中添加：引入了 description 字段。

版本 1.52 中添加：引入了 allocation_uuid 字段。

版本 1.61 中添加：引入了 retired 和 retired_reason 字段。

版本 1.65 中添加：引入了 lessee 字段。

1.66 版本中添加：引入了 network_data 字段。

版本 1.82 中添加：引入了 shard 字段。

版本 1.83 中添加：引入了 parent_node 字段。

版本 1.95 中添加：引入了 disable_power_off 字段。

版本 1.104 中添加：引入了 instance_name 字段。

正常响应代码：200

错误代码：400,403,404,406

请求¶

名称

入参

类型

描述

node_ident

路径

字符串

节点的 UUID 或名称。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

Response¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name (可选)	body	字符串	节点的资源的易于理解的标识符。可以是未定义的。某些单词是保留的。
power_state	body	字符串	此节点的当前电源状态。通常为“power on”（开机）或“power off”（关机），但如果 Ironic 无法确定电源状态（例如，由于硬件故障），则可能是“None”。
target_power_state	body	字符串	如果已请求电源状态转换，则此字段表示请求的（即“目标”）状态，可以是“power on”（开机）或“power off”（关机）。
provision_state	body	字符串	此节点的当前配置状态。
target_provision_state	body	字符串	如果已请求配置操作，则此字段表示请求的（即“目标”）状态。请注意，节点在过渡到此目标状态时可能会经历几个状态。例如，当请求将实例部署到 AVAILABLE 节点时，节点可能会经历以下状态更改过程：AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
maintenance	body	布尔值	指示此节点是否当前处于“维护模式”。将节点置于维护模式会将其从可用资源池中删除并停止某些内部自动化。这可以手动完成（例如，通过 API 请求），也可以在 Ironic 检测到阻止与机器通信的硬件故障时自动完成。
maintenance_reason (可选)	body	字符串	用户可设置的描述，说明为什么将此节点置于维护模式
fault (可选)	body	字符串	故障指示 ironic 检测到的活动故障，通常节点处于“维护模式”。None 表示 ironic 未检测到任何故障。“power failure”（电源故障）表示 ironic 无法从此节点检索电源状态。还有其他可能的类型，例如“clean failure”（清理失败）和“rescue abort failure”（救援中止失败）。
last_error	body	字符串	最近一次启动但未能完成的事务中的任何错误。
reservation	body	字符串	如果持有锁，则为持有此节点锁的 Ironic Conductor 主机的 `name`。通常为“null”，但此字段对于调试很有用。
driver	body	字符串	驱动程序的名称。
driver_info	body	JSON	驱动程序管理此节点所需的所有元数据。字段列表因驱动程序而异，可以从 `/v1/drivers/<DRIVER_NAME>/properties` 资源中检索。
driver_internal_info (可选)	body	JSON	由节点的驱动程序设置和存储的内部元数据。此字段为只读。
properties	body	JSON	此节点的物理特性。在检查期间填充。可以随时通过 REST API 进行编辑。
instance_info	body	JSON	用于自定义已部署镜像的信息。可能包括根分区大小、base64 编码的 config drive 和其他元数据。请注意，此字段在删除实例时会自动擦除（这是通过请求将节点置备状态更改为 DELETED 来完成的）。
instance_uuid	body	字符串	与此节点关联的 Nova 实例的 UUID。注意此字段不遵循标准的 JSON PATCH RFC 6902 行为。 “add” 操作符无法替换现有的 instance_uuid 值。尝试这样做将导致 409 Conflict 错误（NodeAssociated 异常）。此保护可防止多个 Nova 计算代理尝试关联相同的节点时发生竞争条件。
instance_name (可选)	body	字符串	部署在此节点上的实例的人类可读名称。为了与节点的 `instance_info` 中的 `display_name` 同步，以便与 Nova 保持向后兼容。
chassis_uuid	body	字符串	与此节点关联的机箱的 UUID。可以为空或 None。
extra	body	对象	一组或多组任意元数据键值对。
console_enabled	body	布尔值	指示在此节点上是否启用或禁用控制台访问。
raid_config (可选)	body	JSON	表示节点的当前 RAID 配置。随清理功能引入。
target_raid_config	body	JSON	表示节点的请求的 RAID 配置，将在节点下次通过 CLEANING 状态转换时应用。随清理功能引入。
clean_step (可选)	body	字符串	当前的清理步骤。随清理功能引入。
deploy_step (可选)	body	字符串	当前的部署步骤。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	指向此节点上端口集合的链接
portgroups	body	数组	指向此节点上端口组集合的链接。
states	body	数组	指向状态集合的链接。请注意，此资源也用于请求状态转换。
resource_class	body	字符串	可由外部调度程序用作特定类型资源单元的此节点的标识符的字符串。有关更多详细信息，请参阅：https://docs.openstack.org/ironic/2025.2/install/configure-nova-flavors.html
bios_interface	body	字符串	要用于此节点的 BIOS 接口。
boot_interface	body	字符串	节点的启动接口，例如“pxe”。
console_interface	body	字符串	节点的控制台接口，例如“no-console”。
deploy_interface	body	字符串	节点的部署接口，例如“iscsi”。
inspect_interface	body	字符串	用于节点检查的接口，例如“no-inspect”。
management_interface	body	字符串	用于节点带外管理的接口，例如“ipmitool”。
network_interface	body	字符串	在部署和清理期间用于此节点的网络接口提供程序。
power_interface	body	字符串	用于对节点执行电源操作的接口，例如“ipmitool”。
raid_interface	body	字符串	用于在此节点上配置 RAID 的接口，例如“no-raid”。
rescue_interface	body	字符串	用于节点救援的接口，例如“no-rescue”。
storage_interface	body	字符串	用于在此节点上附加和分离卷的接口，例如“cinder”。
traits	body	数组	此节点的特征列表。
vendor_interface	body	字符串	用于此节点上特定于供应商的功能的接口，例如“no-vendor”。
volume	body	数组	指向卷资源的链接。
conductor_group	body	字符串	节点的 conductor 组。最多 255 个字符的区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
protected (可选)	body	布尔值	是否保护节点免于取消配置、重建和删除。
protected_reason (可选)	body	字符串	节点被标记为受保护的原因。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
lessee (可选)	body	字符串	租赁该对象的租户的字符串或 UUID。
shard (可选)	body	字符串	一个字符串，指示此节点所属的分片。
description	body	字符串	关于此节点的说明性文本。
conductor (可选)	body	字符串	当前服务于节点的 Conductor。此字段为只读。
allocation_uuid	body	字符串	与节点关联的分配的 UUID。如果不是 `null`，将与 `instance_uuid` 相同（反之不一定成立）。与 `instance_uuid` 不同，此字段为只读。请使用 Allocation API 删除分配。
network_data (可选)	body	JSON	在部署和清理期间使用的 OpenStack 网络数据格式的静态网络配置。需要专门构建的 ramdisk，请参阅 DHCP-less 文档。
disable_power_off (可选)	body	布尔值	如果设置为 true，则明确禁用节点的关机，而是使用重启代替开机/关机。此外，如果可能，节点将被禁用（即，其 API 代理将变得不可用，并且将删除网络配置），而不是被关机。

Node 的示例 JSON 表示形式

{
  "allocation_uuid": null,
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "conductor": "compute1.localdomain",
  "conductor_group": "group-1",
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": null,
  "deploy_step": {},
  "description": null,
  "driver": "fake",
  "driver_info": {
    "ipmi_password": "******",
    "ipmi_username": "ADMIN"
  },
  "driver_internal_info": {
    "clean_steps": null
  },
  "extra": {},
  "inspect_interface": null,
  "inspection_finished_at": null,
  "inspection_started_at": null,
  "instance_info": {},
  "instance_uuid": null,
  "instance_name": null,
  "last_error": null,
  "lessee": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "bookmark"
    }
  ],
  "maintenance": false,
  "maintenance_reason": null,
  "management_interface": null,
  "name": "test_node_classic",
  "network_data": {},
  "network_interface": "flat",
  "owner": null,
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "bookmark"
    }
  ],
  "power_interface": null,
  "power_state": "power off",
  "properties": {},
  "protected": false,
  "protected_reason": null,
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "raid_interface": null,
  "rescue_interface": null,
  "reservation": null,
  "resource_class": "bm-large",
  "retired": false,
  "retired_reason": null,
  "states": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "bookmark"
    }
  ],
  "storage_interface": "noop",
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "traits": [],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null,
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "bookmark"
    }
  ]
}

PATCH

/v1/nodes/{node_ident}

更新节点

更新有关节点的存储信息。

请注意，此端点不能用于请求状态更改，这些更改通过子资源进行管理。

1.25 版本中添加：引入了取消设置节点机箱 UUID 的功能。

1.51 版本中添加：引入了设置/取消设置节点描述的功能。

1.82 版本中添加：引入了设置/取消设置节点分片的功能。

1.104 版本中添加：引入了设置/取消设置节点实例名称的功能。

正常响应代码：200

错误代码：400,403,404,406,409

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

注意

instance_uuid 字段是 RFC 6902 行为的一个例外。 “add” 操作符不能替换现有的 instance_uuid 值。尝试这样做将导致 409 冲突错误（NodeAssociated 异常）。这种保护措施可以防止多个 Nova 计算代理尝试关联相同的节点时发生竞争条件。

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

示例 PATCH 文档更新 Node driver_info

[
   {
      "op": "replace",
      "path": "/driver_info/ipmi_username",
      "value": "OPERATOR"
   },
   {
      "op": "add",
      "path": "/driver_info/deploy_kernel",
      "value": "http://127.0.0.1/images/kernel"
   },
   {
       "op": "add",
       "path": "/driver_info/deploy_ramdisk",
       "value": "http://127.0.0.1/images/ramdisk"
   }
]

Response¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name (可选)	body	字符串	节点的资源的易于理解的标识符。可以是未定义的。某些单词是保留的。
power_state	body	字符串	此节点的当前电源状态。通常为“power on”（开机）或“power off”（关机），但如果 Ironic 无法确定电源状态（例如，由于硬件故障），则可能是“None”。
target_power_state	body	字符串	如果已请求电源状态转换，则此字段表示请求的（即“目标”）状态，可以是“power on”（开机）或“power off”（关机）。
provision_state	body	字符串	此节点的当前配置状态。
target_provision_state	body	字符串	如果已请求配置操作，则此字段表示请求的（即“目标”）状态。请注意，节点在过渡到此目标状态时可能会经历几个状态。例如，当请求将实例部署到 AVAILABLE 节点时，节点可能会经历以下状态更改过程：AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
maintenance	body	布尔值	指示此节点是否当前处于“维护模式”。将节点置于维护模式会将其从可用资源池中删除并停止某些内部自动化。这可以手动完成（例如，通过 API 请求），也可以在 Ironic 检测到阻止与机器通信的硬件故障时自动完成。
maintenance_reason (可选)	body	字符串	用户可设置的描述，说明为什么将此节点置于维护模式
fault (可选)	body	字符串	故障指示 ironic 检测到的活动故障，通常节点处于“维护模式”。None 表示 ironic 未检测到任何故障。“power failure”（电源故障）表示 ironic 无法从此节点检索电源状态。还有其他可能的类型，例如“clean failure”（清理失败）和“rescue abort failure”（救援中止失败）。
last_error	body	字符串	最近一次启动但未能完成的事务中的任何错误。
reservation	body	字符串	如果持有锁，则为持有此节点锁的 Ironic Conductor 主机的 `name`。通常为“null”，但此字段对于调试很有用。
driver	body	字符串	驱动程序的名称。
driver_info	body	JSON	驱动程序管理此节点所需的所有元数据。字段列表因驱动程序而异，可以从 `/v1/drivers/<DRIVER_NAME>/properties` 资源中检索。
driver_internal_info (可选)	body	JSON	由节点的驱动程序设置和存储的内部元数据。此字段为只读。
properties	body	JSON	此节点的物理特性。在检查期间填充。可以随时通过 REST API 进行编辑。
instance_info	body	JSON	用于自定义已部署镜像的信息。可能包括根分区大小、base64 编码的 config drive 和其他元数据。请注意，此字段在删除实例时会自动擦除（这是通过请求将节点置备状态更改为 DELETED 来完成的）。
instance_uuid	body	字符串	与此节点关联的 Nova 实例的 UUID。注意此字段不遵循标准的 JSON PATCH RFC 6902 行为。 “add” 操作符无法替换现有的 instance_uuid 值。尝试这样做将导致 409 Conflict 错误（NodeAssociated 异常）。此保护可防止多个 Nova 计算代理尝试关联相同的节点时发生竞争条件。
instance_name (可选)	body	字符串	部署在此节点上的实例的人类可读名称。为了与节点的 `instance_info` 中的 `display_name` 同步，以便与 Nova 保持向后兼容。
chassis_uuid	body	字符串	与此节点关联的机箱的 UUID。可以为空或 None。
extra	body	对象	一组或多组任意元数据键值对。
console_enabled	body	布尔值	指示在此节点上是否启用或禁用控制台访问。
raid_config (可选)	body	JSON	表示节点的当前 RAID 配置。随清理功能引入。
target_raid_config	body	JSON	表示节点的请求的 RAID 配置，将在节点下次通过 CLEANING 状态转换时应用。随清理功能引入。
clean_step (可选)	body	字符串	当前的清理步骤。随清理功能引入。
deploy_step (可选)	body	字符串	当前的部署步骤。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	指向此节点上端口集合的链接
portgroups	body	数组	指向此节点上端口组集合的链接。
states	body	数组	指向状态集合的链接。请注意，此资源也用于请求状态转换。
resource_class	body	字符串	可由外部调度程序用作特定类型资源单元的此节点的标识符的字符串。有关更多详细信息，请参阅：https://docs.openstack.org/ironic/2025.2/install/configure-nova-flavors.html
boot_interface	body	字符串	节点的启动接口，例如“pxe”。
console_interface	body	字符串	节点的控制台接口，例如“no-console”。
deploy_interface	body	字符串	节点的部署接口，例如“iscsi”。
inspect_interface	body	字符串	用于节点检查的接口，例如“no-inspect”。
management_interface	body	字符串	用于节点带外管理的接口，例如“ipmitool”。
network_interface	body	字符串	在部署和清理期间用于此节点的网络接口提供程序。
power_interface	body	字符串	用于对节点执行电源操作的接口，例如“ipmitool”。
raid_interface	body	字符串	用于在此节点上配置 RAID 的接口，例如“no-raid”。
rescue_interface	body	字符串	用于节点救援的接口，例如“no-rescue”。
storage_interface	body	字符串	用于在此节点上附加和分离卷的接口，例如“cinder”。
traits	body	数组	此节点的特征列表。
vendor_interface	body	字符串	用于此节点上特定于供应商的功能的接口，例如“no-vendor”。
volume	body	数组	指向卷资源的链接。
conductor_group	body	字符串	节点的 conductor 组。最多 255 个字符的区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
protected (可选)	body	布尔值	是否保护节点免于取消配置、重建和删除。
protected_reason (可选)	body	字符串	节点被标记为受保护的原因。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
lessee (可选)	body	字符串	租赁该对象的租户的字符串或 UUID。
shard (可选)	body	字符串	一个字符串，指示此节点所属的分片。
description	body	字符串	关于此节点的说明性文本。
conductor (可选)	body	字符串	当前服务于节点的 Conductor。此字段为只读。
allocation_uuid	body	字符串	与节点关联的分配的 UUID。如果不是 `null`，将与 `instance_uuid` 相同（反之不一定成立）。与 `instance_uuid` 不同，此字段为只读。请使用 Allocation API 删除分配。
network_data (可选)	body	JSON	在部署和清理期间使用的 OpenStack 网络数据格式的静态网络配置。需要专门构建的 ramdisk，请参阅 DHCP-less 文档。
disable_power_off (可选)	body	布尔值	如果设置为 true，则明确禁用节点的关机，而是使用重启代替开机/关机。此外，如果可能，节点将被禁用（即，其 API 代理将变得不可用，并且将删除网络配置），而不是被关机。

Node 的示例 JSON 表示形式

{
  "allocation_uuid": null,
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "conductor": "compute1.localdomain",
  "conductor_group": "group-1",
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": null,
  "deploy_step": {},
  "driver": "fake",
  "driver_info": {
    "deploy_kernel": "http://127.0.0.1/images/kernel",
    "deploy_ramdisk": "http://127.0.0.1/images/ramdisk",
    "ipmi_password": "******",
    "ipmi_username": "OPERATOR"
  },
  "driver_internal_info": {
    "clean_steps": null
  },
  "extra": {},
  "inspect_interface": null,
  "inspection_finished_at": null,
  "inspection_started_at": null,
  "instance_info": {},
  "instance_uuid": null,
  "instance_name": null,
  "last_error": null,
  "lessee": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "bookmark"
    }
  ],
  "maintenance": true,
  "maintenance_reason": "Replacing the hard drive",
  "management_interface": null,
  "name": "test_node_classic",
  "network_data": {},
  "network_interface": "flat",
  "owner": null,
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "bookmark"
    }
  ],
  "power_interface": null,
  "power_state": "power off",
  "properties": {},
  "protected": false,
  "protected_reason": null,
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "raid_interface": null,
  "rescue_interface": null,
  "reservation": null,
  "resource_class": null,
  "retired": false,
  "retired_reason": null,
  "states": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "bookmark"
    }
  ],
  "storage_interface": "noop",
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "traits": [
    "CUSTOM_TRAIT1",
    "HW_CPU_X86_VMX"
  ],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null,
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "bookmark"
    }
  ]
}

DELETE

/v1/nodes/{node_ident}

删除节点

删除一个节点。

正常响应代码：204

错误代码：400,403,404,409

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

节点管理 (nodes)¶

可以通过几个子资源管理节点。

操作员可以设置维护模式，Ironic 会存储可选的“reason”（原因）。

提供的 driver_info 可以进行验证，以确保所选 driver 具有管理节点所需的所有信息。

可以通过请求更改其电源状态来重新启动、打开或关闭节点。这以异步方式处理，并在收到请求后在 target_power_state 字段中跟踪。

可以更改节点的启动设备，并可以查询支持的启动设备集。

更改节点配置状态的请求也会异步跟踪； target_provision_state 表示请求的状态。节点在到达请求的状态之前，可能会经历几个离散的 provision_state 步骤。这可能因驱动程序和配置而异。

例如，处于 available 状态的节点可以通过请求配置状态为 active 来部署实例。在此转换期间，节点的 provision_state 将暂时设置为 deploying，并且根据驱动程序，它也可能是 wait call-back。当转换完成时， target_provision_state 将设置为 None，并且 provision_state 将设置为 active。要销毁实例，请请求配置状态为 delete。在此转换期间，节点可能或可能不会经历 cleaning 状态，具体取决于服务配置。

GET

/v1/nodes/{node_ident}/validate

验证节点

请求 Ironic 验证节点的 driver 是否具有足够的信息来管理节点。这将轮询驱动程序上的每个 interface，并在响应中将该 interface 的状态作为元素返回。请注意，每个 driver 可能需要提供不同的信息，并且并非所有驱动程序都支持所有接口。

正常响应代码：200

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

响应中的每个元素将包含一个“result”（结果）变量，其值为“true”或“false”，指示接口是否具有足够的功能信息。值为 null 表示节点的驱动程序不支持该接口。

名称	入参	类型	描述
bios	body	对象	“bios”接口的状态
boot	body	对象	“boot”接口的状态
console	body	对象	“console”接口的状态
deploy	body	对象	“deploy”接口的状态
inspect	body	对象	“inspect”接口的状态
management	body	对象	“management”接口的状态
network	body	对象	“network”接口的状态
power	body	对象	“power”接口的状态
raid	body	对象	“raid”接口的状态
rescue	body	对象	“rescue”接口的状态
storage	body	对象	“storage”接口的状态

示例节点验证响应

{
  "boot": {
    "result": true
  },
  "console": {
    "result": true
  },
  "deploy": {
    "result": true
  },
  "inspect": {
    "result": true
  },
  "management": {
    "result": true
  },
  "network": {
    "result": true
  },
  "power": {
    "result": true
  },
  "raid": {
    "result": true
  },
  "rescue": {
    "reason": "not supported",
    "result": null
  },
  "storage": {
    "result": true
  }
}

PUT

/v1/nodes/{node_ident}/maintenance

设置维护标志

请求 Ironic 在节点上设置维护标志。这将禁用节点驱动程序可能采取的某些自动操作，并将其从 Nova 的可用资源池中删除。

正常响应代码：202

Request¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
reason（可选）	body	字符串	指定将节点置于维护模式的原因。

示例请求：将节点标记为维护

{
    "reason": "Replacing the hard drive"
}

DELETE

/v1/nodes/{node_ident}/maintenance

清除维护标志

通过向此端点发送 DELETE 请求来取消设置维护标志。如果接受请求，Ironic 还会清除 maintenance_reason 字段。

正常响应代码：202

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

PUT

/v1/nodes/{node_ident}/management/boot_device

设置启动设备

设置给定节点的启动设备，并持久地设置或设置为一次性启动。确切行为取决于硬件驱动程序。

注意

在某些驱动程序中，例如 *_ipmitool 系列，此方法会启动到硬件管理设备（BMC）的同步调用。谨慎使用！这是一个已知错误。

注意

一些驱动程序不支持一次性启动，并且始终持久地设置启动设备。

正常响应代码：204

Request¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
boot_device	body	字符串	节点的启动设备，例如“pxe”或“disk”。
persistent（可选）	body	布尔值	是否应仅为下一次重新启动设置启动设备，或者持久设置。

示例 JSON 请求正文以设置启动设备

{
    "boot_device": "pxe",
    "persistent": false
}

GET

/v1/nodes/{node_ident}/management/boot_device

获取启动设备

获取给定节点的当前启动设备。

注意

在某些驱动程序中，例如 *_ipmitool 系列，此方法会启动到硬件管理设备（BMC）的同步调用。谨慎使用！这是一个已知错误。

正常响应代码：200

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
boot_device	body	字符串	节点的启动设备，例如“pxe”或“disk”。
persistent	body	布尔值	是否应仅为下一次重新启动设置启动设备，或者持久设置。

示例 JSON 响应以获取启动设备

{
  "boot_device": "pxe",
  "persistent": false
}

GET

/v1/nodes/{node_ident}/management/boot_device/supported

获取支持的启动设备

检索特定节点支持的接受的启动设备集。

正常响应代码：200

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

Response¶

名称	入参	类型	描述
supported_boot_devices	body	数组	此节点驱动程序支持的启动设备列表。

示例响应列出支持的启动设备

{
  "supported_boot_devices": [
    "pxe"
  ]
}

PUT

/v1/nodes/{node_ident}/management/inject_nmi

注入 NMI（非屏蔽中断）

1.29 版本中添加。

为给定的节点注入 NMI（非屏蔽中断）。此功能可用于硬件诊断，实际支持取决于驱动程序。

正常响应代码：204（无内容）

错误代码

400（无效）
403（禁止）
404（未找到）
406（不可接受）
409（节点锁定、客户端错误）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

向节点注入 NMI 的请求必须是空字典

{}

GET

/v1/nodes/{node_ident}/states

节点状态摘要

获取节点当前电源、配置、启动模式、RAID 和控制台状态的摘要。

1.75 版本中添加：引入 boot_mode 和 secure_boot 字段。

正常响应代码：200

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
power_state	body	字符串	此节点的当前电源状态。通常为“power on”（开机）或“power off”（关机），但如果 Ironic 无法确定电源状态（例如，由于硬件故障），则可能是“None”。
target_power_state	body	字符串	如果已请求电源状态转换，则此字段表示请求的（即“目标”）状态，可以是“power on”（开机）或“power off”（关机）。
provision_state	body	字符串	此节点的当前配置状态。
target_provision_state	body	字符串	如果已请求配置操作，则此字段表示请求的（即“目标”）状态。请注意，节点在过渡到此目标状态时可能会经历几个状态。例如，当请求将实例部署到 AVAILABLE 节点时，节点可能会经历以下状态更改过程：AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
provision_updated_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。如果节点未被配置，则为“null”。
last_error	body	字符串	最近一次启动但未能完成的事务中的任何错误。
console_enabled	body	布尔值	指示在此节点上是否启用或禁用控制台访问。
raid_config (可选)	body	JSON	表示节点的当前 RAID 配置。随清理功能引入。
target_raid_config	body	JSON	表示节点的请求的 RAID 配置，将在节点下次通过 CLEANING 状态转换时应用。随清理功能引入。
boot_mode（可选）	body	字符串	当前的启动模式状态（uefi/bios）
secure_boot（可选）	body	布尔值	指示节点当前是否以启用 secure_boot 启动。

示例节点状态

{
  "boot_mode": "uefi",
  "console_enabled": false,
  "last_error": null,
  "power_state": "power off",
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "secure_boot": true,
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {}
}

PUT

/v1/nodes/{node_ident}/states/boot_mode

更改节点启动模式

请求更改节点的启动模式。

注意

根据驱动程序和底层硬件，更改启动模式可能会导致自动重新启动。

1.76 版本中添加：可以请求更改节点的启动模式。

正常响应代码：202（已接受）

错误代码

400（无效、InvalidStateRequested、InvalidParameterValue）
404（未找到）
409（冲突、节点锁定、客户端错误）
503（没有空闲 Conductor Workers）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
target	body	字符串	如果已请求启动模式更改，则此字段表示请求的（即“目标”）状态，为“uefi”或“bios”。

示例请求 UEFI 启动

{
    "target": "uefi"
}

示例请求 Legacy BIOS 启动

{
    "target": "bios"
}

PUT

/v1/nodes/{node_ident}/states/secure_boot

更改节点安全启动

请求更改节点的安全启动状态。

注意

根据驱动程序和底层硬件，更改安全启动状态可能会导致自动重新启动。

1.76 版本中添加：可以请求更改节点的安全启动状态。

正常响应代码：202（已接受）

错误代码

400（无效、InvalidStateRequested、InvalidParameterValue）
404（未找到）
409（冲突、节点锁定、客户端错误）
503（没有空闲 Conductor Workers）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
target	body	布尔值	如果已请求安全启动更改，则此字段表示请求的（即“目标”）状态，为 `true` 或 `false`。

示例请求关闭安全启动

{
    "target": false
}

示例请求打开安全启动

{
    "target": true
}

PUT

/v1/nodes/{node_ident}/states/power

更改节点电源状态

请求更改节点的电源状态。

正常响应代码：202（已接受）

1.27 版本中添加：在请求中，target 值也可以是 soft power off 或 soft rebooting。

1.27 版本中添加：在请求中，可以指定 timeout。

错误代码

409（节点锁定、客户端错误）
400（无效、InvalidStateRequested、InvalidParameterValue）
406（不可接受）
503（没有空闲 Conductor Workers）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
target	body	字符串	如果已请求电源状态转换，则此字段表示请求的（即“目标”）状态，为“power on”（开机）、“power off”（关机）、“rebooting”（重新启动）、“soft power off”（软关机）或“soft rebooting”（软重新启动）。
timeout (可选)	body	整数	电源状态转换的超时时间（以秒为单位）。

示例请求关闭节点电源

{
    "target": "power off"
}

示例请求使用超时时间软关机节点

{
    "target": "soft power off",
    "timeout": 300
}

PUT

/v1/nodes/{node_ident}/states/provision

更改节点配置状态

请求更改节点的配置状态。

可接受的目标状态取决于节点的当前配置状态。 Ironic 状态机的更详细文档可在开发者文档中找到。

1.35 版本中添加：在将节点的配置目标状态设置为 rebuild 时，可以提供 configdrive。

1.38 版本中添加：可以通过将节点的配置目标状态设置为 rescue 或 unrescue 来救援或取消救援节点。

1.56 版本中添加：一个 configdrive 可以是一个 JSON 对象，包含 meta_data、network_data 和 user_data。

1.59 版本中添加：一个 configdrive 现在接受 vendor_data。

1.69 版本中添加： deploy_steps 可以在将节点的配置目标状态设置为 active 或 rebuild 时提供。

1.70 版本中添加： disable_ramdisk 可以提供，以避免在手动清理期间启动 ramdisk。

1.87 版本中添加：可以通过将配置目标状态设置为 service 以及一个 service_steps 列表来服务节点。

1.92 版本中添加：添加了允许在配置期间执行预定义的步骤集的能力，通过传递一个已经为给定节点批准的 runbook_ident，作为替代 clean_steps 或 service_steps 字典。

1.95 版本中添加：添加了设置/取消设置节点上 disable_power_off 的能力。

正常响应代码：202

错误代码

409（节点锁定、客户端错误）
400 (InvalidState, NodeInMaintenance)
406（不可接受）
503（没有空闲 Conductor Workers）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
target	body	字符串	此节点的请求配置状态。
configdrive (可选)	body	字符串或对象	要写入节点启动磁盘分区上的 configdrive。可以是完整的 gzip 压缩和 base-64 编码的镜像，也可以是包含键的 JSON 对象 `meta_data` (可选) - 包含标准元数据的 JSON 对象。Ironic 将为 `uuid` 和 `name` 字段提供默认值。 `network_data` (可选) - 包含网络配置的 JSON 对象。 `user_data` (可选) - 用户数据。可以是字符串（将以 UTF-8 编码）；JSON 对象；或 JSON 数组。 `vendor_data` (可选) - 包含额外供应商数据的 JSON 对象。仅当将状态设置为“active”或“rebuild”时才接受此参数。
clean_steps (可选)	body	数组	将在节点上执行的清理步骤的有序列表。清理步骤是一个字典，包含必需的键 ‘interface’ 和 ‘step’，以及可选的键 ‘args’。如果指定，则 ‘args’ 的值是一个关键字变量参数字典，该字典传递给清理步骤方法。
deploy_steps (可选)	body	数组	将在节点上执行的部署步骤的列表。部署步骤是一个字典，包含必需的键 ‘interface’、‘step’、‘priority’ 以及可选的键 ‘args’。如果指定，则 ‘args’ 的值是一个关键字变量参数字典，该字典传递给部署步骤方法。
service_steps (可选)	body	数组	将在节点上执行的服务步骤的有序列表。清理步骤是一个字典，包含必需的键 ‘interface’ 和 ‘step’，以及可选的键 ‘args’。如果指定，则 ‘args’ 的值是一个关键字变量参数字典，该字典传递给清理步骤方法。
rescue_password (可选)	body	字符串	用于在节点救援操作期间配置救援 ramdisk 的非空密码。
disable_ramdisk (可选)	body	布尔值	如果设置为 `true`，ironic-python-agent ramdisk 将不会在清理期间启动。只有明确标记为不需要 ramdisk 的清理步骤才能在此模式下执行。仅允许进行手动清理。
runbook	路径	字符串	runbook 的 UUID 或名称。

使用通过本地 Web 服务器提供的 configdrive 部署节点的示例请求

{
    "target": "active",
    "configdrive": "http://127.0.0.1/images/test-node-config-drive.iso.gz"
}

使用自定义部署步骤部署节点的示例请求

{
    "target": "active",
    "deploy_steps": [
        {
            "interface": "deploy",
            "step": "upgrade_firmware",
            "args": {
                "force": "True"
            },
            "priority": 95
        }
    ]
}

使用自定义清理步骤清理节点的示例请求

{
    "target": "clean",
    "clean_steps": [
        {
            "interface": "deploy",
            "step": "upgrade_firmware",
            "args": {
                "force": "True"
            }
        }
    ]
}

使用自定义服务步骤服务节点的示例请求

{
    "target":"service",
    "sevice_steps": [
        {
            "interface": "raid",
            "step": "apply_configuration",
            "args": {
                "create_nonroot_volumes": "True"
            }
        }
    ]
}

使用 runbook 设置节点配置状态的示例请求

{
    "target": "clean",
    "runbook": "runbook_ident"
}

注意

使用 runbook 作为 clean_steps 或 service_steps 的替代方案。如果提供了 runbook，则请求中不得包含 clean_steps 或 service_steps。

PUT

/v1/nodes/{node_ident}/states/raid

设置 RAID 配置

1.12 版本中添加。

将提供的配置存储在节点的 target_raid_config 属性上。此属性必须是结构化的 JSON，并在收到时由驱动程序进行验证。请求模式定义在 RAID 功能文档中

注意

调用此 API 仅存储请求的配置；下次节点过渡到 cleaning 阶段时，它将被应用。

正常响应代码：204

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
target_raid_config	body	JSON	表示节点的请求的 RAID 配置，将在节点下次通过 CLEANING 状态转换时应用。随清理功能引入。

示例请求的 RAID 配置

{
   "logical_disks" : [
      {
         "size_gb" : 100,
         "is_root_volume" : true,
         "raid_level" : "1"
      }
   ]
}

GET

/v1/nodes/{node_ident}/states/console

获取控制台

获取有关控制台的连接信息。

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

PUT

/v1/nodes/{node_ident}/states/console

启动/停止控制台

启动或停止串行控制台。

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
enabled	body	布尔值	指示在此节点上是否启用或禁用控制台访问。

附加/分离虚拟媒体 (节点)¶

1.89 版本中添加。

使用 v1/nodes/{node_ident}/vmedia 端点将通用镜像作为虚拟媒体设备附加到节点，或将其从节点移除。

POST

/v1/nodes/{node_ident}/vmedia

将虚拟媒体附加到节点

将虚拟介质设备附加到节点。

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
device_type	body	字符串	使用的虚拟媒体设备的类型，例如 CDROM
image_url	body	字符串	要附加到虚拟媒体设备的镜像的 URL。
image_download_source (可选)	body	字符串	镜像提供给 BMC 的方式，“http” 表示远程位置，“local” 表示使用本地 Web 服务器。

将虚拟媒体附加到节点的示例请求

{
    "device_type": "CDROM",
    "image_url": "http://image"
}

DELETE

/v1/nodes/{node_ident}/vmedia

从节点分离虚拟媒体

从节点分离虚拟媒体设备。

正常响应代码：204

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

节点供应商直通 (节点)¶

每个驱动程序 MAY 支持供应商特定的扩展，称为“直通”方法。

在内部，Ironic 的驱动程序 API 支持通过通用的 HTTP 方法 GET、PUT、POST 和 DELETE 灵活地暴露函数。要调用直通方法，查询字符串必须包含方法名称，例如 /vendor_passthru?method=reset_bmc。HTTP 请求的内容将转发到节点的驱动程序并进行验证。

Ironic 的 REST API 提供了一种发现这些方法的方式，但不支持、测试或记录这些端点。Ironic 开发团队不保证这些方法在发布版本之间的任何兼容性，但我们鼓励驱动程序作者为这些方法提供文档和支持。

除了此处记录的端点之外，所有位于标题 vendor_passthru 下的资源和端点都应被视为不受支持的 API，并且可能由驱动程序作者在未发出警告的情况下更改。

GET

/v1/nodes/{node_ident}/vendor_passthru/methods

列出方法

检索给定节点可用的供应商直通方法的列表。响应将指示每个供应商直通方法允许哪些 HTTP 方法，方法调用是同步还是异步，以及响应是否包含任何附件。

正常响应代码：200

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

示例直通方法列表

{
  "bmc_reset": {
    "async": true,
    "attach": false,
    "description": "",
    "http_methods": [
      "POST"
    ],
    "require_exclusive_lock": true
  },
  "send_raw": {
    "async": true,
    "attach": false,
    "description": "",
    "http_methods": [
      "POST"
    ],
    "require_exclusive_lock": true
  }
}

METHOD

/v1/nodes/{node_ident}/vendor_passthru?method={method_name}

调用方法

HTTP METHOD 可能是 GET、POST、PUT、DELETE 中的一种，具体取决于驱动程序和方法。

此端点将请求直接传递给节点的硬件驱动程序。HTTP BODY 必须是可解析的 JSON，它将被转换为传递给该函数的参数。不可解析的 JSON、缺少参数或参数过多将导致请求被拒绝并返回 HTTP 400 错误。

正常响应代码：200 202

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
method_name	查询	字符串	驱动程序特定的方法名称。

所有其他参数应在 BODY 中传递。参数列表因 method_name 而异。

响应¶

不确定。

节点特性 (节点)¶

1.37 版本中添加。

节点特性用于 Compute 服务中的调度，使用定性属性来影响实例到裸机计算节点的放置。在 Bare Metal 服务中为节点指定的特性将在 Compute 服务的 placement API 中相应的资源提供程序上注册。

特性可以是标准特性或自定义特性。标准特性列在 os_traits 库中。自定义特性必须满足以下要求

并在其前加上 CUSTOM_
仅包含大写字母 A 到 Z、数字 0 到 9 或下划线
长度不超过 255 个字符

裸机节点最多可以有 50 个特性。

GET

/v1/nodes/{node_ident}/traits

列出节点的特性

返回节点的特性列表。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
traits	body	数组	此节点的特征列表。

节点特性的示例列表

{
  "traits": [
    "CUSTOM_TRAIT1",
    "HW_CPU_X86_VMX"
  ]
}

PUT

/v1/nodes/{node_ident}/traits

设置节点的全部特性

设置节点的全部特性，替换任何现有特性。

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
traits	body	数组	此节点的特征列表。

设置节点全部特性的示例请求

{
  "traits": [
    "CUSTOM_TRAIT1",
    "HW_CPU_X86_VMX"
  ]
}

PUT

/v1/nodes/{node_ident}/traits/{trait}

将特性添加到节点

将单个特性添加到节点。

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
trait	路径	字符串	此节点的单个特性。

DELETE

/v1/nodes/{node_ident}/traits

从节点移除所有特性

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

DELETE

/v1/nodes/{node_ident}/traits/{trait}

从节点移除特性

从节点移除单个特性。

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
trait	路径	字符串	此节点的单个特性。

VIF（虚拟接口）的节点¶

1.28 版本中添加。

通过 v1/nodes/{node_ident}/vifs 端点将 VIF（虚拟接口）附加到节点或从节点分离。将 VIF 附加到节点意味着 VIF 将映射到指定节点的空闲端口或端口组。

GET

/v1/nodes/{node_ident}/vifs

列出附加到节点的 VIF

返回附加到节点的 VIF 列表。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
vifs	body	数组	附加到此节点的 VIF。
id	body	字符串	VIF 的 UUID 或名称。

附加到节点的 VIF 列表示例

{
  "vifs": [
    {
      "id": "1974dcfa-836f-41b2-b541-686c100900e5"
    }
  ]
}

POST

/v1/nodes/{node_ident}/vifs

将 VIF 附加到节点

将 VIF 附加到节点。

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
id	body	字符串	VIF 的 UUID 或名称。
port_uuid (可选)	body	字符串	要附加 VIF 的端口的 UUID。不能与 `portgroup_uuid` 一起指定。
portgroup_uuid (可选)	body	字符串	要附加 VIF 的端口组的 UUID。不能与 `port_uuid` 一起指定。
node_ident	路径	字符串	节点的 UUID 或名称。

将 VIF 附加到节点的示例请求

{
    "id": "1974dcfa-836f-41b2-b541-686c100900e5"
}

DELETE

/v1/nodes/{node_ident}/vifs/{node_vif_ident}

从节点分离 VIF

从节点分离 VIF。

正常响应代码：204

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
node_vif_ident	body	字符串	VIF 的 UUID 或名称。

指标管理¶

指标管理是节点 ReST API 端点的扩展，允许读取和切换硬件单元上的指示器（例如 LED）。

GET

/v1/nodes/{node_ident}/management/indicators

列出指示器

在版本 1.63 中添加。

列出每个硬件组件可用的所有指示器名称。 redfish 驱动程序可能具有的组件包括：system、chassis 和 drive。实际列表取决于底层硬件的支持情况。

正常响应代码：200

错误响应代码：404（如果未找到节点）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应参数¶

名称	入参	类型	描述
组件	body	数组	列出此节点的每个硬件组件可用的所有指示器名称。
name	body	字符串	节点可用的组件名称。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

节点指示器的示例列表

{
    "components": [
        {
            "name": "system",
            "links": [
                {
                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/management/indicators/system",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:6385/nodes/Compute0/management/indicators/system",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "name": "chassis",
            "links": [
                {
                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/management/indicators/chassis",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:6385/nodes/Compute0/management/indicators/chassis",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}

GET

/v1/nodes/{node_ident}/management/indicators/{ind_ident}@{component}

获取指示器状态

在版本 1.63 中添加。

检索节点给定组件的选定指示器的状态。响应对象中字段的值代表其状态。这些值可以是 OFF、ON、BLINKING 或 UNKNOWN 中的一个。

正常响应代码：200

错误响应代码：404（如果未找到节点、组件或指示器）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
组件	路径	字符串	Bare Metal 节点组件。
ind_ident	路径	字符串	Bare Metal 组件的指示器。

响应参数¶

名称	入参	类型	描述
state	body	字符串	节点组件的指示器状态。可能的值包括：`OFF`、`ON`、`BLINKING` 或 `UNKNOWN`。

节点给定组件的指示器示例列表

{
  "state": "ON"
}

PUT

/v1/nodes/{node_ident}/management/indicators/{ind_ident}@{component}

设置指示器状态

在版本 1.63 中添加。

设置组件所需指示器的状态。

正常响应代码：204（无内容）

错误代码

400（如果状态不是可接受的值）
404（如果未找到节点、组件或指示器）

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
组件	路径	字符串	Bare Metal 节点组件。
ind_ident	路径	字符串	Bare Metal 组件的指示器。
state	body	字符串	节点组件的指示器状态。可能的值包括：`OFF`、`ON`、`BLINKING` 或 `UNKNOWN`。

设置指示器状态

{
  "state": "BLINKING"
}

端口组 (portgroups)¶

在版本 1.23 中添加。

端口可以组合成端口组，以支持静态链路聚合组 (LAG) 或多机箱链路聚合组 (MLAG) 配置。通过 v1/portgroups 资源完成 Bare Metal 端口组资源的列出、搜索、创建、更新和删除。

所有端口组在创建时都必须与节点关联。这种关联可以更改，但如果当前节点或目标节点处于过渡状态（例如，正在部署中），或者处于受此类更改影响的不确定状态（例如，节点上有活动的实例），则请求可能会被拒绝。

GET

/v1/portgroups

列出端口组

返回 Bare Metal 端口组列表。可以通过在请求中传递一些参数来进行一些过滤。

默认情况下，此查询将返回每个端口组的 UUID、名称和地址。

在版本 1.43 中添加：添加了 detail 布尔请求参数。如果指定 True，则响应将包含有关每个端口组的完整详细信息。

在版本 1.99 中添加：添加了根据节点关联的 conductor_group 过滤端口组的功能。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node (可选)	查询	字符串	过滤返回的端口组列表，仅返回与此特定节点（名称或 UUID）关联的端口组，如果未找到则返回空集。
address (可选)	查询	字符串	过滤返回的端口组列表，仅返回具有指定物理硬件地址（通常是 MAC）的端口组，如果未找到则返回空集。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。
conductor_group (可选)	查询	数组	过滤返回的端口或端口组列表，仅返回具有指定的 `conductor_group` 的端口或端口组，如果未找到则返回空集。包含最多 255 个字符的区分大小写的字符串列表，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。如果指定了 `node`、`node_uuid`、`portgroup` 或 `address`，则不能使用此选项。例如，以下请求仅返回节点在 bear 和 metal 导体组中的端口 GET /v1/ports?conductor_groups=bear,metal

响应¶

名称	入参	类型	描述
portgroups	body	数组	端口组资源集合。
uuid	body	字符串	资源的 UUID。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
name	body	字符串	端口组资源的易于理解的标识符。可能未定义。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

端口组列表响应示例

{
  "portgroups": [
    {
      "address": "11:11:11:11:11:11",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "name": "test_portgroup",
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}

POST

/v1/portgroups

创建端口组

创建一个新的端口组资源。

此方法需要节点 UUID 和端口组的物理硬件地址（在大多数情况下是 MAC 地址）。

在版本 1.102 中添加：添加了 physical_network 字段。

在版本 1.103 中添加：添加了 category 字段。

正常响应代码：201

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_uuid	body	字符串	此资源所属的节点的 UUID。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
name (可选)	body	字符串	端口组资源的易于理解的标识符。可能未定义。
mode (可选)	body	字符串	端口组模式。有关可能的值，请参阅 https://linuxkernel.org.cn/doc/Documentation/networking/bonding.txt。如果在创建端口组的请求中未指定，则将设置为 `[DEFAULT]default_portgroup_mode` 配置选项的值。设置后，无法从端口组中删除。
standalone_ports_supported (可选)	body	布尔值	指示作为此端口组成员的端口是否可以用作独立端口。
properties (可选)	body	JSON	与端口组配置相关的键/值属性。
extra (可选)	body	对象	一组或多组任意元数据键值对。
uuid (可选)	body	字符串	资源的 UUID。
physical_network (可选)	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
category (可选)	body	字符串	网络端口组的类别。帮助进一步区分端口组。

端口组创建请求示例

{
    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
    "address": "11:11:11:11:11:11",
    "name": "test_portgroup"
}

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	端口组资源的易于理解的标识符。可能未定义。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
standalone_ports_supported	body	布尔值	指示作为此端口组成员的端口是否可以用作独立端口。
internal_info	body	JSON	端口组设置和存储的内部元数据。此字段是只读的。
extra	body	对象	一组或多组任意元数据键值对。
mode	body	字符串	端口组模式。有关可能的值，请参阅 https://linuxkernel.org.cn/doc/Documentation/networking/bonding.txt。如果在创建端口组的请求中未指定，则将设置为 `[DEFAULT]default_portgroup_mode` 配置选项的值。设置后，无法从端口组中删除。
properties	body	JSON	与端口组配置相关的键/值属性。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	链接到属于此端口组的端口集合。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
category (可选)	body	字符串	网络端口组的类别。帮助进一步区分端口组。

端口组创建响应示例

{
  "address": "11:11:11:11:11:11",
  "category": "hypernet",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "bookmark"
    }
  ],
  "mode": "active-backup",
  "name": "test_portgroup",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "bookmark"
    }
  ],
  "physical_network": "physnet1",
  "properties": {},
  "standalone_ports_supported": true,
  "updated_at": null,
  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}

GET

/v1/portgroups/detail

列出详细的端口组

返回 Bare Metal 端口组列表，包含详细信息。

在版本 1.102 中添加：添加了 physical_network 字段。

在版本 1.103 中添加：添加了 category 字段。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node (可选)	查询	字符串	过滤返回的端口组列表，仅返回与此特定节点（名称或 UUID）关联的端口组，如果未找到则返回空集。
address (可选)	查询	字符串	过滤返回的端口组列表，仅返回具有指定物理硬件地址（通常是 MAC）的端口组，如果未找到则返回空集。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
portgroups	body	数组	端口组资源集合。
name	body	字符串	端口组资源的易于理解的标识符。可能未定义。
uuid	body	字符串	资源的 UUID。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
standalone_ports_supported	body	布尔值	指示作为此端口组成员的端口是否可以用作独立端口。
internal_info	body	JSON	端口组设置和存储的内部元数据。此字段是只读的。
extra	body	对象	一组或多组任意元数据键值对。
mode	body	字符串	端口组模式。有关可能的值，请参阅 https://linuxkernel.org.cn/doc/Documentation/networking/bonding.txt。如果在创建端口组的请求中未指定，则将设置为 `[DEFAULT]default_portgroup_mode` 配置选项的值。设置后，无法从端口组中删除。
properties	body	JSON	与端口组配置相关的键/值属性。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	链接到属于此端口组的端口集合。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
category (可选)	body	字符串	网络端口组的类别。帮助进一步区分端口组。

详细的端口组列表响应示例

{
  "portgroups": [
    {
      "address": "11:11:11:11:11:11",
      "category": "hypernet",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "mode": "active-backup",
      "name": "test_portgroup",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "bookmark"
        }
      ],
      "physical_network": "physnet1",
      "properties": {},
      "standalone_ports_supported": true,
      "updated_at": null,
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}

GET

/v1/portgroups/{portgroup_ident}

显示端口组详细信息

显示给定端口组的详细信息。

在版本 1.102 中添加：添加了 physical_network 字段。

在版本 1.103 中添加：添加了 category 字段。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称

入参

类型

描述

portgroup_ident

路径

字符串

端口组的 UUID 或名称。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	端口组资源的易于理解的标识符。可能未定义。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
standalone_ports_supported	body	布尔值	指示作为此端口组成员的端口是否可以用作独立端口。
internal_info	body	JSON	端口组设置和存储的内部元数据。此字段是只读的。
extra	body	对象	一组或多组任意元数据键值对。
mode	body	字符串	端口组模式。有关可能的值，请参阅 https://linuxkernel.org.cn/doc/Documentation/networking/bonding.txt。如果在创建端口组的请求中未指定，则将设置为 `[DEFAULT]default_portgroup_mode` 配置选项的值。设置后，无法从端口组中删除。
properties	body	JSON	与端口组配置相关的键/值属性。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	链接到属于此端口组的端口集合。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
category (可选)	body	字符串	网络端口组的类别。帮助进一步区分端口组。

端口组详细信息示例

{
  "address": "11:11:11:11:11:11",
  "category": "hypernet",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "bookmark"
    }
  ],
  "mode": "active-backup",
  "name": "test_portgroup",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "bookmark"
    }
  ],
  "physical_network": "physnet1",
  "properties": {},
  "standalone_ports_supported": true,
  "updated_at": null,
  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}

PATCH

/v1/portgroups/{portgroup_ident}

更新端口组

更新端口组。

在版本 1.102 中添加：添加了 physical_network 字段。

在版本 1.103 中添加：添加了 category 字段。

正常响应代码：200

错误代码：400,401,403,404

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

名称	入参	类型	描述
portgroup_ident	路径	字符串	端口组的 UUID 或名称。

端口组更新请求示例

[
   {
      "path" : "/address",
      "value" : "22:22:22:22:22:22",
      "op" : "replace"
   }
]

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	端口组资源的易于理解的标识符。可能未定义。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
standalone_ports_supported	body	布尔值	指示作为此端口组成员的端口是否可以用作独立端口。
internal_info	body	JSON	端口组设置和存储的内部元数据。此字段是只读的。
extra	body	对象	一组或多组任意元数据键值对。
mode	body	字符串	端口组模式。有关可能的值，请参阅 https://linuxkernel.org.cn/doc/Documentation/networking/bonding.txt。如果在创建端口组的请求中未指定，则将设置为 `[DEFAULT]default_portgroup_mode` 配置选项的值。设置后，无法从端口组中删除。
properties	body	JSON	与端口组配置相关的键/值属性。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
ports	body	数组	链接到属于此端口组的端口集合。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
category (可选)	body	字符串	网络端口组的类别。帮助进一步区分端口组。

端口组更新响应示例

{
  "address": "22:22:22:22:22:22",
  "category": "hypernet",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "bookmark"
    }
  ],
  "mode": "active-backup",
  "name": "test_portgroup",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "bookmark"
    }
  ],
  "physical_network": "physnet1",
  "properties": {},
  "standalone_ports_supported": true,
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}

DELETE

/v1/portgroups/{portgroup_ident}

删除端口组

删除端口组。

正常响应代码：204

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
portgroup_ident	路径	字符串	端口组的 UUID 或名称。

按节点列出端口组 (nodes, portgroups)¶

在版本 1.24 中添加。

给定节点标识符（uuid 或 name），API 暴露与该节点关联的所有端口组的列表和详细信息。

这些端点不允许修改端口组；应该通过访问 /v1/portgroups 端点下的端口组资源来完成。

GET

/v1/nodes/{node_ident}/portgroups

按节点列出端口组

返回与 node_ident 关联的 Bare Metal 端口组列表。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
portgroups	body	数组	端口组资源集合。
uuid	body	字符串	资源的 UUID。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
name	body	字符串	端口组资源的易于理解的标识符。可能未定义。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

节点端口组列表示例

{
  "portgroups": [
    {
      "address": "22:22:22:22:22:22",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "name": "test_portgroup",
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}

GET

/v1/nodes/{node_ident}/portgroups/detail

按节点列出详细的端口组

返回与 node_ident 关联的 Bare Metal 端口组的详细列表。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
portgroups	body	数组	端口组资源集合。
uuid	body	字符串	资源的 UUID。
address (可选)	body	字符串	此端口组的物理硬件地址，通常是硬件 MAC 地址。
name	body	字符串	端口组资源的易于理解的标识符。可能未定义。
node_uuid	body	字符串	此资源所属的节点的 UUID。
standalone_ports_supported	body	布尔值	指示作为此端口组成员的端口是否可以用作独立端口。
internal_info	body	JSON	端口组设置和存储的内部元数据。此字段是只读的。
extra	body	对象	一组或多组任意元数据键值对。
mode	body	字符串	端口组模式。有关可能的值，请参阅 https://linuxkernel.org.cn/doc/Documentation/networking/bonding.txt。如果在创建端口组的请求中未指定，则将设置为 `[DEFAULT]default_portgroup_mode` 配置选项的值。设置后，无法从端口组中删除。
properties	body	JSON	与端口组配置相关的键/值属性。
ports	body	数组	链接到属于此端口组的端口集合。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

节点端口组详细信息示例

{
  "portgroups": [
    {
      "address": "22:22:22:22:22:22",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "mode": "active-backup",
      "name": "test_portgroup",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "bookmark"
        }
      ],
      "properties": {},
      "standalone_ports_supported": true,
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}

端口 (ports)¶

通过 ports 资源完成 Bare Metal 端口资源的列出、搜索、创建、更新和删除。

所有端口在创建时都必须与节点关联。这种关联可以更改，但如果当前节点或目标节点处于过渡状态（例如，正在部署中），或者处于受此类更改影响的不确定状态（例如，节点上有活动的实例），则请求可能会被拒绝。

GET

/v1/ports

列出端口

返回 Bare Metal 端口列表。可以通过在请求中传递一些参数来进行一些过滤。

默认情况下，此查询将返回每个端口的 uuid 和地址。

在版本 1.6 中添加：添加了 node 查询参数。如果在请求中同时指定了 node_uuid 和 node，则将使用 node_uuid 来过滤结果。

在版本 1.8 中添加：添加了 fields 请求参数。如果指定，这将导致响应仅包含指定的字段，而不是默认集。

在版本 1.19 中添加：添加了 pxe_enabled 和 local_link_connection 字段。

在版本 1.24 中添加：添加了 portgroup_uuid 字段。

在版本 1.34 中添加：添加了 physical_network 字段。

在版本 1.43 中添加：添加了 detail 布尔请求参数。如果指定 True，则响应将包含有关每个端口的完整详细信息。

在版本 1.53 中添加：添加了 is_smartnic 字段。

在版本 1.82 中添加：添加了根据节点关联的 shard 过滤端口的功能。

在版本 1.97 中添加：添加了 description 字段。

在版本 1.99 中添加：添加了根据节点关联的 conductor_group 过滤端口的功能。

在版本 1.100 中添加：添加了 vendor 字段。

在版本 1.101 中添加：添加了 category 字段。

正常响应代码：200

请求¶

名称	入参	类型	描述
node (可选)	查询	字符串	过滤返回的端口列表，仅返回与此特定节点（名称或 UUID）关联的端口，如果未找到则返回空集。此过滤器优先于所有其他过滤器，不能与 node_uuid 或 portgroup 同时设置。
node_uuid (可选)	查询	字符串	过滤返回的端口列表，仅返回与此特定节点 UUID 关联的端口，如果未找到则返回空集。此过滤器优先于所有其他过滤器，不能与 node 或 portgroup 同时设置。
portgroup (可选)	查询	字符串	过滤返回的端口列表，仅返回与此特定端口组（名称或 UUID）关联的端口，如果未找到则返回空集。此过滤器优先于所有其他过滤器，不能与 node_uuid 或 node 同时设置。
address (可选)	查询	字符串	过滤返回的端口列表，仅返回具有指定物理硬件地址（通常是 MAC）的端口，如果未找到则返回空集。
shard (可选)	查询	数组	过滤返回的端口列表，仅返回与这些特定 shard 的节点关联的端口，如果未找到则返回空集。
conductor_group (可选)	查询	数组	过滤返回的端口或端口组列表，仅返回具有指定的 `conductor_group` 的端口或端口组，如果未找到则返回空集。包含最多 255 个字符的区分大小写的字符串列表，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。如果指定了 `node`、`node_uuid`、`portgroup` 或 `address`，则不能使用此选项。例如，以下请求仅返回节点在 bear 和 metal 导体组中的端口 GET /v1/ports?conductor_groups=bear,metal
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。

响应¶

名称	入参	类型	描述
ports	body	数组	端口资源集合。
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

端口列表响应示例

{
  "ports": [
    {
      "address": "11:11:11:11:11:11",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

POST

/v1/ports

创建端口

创建一个新的端口资源。

此方法需要节点 UUID 和端口的物理硬件地址（在大多数情况下是 MAC 地址）。

在版本 1.19 中添加：添加了 pxe_enabled 和 local_link_connection 请求和响应字段。

在版本 1.24 中添加：添加了 portgroup_uuid 请求和响应字段。

1.34版本中添加：添加了 physical_network 请求和响应字段。

1.53版本中添加：添加了 is_smartnic 请求和响应字段。

1.88版本中添加：添加了 name 字段。

1.90版本中添加： local_link_connection 字段现在接受一个包含 vtep-logical-switch、vtep-physical-switch 和 port_id 的字典，用于标识 ovn vtep 交换机。

1.94版本中添加：添加了支持通过节点名称或 UUID 创建端口。

在版本 1.97 中添加：添加了 description 字段。

在版本 1.100 中添加：添加了 vendor 字段。

在版本 1.101 中添加：添加了 category 字段。

正常响应代码：201

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
portgroup_uuid (可选)	body	字符串	此资源所属端口组的 UUID。
name (可选)	body	字符串	分配给网络端口的名称。
local_link_connection（可选）	body	JSON	端口绑定配置文件。如果指定，必须包含 `switch_id`（此字段仅接受交换机的 MAC 地址或基于 OpenFlow 的 datapath_id）和 `port_id`（节点端口连接到的交换机上的物理端口标识符）字段。`switch_info` 是一个可选的字符串字段，用于存储任何特定于供应商的信息。
pxe_enabled（可选）	body	布尔值	指示端口上是否启用 PXE。
physical_network (可选)	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
extra (可选)	body	对象	一组或多组任意元数据键值对。
is_smartnic（可选）	body	布尔值	指示端口是否为 Smart NIC 端口。
uuid (可选)	body	字符串	资源的 UUID。
description (可选)	body	字符串	关于网络端口的描述性文本。
vendor（可选）	body	字符串	网络端口的硬件供应商名称。
category (可选)	body	字符串	网络端口的类别。有助于进一步区分端口。

注意

可以使用 node_ident 或 node_uuid 作为有效参数。

示例端口创建请求

{
    "node_ident": "6d85703a-565d-469a-96ce-30b6de53079d",
    "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
    "name": "port1",
    "description": "Physical Network",
    "vendor": "splitrock",
    "category": "hypernet",
    "address": "11:11:11:11:11:11",
    "is_smartnic": true,
    "local_link_connection": {
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "port_id": "Ethernet3/1",
        "switch_info": "switch1"
    },
    "physical_network": "physnet1"
}

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
portgroup_uuid	body	字符串	此资源所属端口组的 UUID。
name (可选)	body	字符串	分配给网络端口的名称。
local_link_connection	body	JSON	端口绑定配置文件。如果指定，必须包含 `switch_id`（此字段仅接受交换机的 MAC 地址或基于 OpenFlow 的 datapath_id）和 `port_id`（节点端口连接到的交换机上的物理端口标识符）字段。`switch_info` 是一个可选的字符串字段，用于存储任何特定于供应商的信息。
pxe_enabled	body	布尔值	指示端口上是否启用 PXE。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
internal_info	body	JSON	端口设置和存储的内部元数据。此字段为只读。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
is_smartnic（可选）	body	布尔值	指示端口是否为 Smart NIC 端口。
description (可选)	body	字符串	关于网络端口的描述性文本。
vendor（可选）	body	字符串	网络端口的硬件供应商名称。
category (可选)	body	字符串	网络端口的类别。有助于进一步区分端口。

示例端口创建响应

{
  "address": "11:11:11:11:11:11",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "is_smartnic": true,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "bookmark"
    }
  ],
  "local_link_connection": {
    "port_id": "Ethernet3/1",
    "switch_id": "0a:1b:2c:3d:4e:5f",
    "switch_info": "switch1"
  },
  "name": "port1",
  "description": "Physical Network",
  "vendor": "splitrock",
  "category": "hypernet",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "physical_network": "physnet1",
  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
  "pxe_enabled": true,
  "updated_at": null,
  "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}

GET

/v1/ports/detail

列出详细端口

返回带有详细信息的裸机端口列表。

在版本 1.6 中添加：添加了 node 查询参数。如果在请求中同时指定了 node_uuid 和 node，则将使用 node_uuid 来过滤结果。

1.19版本中添加：添加了 pxe_enabled 和 local_link_connection 响应字段。

1.24版本中添加：添加了 portgroup 查询参数和 portgroup_uuid 响应字段。

1.34版本中添加：添加了 physical_network 响应字段。

1.53版本中添加：添加了 is_smartnic 响应字段。

1.82版本中添加：添加了根据节点分片过滤端口的能力。

1.88版本中添加：添加了 name 字段。

在版本 1.97 中添加：添加了 description 字段。

在版本 1.100 中添加：添加了 vendor 字段。

在版本 1.101 中添加：添加了 category 字段。

正常响应代码：200

请求¶

名称	入参	类型	描述
node (可选)	查询	字符串	过滤返回的端口列表，仅返回与此特定节点（名称或 UUID）关联的端口，如果未找到则返回空集。此过滤器优先于所有其他过滤器，不能与 node_uuid 或 portgroup 同时设置。
node_uuid (可选)	查询	字符串	过滤返回的端口列表，仅返回与此特定节点 UUID 关联的端口，如果未找到则返回空集。此过滤器优先于所有其他过滤器，不能与 node 或 portgroup 同时设置。
portgroup (可选)	查询	字符串	过滤返回的端口列表，仅返回与此特定端口组（名称或 UUID）关联的端口，如果未找到则返回空集。此过滤器优先于所有其他过滤器，不能与 node_uuid 或 node 同时设置。
address (可选)	查询	字符串	过滤返回的端口列表，仅返回具有指定物理硬件地址（通常是 MAC）的端口，如果未找到则返回空集。
shard (可选)	查询	数组	过滤返回的端口列表，仅返回与这些特定 shard 的节点关联的端口，如果未找到则返回空集。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
ports	body	数组	端口资源集合。
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
portgroup_uuid	body	字符串	此资源所属端口组的 UUID。
name (可选)	body	字符串	分配给网络端口的名称。
local_link_connection	body	JSON	端口绑定配置文件。如果指定，必须包含 `switch_id`（此字段仅接受交换机的 MAC 地址或基于 OpenFlow 的 datapath_id）和 `port_id`（节点端口连接到的交换机上的物理端口标识符）字段。`switch_info` 是一个可选的字符串字段，用于存储任何特定于供应商的信息。
pxe_enabled	body	布尔值	指示端口上是否启用 PXE。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
internal_info	body	JSON	端口设置和存储的内部元数据。此字段为只读。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
is_smartnic（可选）	body	布尔值	指示端口是否为 Smart NIC 端口。
description (可选)	body	字符串	关于网络端口的描述性文本。
vendor（可选）	body	字符串	网络端口的硬件供应商名称。
category (可选)	body	字符串	网络端口的类别。有助于进一步区分端口。

示例详细端口列表响应

{
  "ports": [
    {
      "address": "11:11:11:11:11:11",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "is_smartnic": true,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "local_link_connection": {
        "port_id": "Ethernet3/1",
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "switch_info": "switch1"
      },
      "name": "port1",
      "description": "Physical Network",
      "vendor": "splitrock",
      "category": "hypernet",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "physical_network": "physnet1",
      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "pxe_enabled": true,
      "updated_at": null,
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

GET

/v1/ports/{port_id}

显示端口详细信息

显示给定端口的详细信息。

在版本 1.8 中添加：添加了 fields 请求参数。如果指定，这将导致响应仅包含指定的字段，而不是默认集。

1.19版本中添加：添加了 pxe_enabled 和 local_link_connection 响应字段。

1.24版本中添加：添加了 portgroup_uuid 响应字段。

1.34版本中添加：添加了 physical_network 响应字段。

1.53版本中添加：添加了 is_smartnic 响应字段。

1.88版本中添加：添加了 name 字段。

在版本 1.97 中添加：添加了 description 字段。

正常响应代码：200

请求¶

名称

入参

类型

描述

port_id

路径

字符串

端口的 UUID 或名称。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
portgroup_uuid	body	字符串	此资源所属端口组的 UUID。
name (可选)	body	字符串	分配给网络端口的名称。
local_link_connection	body	JSON	端口绑定配置文件。如果指定，必须包含 `switch_id`（此字段仅接受交换机的 MAC 地址或基于 OpenFlow 的 datapath_id）和 `port_id`（节点端口连接到的交换机上的物理端口标识符）字段。`switch_info` 是一个可选的字符串字段，用于存储任何特定于供应商的信息。
pxe_enabled	body	布尔值	指示端口上是否启用 PXE。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
internal_info	body	JSON	端口设置和存储的内部元数据。此字段为只读。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
is_smartnic（可选）	body	布尔值	指示端口是否为 Smart NIC 端口。
description (可选)	body	字符串	关于网络端口的描述性文本。

示例端口详细信息

{
  "address": "11:11:11:11:11:11",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "is_smartnic": true,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "bookmark"
    }
  ],
  "local_link_connection": {
    "port_id": "Ethernet3/1",
    "switch_id": "0a:1b:2c:3d:4e:5f",
    "switch_info": "switch1"
  },
  "name": "port1",
  "description": "Physical Network",
  "vendor": "splitrock",
  "category": "hypernet",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "physical_network": "physnet1",
  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
  "pxe_enabled": true,
  "updated_at": null,
  "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}

PATCH

/v1/ports/{port_id}

更新端口

更新端口。

在版本 1.19 中添加：添加了 pxe_enabled 和 local_link_connection 字段。

在版本 1.24 中添加：添加了 portgroup_uuid 字段。

在版本 1.34 中添加：添加了 physical_network 字段。

1.53版本中添加：添加了 is_smartnic 字段。

1.88版本中添加：添加了 name 字段。

1.90版本中添加： local_link_connection 字段现在接受一个包含 vtep-logical-switch、vtep-physical-switch 和 port_id 的字典，用于标识 ovn vtep 交换机。

在版本 1.97 中添加：添加了 description 字段。

正常响应代码：200

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

名称	入参	类型	描述
port_id	路径	字符串	端口的 UUID 或名称。

示例端口更新请求

[
   {
      "path" : "/address",
      "value" : "22:22:22:22:22:22",
      "op" : "replace"
   }
]

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
portgroup_uuid	body	字符串	此资源所属端口组的 UUID。
name (可选)	body	字符串	分配给网络端口的名称。
local_link_connection	body	JSON	端口绑定配置文件。如果指定，必须包含 `switch_id`（此字段仅接受交换机的 MAC 地址或基于 OpenFlow 的 datapath_id）和 `port_id`（节点端口连接到的交换机上的物理端口标识符）字段。`switch_info` 是一个可选的字符串字段，用于存储任何特定于供应商的信息。
pxe_enabled	body	布尔值	指示端口上是否启用 PXE。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
internal_info	body	JSON	端口设置和存储的内部元数据。此字段为只读。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
is_smartnic（可选）	body	布尔值	指示端口是否为 Smart NIC 端口。
description (可选)	body	字符串	关于网络端口的描述性文本。

示例端口更新响应

{
  "address": "22:22:22:22:22:22",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "is_smartnic": true,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "bookmark"
    }
  ],
  "local_link_connection": {
    "port_id": "Ethernet3/1",
    "switch_id": "0a:1b:2c:3d:4e:5f",
    "switch_info": "switch1"
  },
  "name": "port1",
  "description": "Physical Network",
  "vendor": "splitrock",
  "category": "hypernet",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "physical_network": "physnet1",
  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
  "pxe_enabled": true,
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}

DELETE

/v1/ports/{port_id}

删除端口

删除端口。

正常响应代码：204

请求¶

名称	入参	类型	描述
port_id	路径	字符串	端口的 UUID 或名称。

按节点列出端口（节点、端口）¶

给定节点标识符（uuid 或 name），API 暴露与该节点关联的所有端口的列表和详细信息。

这些端点不允许修改端口；应该通过访问 /v1/ports 端点下的端口资源来完成。

GET

/v1/nodes/{node_ident}/ports

按节点列出端口

返回与 node_ident 关联的裸机端口列表。

在版本 1.8 中添加：添加了 fields 请求参数。如果指定，这将导致响应仅包含指定的字段，而不是默认集。

在版本 1.19 中添加：添加了 pxe_enabled 和 local_link_connection 字段。

在版本 1.24 中添加：添加了 portgroup_uuid 字段。

在版本 1.34 中添加：添加了 physical_network 字段。

1.53版本中添加：添加了 is_smartnic 响应字段。

正常响应代码：200

错误代码：待定

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
ports	body	数组	端口资源集合。
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例节点端口列表

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

GET

/v1/nodes/{node_ident}/ports/detail

按节点列出详细端口

返回与 node_ident 关联的裸机端口的详细列表。

在版本 1.19 中添加：添加了 pxe_enabled 和 local_link_connection 字段。

在版本 1.24 中添加：添加了 portgroup_uuid 字段。

在版本 1.34 中添加：添加了 physical_network 字段。

1.53版本中添加：添加了 is_smartnic 响应字段。

正常响应代码：200

错误代码：待定

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
ports	body	数组	端口资源集合。
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
local_link_connection	body	JSON	端口绑定配置文件。如果指定，必须包含 `switch_id`（此字段仅接受交换机的 MAC 地址或基于 OpenFlow 的 datapath_id）和 `port_id`（节点端口连接到的交换机上的物理端口标识符）字段。`switch_info` 是一个可选的字符串字段，用于存储任何特定于供应商的信息。
pxe_enabled	body	布尔值	指示端口上是否启用 PXE。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
internal_info	body	JSON	端口设置和存储的内部元数据。此字段为只读。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
is_smartnic（可选）	body	布尔值	指示端口是否为 Smart NIC 端口。

示例节点端口详细信息

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "is_smartnic": true,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "local_link_connection": {
        "port_id": "Ethernet3/1",
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "switch_info": "switch1"
      },
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "physical_network": "physnet1",
      "vendor": "splitrock",
      "category": "hupernet",
      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "pxe_enabled": true,
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

按端口组列出端口（端口组、端口）¶

在版本 1.24 中添加。

给定端口组标识符（uuid 或 name），API 暴露与该端口组关联的所有端口的列表和详细信息。

这些端点不允许修改端口；应该通过访问 /v1/ports 端点下的端口资源来完成。

GET

/v1/portgroups/{portgroup_ident}/ports

按端口组列出端口

返回与 portgroup_ident 关联的裸机端口列表。

当指定时，fields 请求参数将导致响应的内容仅包含指定的字段，而不是默认集。

在版本 1.34 中添加：添加了 physical_network 字段。

1.53版本中添加：添加了 is_smartnic 响应字段。

1.88版本中添加：添加了 name 字段。

在版本 1.97 中添加：添加了 description 字段。

在版本 1.100 中添加：添加了 vendor 字段。

在版本 1.101 中添加：添加了 category 字段。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
portgroup_ident	路径	字符串	端口组的 UUID 或名称。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
ports	body	数组	端口资源集合。
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例端口组端口列表

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

GET

/v1/portgroups/{portgroup_ident}/ports/detail

按端口组列出详细端口

返回与 portgroup_ident 关联的裸机端口的详细列表。

在版本 1.34 中添加：添加了 physical_network 字段。

1.53版本中添加：添加了 is_smartnic 响应字段。

1.88版本中添加：添加了 name 字段。

在版本 1.97 中添加：添加了 description 字段。

在版本 1.100 中添加：添加了 vendor 字段。

在版本 1.101 中添加：添加了 category 字段。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
portgroup_ident	路径	字符串	端口组的 UUID 或名称。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
ports	body	数组	端口资源集合。
uuid	body	字符串	资源的 UUID。
address	body	字符串	此网络端口的物理硬件地址，通常是硬件 MAC 地址。
node_uuid	body	字符串	此资源所属的节点的 UUID。
local_link_connection	body	JSON	端口绑定配置文件。如果指定，必须包含 `switch_id`（此字段仅接受交换机的 MAC 地址或基于 OpenFlow 的 datapath_id）和 `port_id`（节点端口连接到的交换机上的物理端口标识符）字段。`switch_info` 是一个可选的字符串字段，用于存储任何特定于供应商的信息。
pxe_enabled	body	布尔值	指示端口上是否启用 PXE。
physical_network	body	字符串	端口或端口组连接到的物理网络的名称。可以为空。
internal_info	body	JSON	端口设置和存储的内部元数据。此字段为只读。
extra	body	对象	一组或多组任意元数据键值对。
portgroup_uuid	body	字符串	此资源所属端口组的 UUID。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
is_smartnic（可选）	body	布尔值	指示端口是否为 Smart NIC 端口。
name (可选)	body	字符串	分配给网络端口的名称。
description (可选)	body	字符串	关于网络端口的描述性文本。
vendor（可选）	body	字符串	网络端口的硬件供应商名称。
category (可选)	body	字符串	网络端口的类别。有助于进一步区分端口。

示例端口组端口详细信息

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "is_smartnic": true,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "local_link_connection": {
        "port_id": "Ethernet3/1",
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "switch_info": "switch1"
      },
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "physical_network": "physnet1",
      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "pxe_enabled": true,
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

卷（volume）¶

1.32版本中添加。

可以将连接到节点的远程卷的信息与节点关联。有两种类型的资源：卷连接器和卷目标。卷连接器包含节点的发起程序信息。卷目标包含远程卷的目标信息。

卷连接器资源的列出、搜索、创建、更新和删除通过 v1/volume/connectors 资源完成。卷目标的相同操作通过 v1/volume/targets 资源完成。

GET

/v1/volume

列出卷资源链接

返回指向所有卷资源的链接列表。

正常响应代码：200

请求¶

响应¶

名称	入参	类型	描述
connectors	body	数组	链接到卷连接器资源集合。
targets	body	数组	链接到卷目标资源集合。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷列表响应

{
  "connectors": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/connectors",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/connectors",
      "rel": "bookmark"
    }
  ],
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/",
      "rel": "bookmark"
    }
  ],
  "targets": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/targets",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/targets",
      "rel": "bookmark"
    }
  ]
}

GET

/v1/volume/connectors

列出卷连接器

返回所有节点的卷连接器列表。

默认情况下，此查询将返回每个卷连接器的 UUID、节点 UUID、类型和连接器 ID。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node (可选)	查询	字符串	过滤返回的卷连接器列表，并仅返回与此特定节点（名称或 UUID）关联的卷连接器，或者如果没有找到则返回一个空集。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
connectors	body	数组	卷连接器资源集合。
uuid	body	字符串	资源的 UUID。
type	body	字符串	卷连接器的类型，例如“iqn”、“ip”、“wwnn”和“wwpn”。
connector_id	body	字符串	卷连接器的标识符。标识符格式取决于卷连接器的 `type`，例如，如果 `type` 为“iqn”，则为“iqn.2017-05.org.openstack:01:d9a51732c3f”，如果 `type` 为“ip”，则为“192.168.1.2”。
node_uuid	body	字符串	此资源所属的节点的 UUID。
extra	body	对象	一组或多组任意元数据键值对。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
next（可选）	body	字符串	请求集合的下一个 URL。当请求中指定 `limit` 并且仍有项目时，将返回此参数。

示例卷连接器列表响应

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}

示例详细卷连接器列表响应

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "updated_at": null,
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}

POST

/v1/volume/connectors

创建卷连接器

创建一个新的卷连接器资源。

此方法需要节点 UUID、连接器类型和连接器 ID。

正常响应代码：201

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
node_uuid	body	字符串	此资源所属的节点的 UUID。
type	body	字符串	卷连接器的类型，例如“iqn”、“ip”、“wwnn”和“wwpn”。
connector_id	body	字符串	卷连接器的标识符。标识符格式取决于卷连接器的 `type`，例如，如果 `type` 为“iqn”，则为“iqn.2017-05.org.openstack:01:d9a51732c3f”，如果 `type` 为“ip”，则为“192.168.1.2”。
extra (可选)	body	对象	一组或多组任意元数据键值对。
uuid (可选)	body	字符串	资源的 UUID。

示例卷连接器创建请求

{
    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
    "type": "iqn",
    "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f"
}

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
type	body	字符串	卷连接器的类型，例如“iqn”、“ip”、“wwnn”和“wwpn”。
connector_id	body	字符串	卷连接器的标识符。标识符格式取决于卷连接器的 `type`，例如，如果 `type` 为“iqn”，则为“iqn.2017-05.org.openstack:01:d9a51732c3f”，如果 `type` 为“ip”，则为“192.168.1.2”。
node_uuid	body	字符串	此资源所属的节点的 UUID。
extra	body	对象	一组或多组任意元数据键值对。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷连接器创建响应

{
  "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "type": "iqn",
  "updated_at": null,
  "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}

GET

/v1/volume/connectors/{volume_connector_id}

显示卷连接器详细信息

显示给定卷连接器的详细信息。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称

入参

类型

描述

volume_connector_id

路径

字符串

卷连接器的 UUID。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
type	body	字符串	卷连接器的类型，例如“iqn”、“ip”、“wwnn”和“wwpn”。
connector_id	body	字符串	卷连接器的标识符。标识符格式取决于卷连接器的 `type`，例如，如果 `type` 为“iqn”，则为“iqn.2017-05.org.openstack:01:d9a51732c3f”，如果 `type` 为“ip”，则为“192.168.1.2”。
node_uuid	body	字符串	此资源所属的节点的 UUID。
extra	body	对象	一组或多组任意元数据键值对。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷连接器详细信息

{
  "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "type": "iqn",
  "updated_at": null,
  "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}

PATCH

/v1/volume/connectors/{volume_connector_id}

更新卷连接器

更新卷连接器。

只有在与卷连接器关联的节点已关闭电源的情况下才能更新卷连接器。

正常响应代码：200

错误代码：400,401,403,404,409

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

名称	入参	类型	描述
volume_connector_id	路径	字符串	卷连接器的 UUID。

示例卷连接器更新请求

[
   {
      "path" : "/connector_id",
      "value" : "iqn.2017-07.org.openstack:02:10190a4153e",
      "op" : "replace"
   }
]

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
type	body	字符串	卷连接器的类型，例如“iqn”、“ip”、“wwnn”和“wwpn”。
connector_id	body	字符串	卷连接器的标识符。标识符格式取决于卷连接器的 `type`，例如，如果 `type` 为“iqn”，则为“iqn.2017-05.org.openstack:01:d9a51732c3f”，如果 `type` 为“ip”，则为“192.168.1.2”。
node_uuid	body	字符串	此资源所属的节点的 UUID。
extra	body	对象	一组或多组任意元数据键值对。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷连接器更新响应

{
  "connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "type": "iqn",
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}

DELETE

/v1/volume/connector/{volume_connector_id}

删除卷连接器

删除卷连接器。

只有在与卷连接器关联的节点已关闭电源的情况下才能删除卷连接器。

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
volume_connector_id	路径	字符串	卷连接器的 UUID。

GET

/v1/volume/targets

列出卷目标

返回所有节点的卷目标列表。

默认情况下，此查询将返回每个卷目标的 UUID、节点 UUID、卷类型、启动索引和卷 ID。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node (可选)	查询	字符串	过滤返回的卷目标列表，并仅返回与此特定节点（名称或 UUID）关联的卷目标，或者如果没有找到则返回一个空集。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
targets	body	数组	卷目标资源集合。
uuid	body	字符串	资源的 UUID。
volume_type	body	字符串	卷目标的类型，例如“iscsi”和“fibre_channel”。
properties	body	对象	卷的物理信息集合，例如标识符（例如 IQN）和卷的 LUN 号。此信息用于通过存储接口将节点连接到卷。内容取决于卷类型。
boot_index	body	字符串	卷目标的启动索引。“0”表示此卷用作启动卷。
volume_id	body	字符串	卷的标识符。此 ID 由存储接口用于区分卷。
extra	body	对象	一组或多组任意元数据键值对。
node_uuid	body	字符串	此资源所属的节点的 UUID。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
next（可选）	body	字符串	请求集合的下一个 URL。当请求中指定 `limit` 并且仍有项目时，将返回此参数。

示例卷目标列表响应

{
  "targets": [
    {
      "boot_index": 0,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
      "volume_type": "iscsi"
    }
  ]
}

示例详细卷目标列表响应

{
  "targets": [
    {
      "boot_index": 0,
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "properties": {},
      "updated_at": null,
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
      "volume_type": "iscsi"
    }
  ]
}

POST

/v1/volume/targets

创建卷目标

创建一个新的卷目标资源。

此方法需要节点 UUID、卷类型、卷 ID 和启动索引。

正常响应代码：201

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
node_uuid	body	字符串	此资源所属的节点的 UUID。
volume_type	body	字符串	卷目标的类型，例如“iscsi”和“fibre_channel”。
properties (可选)	body	对象	卷的物理信息集合，例如标识符（例如 IQN）和卷的 LUN 号。此信息用于通过存储接口将节点连接到卷。内容取决于卷类型。
boot_index	body	字符串	卷目标的启动索引。“0”表示此卷用作启动卷。
volume_id	body	字符串	卷的标识符。此 ID 由存储接口用于区分卷。
extra (可选)	body	对象	一组或多组任意元数据键值对。
uuid (可选)	body	字符串	资源的 UUID。

示例卷目标创建请求

{
    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
    "volume_type": "iscsi",
    "boot_index": 0,
    "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2"
}

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
volume_type	body	字符串	卷目标的类型，例如“iscsi”和“fibre_channel”。
properties	body	对象	卷的物理信息集合，例如标识符（例如 IQN）和卷的 LUN 号。此信息用于通过存储接口将节点连接到卷。内容取决于卷类型。
boot_index	body	字符串	卷目标的启动索引。“0”表示此卷用作启动卷。
volume_id	body	字符串	卷的标识符。此 ID 由存储接口用于区分卷。
extra	body	对象	一组或多组任意元数据键值对。
node_uuid	body	字符串	此资源所属的节点的 UUID。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷目标创建响应

{
  "boot_index": 0,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "properties": {},
  "updated_at": null,
  "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
  "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
  "volume_type": "iscsi"
}

GET

/v1/volume/targets/{volume_target_id}

显示卷目标详细信息

显示给定卷目标的详细信息。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称

入参

类型

描述

volume_target_id

路径

字符串

卷目标的 UUID。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
volume_type	body	字符串	卷目标的类型，例如“iscsi”和“fibre_channel”。
properties	body	对象	卷的物理信息集合，例如标识符（例如 IQN）和卷的 LUN 号。此信息用于通过存储接口将节点连接到卷。内容取决于卷类型。
boot_index	body	字符串	卷目标的启动索引。“0”表示此卷用作启动卷。
volume_id	body	字符串	卷的标识符。此 ID 由存储接口用于区分卷。
extra	body	对象	一组或多组任意元数据键值对。
node_uuid	body	字符串	此资源所属的节点的 UUID。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷目标详细信息

{
  "boot_index": 0,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "properties": {},
  "updated_at": null,
  "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
  "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
  "volume_type": "iscsi"
}

PATCH

/v1/volume/targets/{volume_target_id}

更新卷目标

更新卷目标。

只有在与卷目标关联的节点已关闭电源的情况下才能更新卷目标。

正常响应代码：200

错误代码：400,401,403,404,409

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

名称	入参	类型	描述
volume_target_id	路径	字符串	卷目标的 UUID。

示例卷目标更新请求

[
   {
      "path" : "/volume_id",
      "value" : "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
      "op" : "replace"
   }
]

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
volume_type	body	字符串	卷目标的类型，例如“iscsi”和“fibre_channel”。
properties	body	对象	卷的物理信息集合，例如标识符（例如 IQN）和卷的 LUN 号。此信息用于通过存储接口将节点连接到卷。内容取决于卷类型。
boot_index	body	字符串	卷目标的启动索引。“0”表示此卷用作启动卷。
volume_id	body	字符串	卷的标识符。此 ID 由存储接口用于区分卷。
extra	body	对象	一组或多组任意元数据键值对。
node_uuid	body	字符串	此资源所属的节点的 UUID。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷目标更新响应

{
  "boot_index": 0,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "properties": {},
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
  "volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
  "volume_type": "iscsi"
}

DELETE

/v1/volume/target/{volume_target_id}

删除卷目标

删除一个卷目标。

只有在与卷目标关联的节点已关电的情况下才能删除卷目标。

正常响应代码：204

错误代码：400,401,403,404,409

请求¶

名称	入参	类型	描述
volume_target_id	路径	字符串	卷目标的 UUID。

按节点列出卷资源 (nodes, volume)¶

1.32版本中添加。

给定一个节点标识符 (uuid 或 name)，API 暴露与该节点关联的所有卷资源的列表和详细信息。

这些端点不允许修改卷连接器和卷目标；应该通过访问 /v1/volume/connectors 和 /v1/volume/targets 端点下的卷资源来完成。

GET

/v1/nodes/{node_ident}/volume

按节点列出卷资源链接

返回与 node_ident 关联的所有卷资源的链接列表。

正常响应代码：200

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
connectors	body	数组	链接到卷连接器资源集合。
targets	body	数组	链接到卷目标资源集合。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

示例卷列表响应

{
  "connectors": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/connectors",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/connectors",
      "rel": "bookmark"
    }
  ],
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/",
      "rel": "bookmark"
    }
  ],
  "targets": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/targets",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/targets",
      "rel": "bookmark"
    }
  ]
}

GET

/v1/nodes/{node_ident}/volume/connectors

按节点列出卷连接器

返回与 node_ident 关联的裸机卷连接器列表。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
connectors	body	数组	卷连接器资源集合。
uuid	body	字符串	资源的 UUID。
type	body	字符串	卷连接器的类型，例如“iqn”、“ip”、“wwnn”和“wwpn”。
connector_id	body	字符串	卷连接器的标识符。标识符格式取决于卷连接器的 `type`，例如，如果 `type` 为“iqn”，则为“iqn.2017-05.org.openstack:01:d9a51732c3f”，如果 `type` 为“ip”，则为“192.168.1.2”。
node_uuid	body	字符串	此资源所属的节点的 UUID。
extra	body	对象	一组或多组任意元数据键值对。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
next（可选）	body	字符串	请求集合的下一个 URL。当请求中指定 `limit` 并且仍有项目时，将返回此参数。

节点卷连接器的示例列表

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}

节点卷连接器的详细示例列表

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}

GET

/v1/nodes/{node_ident}/volume/targets

按节点列出卷目标

返回与 node_ident 关联的裸机卷目标列表。

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应¶

名称	入参	类型	描述
targets	body	数组	卷目标资源集合。
uuid	body	字符串	资源的 UUID。
volume_type	body	字符串	卷目标的类型，例如“iscsi”和“fibre_channel”。
properties	body	对象	卷的物理信息集合，例如标识符（例如 IQN）和卷的 LUN 号。此信息用于通过存储接口将节点连接到卷。内容取决于卷类型。
boot_index	body	字符串	卷目标的启动索引。“0”表示此卷用作启动卷。
volume_id	body	字符串	卷的标识符。此 ID 由存储接口用于区分卷。
extra	body	对象	一组或多组任意元数据键值对。
node_uuid	body	字符串	此资源所属的节点的 UUID。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
next（可选）	body	字符串	请求集合的下一个 URL。当请求中指定 `limit` 并且仍有项目时，将返回此参数。

节点卷目标的示例列表

{
  "targets": [
    {
      "boot_index": 0,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
      "volume_type": "iscsi"
    }
  ]
}

节点卷目标的详细示例列表

{
  "targets": [
    {
      "boot_index": 0,
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "properties": {},
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
      "volume_type": "iscsi"
    }
  ]
}

驱动程序 (drivers)¶

1.30 版本更改：REST API 现在也暴露关于动态驱动程序的信息。

Ironic 有两种类型的驱动程序：经典驱动程序和动态驱动程序。

经典驱动程序是一个 Python 对象，包含管理 Ironic 中注册的裸机节点的所有逻辑。驱动程序可以在一个或多个 ironic-conductor 服务中加载。每个驱动程序包含预先确定的一组实例化接口。每种类型的接口（例如，power 或 boot）执行特定的硬件功能。

动态驱动程序通过硬件类型支持，硬件类型是通过入口点启用的 Python 类。与具有预定接口的经典驱动程序不同，硬件类型可以支持多种类型的接口。例如，ipmi 硬件类型可以支持多种启用节点控制台的方法。对于特定硬件类型的节点使用哪个接口是在运行时确定的。这种接口集合称为动态驱动程序。有关更多信息，请参阅节点 API 文档。

REST API 暴露驱动程序列表以及哪些 ironic-conductor 进程已加载该驱动程序，通过驱动程序资源 (/v1/drivers 端点)。这对于操作员验证异构硬件环境中的配置非常有用。每个 ironic-conductor 进程可以加载一个或多个驱动程序，并且不一定需要加载与其他 ironic-conductor 相同的经典驱动程序。具有相同硬件类型的每个 ironic-conductor 必须启用相同的硬件接口。

REST API 还暴露每个驱动程序的详细信息，例如必须提供给节点 driver_info 的属性，以便该驱动程序管理硬件。

最后，一些驱动程序可以通过 driver_vendor_passthru 端点暴露方法，允许直接与驱动程序交互（即，无需知道特定的节点标识符）。例如，这被 ironic python agent ramdisk 用于获取正在部署/清理的节点的 UUID，方法是使用代理发现的节点的网络接口的 MAC 地址。

GET

/v1/drivers

列出驱动程序

列出所有驱动程序。

1.77 版本新增：添加了 fields 选择器以查询特定字段。

正常响应代码：200

请求¶

名称

入参

类型

描述

type (可选)

查询

字符串

仅列出这种类型的驱动程序。选项是“classic”或“dynamic”。

detail (可选)

查询

布尔值

是否显示驱动程序的详细信息（例如“boot_interface”字段）。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

响应参数¶

响应 BODY 包含一个键“drivers”，其值为 Ironic 服务支持的驱动程序列表。

名称	入参	类型	描述
驱动程序	body	数组	驱动程序对象列表。
name	body	字符串	驱动程序的名称。
hosts	body	数组	支持此驱动程序的主动主机列表。
type	body	字符串	此驱动程序的类型（“classic”或“dynamic”）。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
properties	body	数组	驱动程序属性的链接列表。

1.30 版本更改：如果请求具有将“detail”URL 参数设置为 true，则每个驱动程序还将包含以下字段。

1.86 版本新增：引入了 default_firmware_interface 和 enabled_firmware_interfaces 字段。

名称	入参	类型	描述
default_bios_interface	body	字符串	如果节点没有指定 bios 接口，则动态驱动程序节点使用的默认 bios 接口。
default_boot_interface	body	字符串	如果节点没有指定 boot 接口，则动态驱动程序节点使用的默认 boot 接口。
default_console_interface	body	字符串	如果节点没有指定 console 接口，则动态驱动程序节点使用的默认 console 接口。
default_deploy_interface	body	字符串	如果节点没有指定 deploy 接口，则动态驱动程序节点使用的默认 deploy 接口。
default_firmware_interface	body	字符串	如果节点没有指定 firmware 接口，则动态驱动程序节点使用的默认 firmware 接口。
default_inspect_interface	body	字符串	如果节点没有指定 inspect 接口，则动态驱动程序节点使用的默认 inspect 接口。
default_management_interface	body	字符串	如果节点没有指定 management 接口，则动态驱动程序节点使用的默认 management 接口。
default_network_interface	body	字符串	如果节点没有指定 network 接口，则动态驱动程序节点使用的默认 network 接口。
default_power_interface	body	字符串	如果节点没有指定 power 接口，则动态驱动程序节点使用的默认 power 接口。
default_raid_interface	body	字符串	如果节点没有指定 RAID 接口，则动态驱动程序节点使用的默认 RAID 接口。
default_rescue_interface	body	字符串	如果节点没有指定 rescue 接口，则动态驱动程序节点使用的默认 rescue 接口。
default_storage_interface	body	字符串	如果节点没有指定 storage 接口，则动态驱动程序节点使用的默认 storage 接口。
default_vendor_interface	body	字符串	如果节点没有指定 vendor 接口，则动态驱动程序节点使用的默认 vendor 接口。
enabled_bios_interfaces	body	列表	此驱动程序启用的 bios 接口。
enabled_boot_interfaces	body	列表	此驱动程序启用的 boot 接口。
enabled_console_interfaces	body	列表	此驱动程序启用的 console 接口。
enabled_deploy_interfaces	body	列表	此驱动程序启用的 deploy 接口。
enabled_firmware_interfaces	body	列表	此驱动程序启用的 firmware 接口。
enabled_inspect_interfaces	body	列表	此驱动程序启用的 inspect 接口。
enabled_management_interfaces	body	列表	此驱动程序启用的 management 接口。
enabled_network_interfaces	body	列表	此驱动程序启用的 network 接口。
enabled_power_interfaces	body	列表	此驱动程序启用的 power 接口。
enabled_rescue_interfaces	body	列表	此驱动程序启用的 rescue 接口。
enabled_raid_interfaces	body	列表	此驱动程序启用的 RAID 接口。
enabled_storage_interfaces	body	列表	此驱动程序启用的 storage 接口。
enabled_vendor_interfaces	body	列表	此驱动程序启用的 vendor 接口。

响应示例¶

detail=false（默认）请求的示例

{
  "drivers": [
    {
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool",
          "rel": "bookmark"
        }
      ],
      "name": "agent_ipmitool",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake",
          "rel": "bookmark"
        }
      ],
      "name": "fake",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi",
          "rel": "bookmark"
        }
      ],
      "name": "ipmi",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi/properties",
          "rel": "bookmark"
        }
      ],
      "type": "dynamic"
    }
  ]
}

detail=true 请求的示例

{
  "drivers": [
    {
      "default_bios_interface": null,
      "default_boot_interface": null,
      "default_console_interface": null,
      "default_deploy_interface": null,
      "default_firmware_interface": null,
      "default_inspect_interface": null,
      "default_management_interface": null,
      "default_network_interface": null,
      "default_power_interface": null,
      "default_raid_interface": null,
      "default_rescue_interface": null,
      "default_storage_interface": null,
      "default_vendor_interface": null,
      "enabled_bios_interfaces": null,
      "enabled_boot_interfaces": null,
      "enabled_console_interfaces": null,
      "enabled_deploy_interfaces": null,
      "enabled_firmware_interfaces": null,
      "enabled_inspect_interfaces": null,
      "enabled_management_interfaces": null,
      "enabled_network_interfaces": null,
      "enabled_power_interfaces": null,
      "enabled_raid_interfaces": null,
      "enabled_rescue_interfaces": null,
      "enabled_storage_interfaces": null,
      "enabled_vendor_interfaces": null,
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool",
          "rel": "bookmark"
        }
      ],
      "name": "agent_ipmitool",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "default_bios_interface": null,
      "default_boot_interface": null,
      "default_console_interface": null,
      "default_deploy_interface": null,
      "default_firmware_interface": null,
      "default_inspect_interface": null,
      "default_management_interface": null,
      "default_network_interface": null,
      "default_power_interface": null,
      "default_raid_interface": null,
      "default_rescue_interface": null,
      "default_storage_interface": null,
      "default_vendor_interface": null,
      "enabled_bios_interfaces": null,
      "enabled_boot_interfaces": null,
      "enabled_console_interfaces": null,
      "enabled_deploy_interfaces": null,
      "enabled_firmware_interfaces": null,
      "enabled_inspect_interfaces": null,
      "enabled_management_interfaces": null,
      "enabled_network_interfaces": null,
      "enabled_power_interfaces": null,
      "enabled_raid_interfaces": null,
      "enabled_rescue_interfaces": null,
      "enabled_storage_interfaces": null,
      "enabled_vendor_interfaces": null,
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake",
          "rel": "bookmark"
        }
      ],
      "name": "fake",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "default_bios_interface": "no-bios",
      "default_boot_interface": "pxe",
      "default_console_interface": "no-console",
      "default_deploy_interface": "direct",
      "default_firmware_interface": "no-firmware",
      "default_inspect_interface": "no-inspect",
      "default_management_interface": "ipmitool",
      "default_network_interface": "flat",
      "default_power_interface": "ipmitool",
      "default_raid_interface": "no-raid",
      "default_rescue_interface": "no-rescue",
      "default_storage_interface": "noop",
      "default_vendor_interface": "no-vendor",
      "enabled_bios_interfaces": [
        "no-bios"
      ],
      "enabled_boot_interfaces": [
        "pxe"
      ],
      "enabled_console_interfaces": [
        "no-console"
      ],
      "enabled_deploy_interfaces": [
        "ansible",
        "direct"
      ],
      "enabled_firmware_interface": [
        "no-firmware"
      ],
      "enabled_inspect_interfaces": [
        "no-inspect"
      ],
      "enabled_management_interfaces": [
        "ipmitool"
      ],
      "enabled_network_interfaces": [
        "flat",
        "noop"
      ],
      "enabled_power_interfaces": [
        "ipmitool"
      ],
      "enabled_raid_interfaces": [
        "no-raid",
        "agent"
      ],
      "enabled_rescue_interfaces": [
        "no-rescue"
      ],
      "enabled_storage_interfaces": [
        "noop"
      ],
      "enabled_vendor_interfaces": [
        "no-vendor"
      ],
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi",
          "rel": "bookmark"
        }
      ],
      "name": "ipmi",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi/properties",
          "rel": "bookmark"
        }
      ],
      "type": "dynamic"
    }
  ]
}

GET

/v1/drivers/{driver_name}

显示驱动程序详细信息

显示驱动程序的详细信息。

1.77 版本新增：添加了 fields 选择器以查询特定字段。

1.86 版本新增：引入了 default_firmware_interface 和 enabled_firmware_interfaces 字段。

正常响应代码：200

请求¶

名称

入参

类型

描述

driver_name

路径

字符串

驱动程序的名称。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

响应参数¶

名称	入参	类型	描述
name	body	字符串	驱动程序的名称。
hosts	body	数组	支持此驱动程序的主动主机列表。
type	body	字符串	此驱动程序的类型（“classic”或“dynamic”）。
default_bios_interface	body	字符串	如果节点没有指定 bios 接口，则动态驱动程序节点使用的默认 bios 接口。
default_boot_interface	body	字符串	如果节点没有指定 boot 接口，则动态驱动程序节点使用的默认 boot 接口。
default_console_interface	body	字符串	如果节点没有指定 console 接口，则动态驱动程序节点使用的默认 console 接口。
default_deploy_interface	body	字符串	如果节点没有指定 deploy 接口，则动态驱动程序节点使用的默认 deploy 接口。
default_firmware_interface	body	字符串	如果节点没有指定 firmware 接口，则动态驱动程序节点使用的默认 firmware 接口。
default_inspect_interface	body	字符串	如果节点没有指定 inspect 接口，则动态驱动程序节点使用的默认 inspect 接口。
default_management_interface	body	字符串	如果节点没有指定 management 接口，则动态驱动程序节点使用的默认 management 接口。
default_network_interface	body	字符串	如果节点没有指定 network 接口，则动态驱动程序节点使用的默认 network 接口。
default_power_interface	body	字符串	如果节点没有指定 power 接口，则动态驱动程序节点使用的默认 power 接口。
default_raid_interface	body	字符串	如果节点没有指定 RAID 接口，则动态驱动程序节点使用的默认 RAID 接口。
default_rescue_interface	body	字符串	如果节点没有指定 rescue 接口，则动态驱动程序节点使用的默认 rescue 接口。
default_storage_interface	body	字符串	如果节点没有指定 storage 接口，则动态驱动程序节点使用的默认 storage 接口。
default_vendor_interface	body	字符串	如果节点没有指定 vendor 接口，则动态驱动程序节点使用的默认 vendor 接口。
enabled_bios_interfaces	body	列表	此驱动程序启用的 bios 接口。
enabled_boot_interfaces	body	列表	此驱动程序启用的 boot 接口。
enabled_console_interfaces	body	列表	此驱动程序启用的 console 接口。
enabled_deploy_interfaces	body	列表	此驱动程序启用的 deploy 接口。
enabled_firmware_interfaces	body	列表	此驱动程序启用的 firmware 接口。
enabled_inspect_interfaces	body	列表	此驱动程序启用的 inspect 接口。
enabled_management_interfaces	body	列表	此驱动程序启用的 management 接口。
enabled_network_interfaces	body	列表	此驱动程序启用的 network 接口。
enabled_power_interfaces	body	列表	此驱动程序启用的 power 接口。
enabled_raid_interfaces	body	列表	此驱动程序启用的 RAID 接口。
enabled_rescue_interfaces	body	列表	此驱动程序启用的 rescue 接口。
enabled_storage_interfaces	body	列表	此驱动程序启用的 storage 接口。
enabled_vendor_interfaces	body	列表	此驱动程序启用的 vendor 接口。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
properties	body	数组	驱动程序属性的链接列表。

响应示例¶

{
  "default_bios_interface": "no-bios",
  "default_boot_interface": "pxe",
  "default_console_interface": "no-console",
  "default_deploy_interface": "direct",
  "default_firmware_interface": "no-firmware",
  "default_inspect_interface": "no-inspect",
  "default_management_interface": "ipmitool",
  "default_network_interface": "flat",
  "default_power_interface": "ipmitool",
  "default_raid_interface": "no-raid",
  "default_rescue_interface": "no-rescue",
  "default_storage_interface": "noop",
  "default_vendor_interface": "no-vendor",
  "enabled_bios_interfaces": [
    "no-bios"
  ],
  "enabled_boot_interfaces": [
    "pxe"
  ],
  "enabled_console_interfaces": [
    "no-console"
  ],
  "enabled_deploy_interfaces": [
    "ansible",
    "direct"
  ],
  "enabled_firmware_interface": [
    "no-firmware"
  ],
  "enabled_inspect_interfaces": [
    "no-inspect"
  ],
  "enabled_management_interfaces": [
    "ipmitool"
  ],
  "enabled_network_interfaces": [
    "flat",
    "noop"
  ],
  "enabled_power_interfaces": [
    "ipmitool"
  ],
  "enabled_raid_interfaces": [
    "no-raid",
    "agent"
  ],
  "enabled_rescue_interfaces": [
    "no-rescue"
  ],
  "enabled_storage_interfaces": [
    "noop"
  ],
  "enabled_vendor_interfaces": [
    "no-vendor"
  ],
  "hosts": [
    "897ab1dad809"
  ],
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/drivers/ipmi",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/drivers/ipmi",
      "rel": "bookmark"
    }
  ],
  "name": "ipmi",
  "properties": [
    {
      "href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/drivers/ipmi/properties",
      "rel": "bookmark"
    }
  ],
  "type": "dynamic"
}

GET

/v1/drivers/{driver_name}/properties

显示驱动程序属性

显示 driver_name 期望在每个它管理的节点的 driver_info 字段中提供的必需和可选参数。

要检查是否已向节点提供所有必需的参数，应查询 /v1/nodes/{node_ident}/validate 端点。

正常响应代码：200

请求¶

名称	入参	类型	描述
driver_name	路径	字符串	驱动程序的名称。

响应示例¶

响应 BODY 是一个字典，但键对于每个驱动程序是唯一的。响应的结构是 property : description。

以下示例来自 agent_ipmitool 驱动程序。

{
  "deploy_forces_oob_reboot": "Whether Ironic should force a reboot of the Node via the out-of-band channel after deployment is complete. Provides compatibility with older deploy ramdisks. Defaults to False. 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.",
  "image_http_proxy": "URL of a proxy server for HTTP connections. Optional.",
  "image_https_proxy": "URL of a proxy server for HTTPS connections. Optional.",
  "image_no_proxy": "A comma-separated list of host names, IP addresses and domain names (with optional :port) that will be excluded from proxying. To denote a domain name, use a dot to prefix the domain name. This value will be ignored if ``image_http_proxy`` and ``image_https_proxy`` are not specified. Optional.",
  "ipmi_address": "IP address or hostname of the node. Required.",
  "ipmi_bridging": "bridging_type; default is \"no\". One of \"single\", \"dual\", \"no\". Optional.",
  "ipmi_disable_boot_timeout": "By default ironic will send a raw IPMI command to disable the 60 second timeout for booting.  Setting this option to False will NOT send that command; default value is True. Optional.",
  "ipmi_force_boot_device": "Whether Ironic should specify the boot device to the BMC each time the server is turned on, eg. because the BMC is not capable of remembering the selected boot device across power cycles; default value is False. Optional.",
  "ipmi_local_address": "local IPMB address for bridged requests. Used only if ipmi_bridging is set to \"single\" or \"dual\". Optional.",
  "ipmi_password": "password. Optional.",
  "ipmi_port": "remote IPMI RMCP port. Optional.",
  "ipmi_priv_level": "privilege level; default is ADMINISTRATOR. One of ADMINISTRATOR, CALLBACK, OPERATOR, USER. Optional.",
  "ipmi_protocol_version": "the version of the IPMI protocol; default is \"2.0\". One of \"1.5\", \"2.0\". Optional.",
  "ipmi_target_address": "destination address for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
  "ipmi_target_channel": "destination channel for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
  "ipmi_terminal_port": "node's UDP port to connect to. Only required for console access.",
  "ipmi_transit_address": "transit address for bridged request. Required only if ipmi_bridging is set to \"dual\".",
  "ipmi_transit_channel": "transit channel for bridged request. Required only if ipmi_bridging is set to \"dual\".",
  "ipmi_username": "username; default is NULL user. Optional."
}

GET

/v1/drivers/{driver_name}/raid/logical_disk_properties

显示驱动程序逻辑磁盘属性

1.12 版本中添加。

显示 driver_name 期望在节点的 raid_config 字段中提供的必需和可选参数，如果请求了 RAID 配置更改。

正常响应代码：200

请求¶

名称	入参	类型	描述
driver_name	路径	字符串	驱动程序的名称。

响应示例¶

响应 BODY 是一个字典，但键对于每个驱动程序是唯一的。响应的结构是 property : description。

以下示例来自 agent_ipmitool 驱动程序。

{
  "controller": "Controller to use for this logical disk. If not specified, the driver will choose a suitable RAID controller on the bare metal node. Optional.",
  "disk_type": "The type of disk preferred. Valid values are 'hdd' and 'ssd'. If this is not specified, disk type will not be a selection criterion for choosing backing physical disks. Optional.",
  "interface_type": "The interface type of disk. Valid values are 'sata', 'scsi' and 'sas'. If this is not specified, interface type will not be a selection criterion for choosing backing physical disks. Optional.",
  "is_root_volume": "Specifies whether this disk is a root volume. By default, this is False. Optional.",
  "number_of_physical_disks": "Number of physical disks to use for this logical disk. By default, the driver uses the minimum number of disks required for that RAID level. Optional.",
  "physical_disks": "The physical disks to use for this logical disk. If not specified, the driver will choose suitable physical disks to use. Optional.",
  "raid_level": "RAID level for the logical disk. Valid values are 'JBOD', '0', '1', '2', '5', '6', '1+0', '5+0' and '6+0'. Required.",
  "share_physical_disks": "Specifies whether other logical disks can share physical disks with this logical disk. By default, this is False. Optional.",
  "size_gb": "Size in GiB (Integer) for the logical disk. Use 'MAX' as size_gb if this logical disk is supposed to use the rest of the space available. Required.",
  "volume_name": "Name of the volume to be created. If this is not specified, it will be auto-generated. Optional."
}

驱动程序供应商 Passthru (drivers)¶

每个驱动程序 MAY 支持供应商特定的扩展，称为“直通”方法。

在内部，Ironic 的驱动程序 API 支持通过常见的 HTTP 方法 GET、PUT、POST 和 DELETE 灵活地暴露函数。要调用 passthru 方法，查询字符串必须包含方法名称。例如，如果方法名称是 my_passthru_method，则请求将类似于 /vendor_passthru?method=my_passthru_method。HTTP 请求的内容将转发到驱动程序并在那里进行验证。

GET

/v1/drivers/{driver_name}/vendor_passthru/methods

列出方法

检索给定驱动程序可用的供应商 passthru 方法列表。响应将指示每个供应商 passthru 方法允许哪些 HTTP 方法，方法调用是同步还是异步，以及响应是否包含任何附件。

正常响应代码：200

请求¶

名称	入参	类型	描述
driver_name	路径	字符串	驱动程序的名称。

响应¶

响应 BODY 是一个字典，其键是方法名称。每个项目的取值本身就是一个字典，描述了如何与该方法交互。

名称	入参	类型	描述
async	body	布尔值	如果为 True，则 passthru 函数是异步调用的；如果为 False，则同步调用。
attach	body	布尔值	如果为 True，则返回值将附加到响应对象，如果为 False，则返回值将返回在响应主体中。
description	body	字符串	对方法所做的事情的描述，包括任何方法参数。
http_methods	body	数组	供应商函数支持的 HTTP 方法列表。

方法

/v1/drivers/{driver_name}/vendor_passthru?method={method_name}

调用方法

HTTP METHOD 可能是 GET、POST、PUT、DELETE 中的一种，具体取决于驱动程序和方法。

此端点将请求直接传递给硬件驱动程序。HTTP BODY 必须是可解析的 JSON，它将被转换为传递给该函数的参数。不可解析的 JSON、缺少参数或参数过多将导致请求被拒绝，并返回 HTTP 400 错误。

正常响应代码：200 202

错误代码：400

请求¶

名称	入参	类型	描述
driver_name	路径	字符串	驱动程序的名称。
method_name	查询	字符串	驱动程序特定的方法名称。

所有其他参数应在 BODY 中传递。参数列表因 method_name 而异。

响应¶

不确定。

节点 Bios (nodes)¶

在版本 1.40 中添加。

给定节点标识符（uuid 或 name），API 暴露与该节点关联的所有 Bios 设置列表。

这些端点不允许修改 Bios 设置；应该使用 clean steps 来完成。

GET

/v1/nodes/{node_ident}/bios

按节点列出所有 Bios 设置

返回与 node_ident 关联的 Bios 设置列表。

在版本 1.74 中添加：添加了可以使用的 bios 注册表中的附加字段 ?detail=True（参见下面的详细响应）。添加了 fields 选择器以查询特定字段。

正常响应代码：200

错误代码：404

请求¶

名称

入参

类型

描述

node_ident

路径

字符串

节点的 UUID 或名称。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

detail (可选)

查询

布尔值

是否显示资源的详细信息。如果指定了 fields 参数，则不能设置为 True。

响应¶

名称	入参	类型	描述
bios	body	数组	可选的 Bios 设置列表。它包括以下字段“created_at”、“updated_at”、“links”、“name”、“value”、“attribute_type”、“allowable_values”、“lower_bound”、“max_length”、“min_length”、“read_only”、“reset_required”、“unique”、“upper_bound”
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
name	body	字符串	节点的 Bios 设置名称，例如 `virtualization`。
value	body	字符串	节点的 Bios 设置值，例如“on”。可能为 `null`。

节点 Bios 设置示例列表

{
  "bios": [
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "bookmark"
        }
      ],
      "name": "Virtualization",
      "value": "Enabled"
    }
  ]
}

GET

/v1/nodes/{node_ident}/bios/?detail=True

按节点列出详细的 Bios 设置

返回与 node_ident 关联的详细 Bios 设置列表。详细列表包括通过 Redfish 获取的 BIOS 属性注册表信息。

在版本 1.74 中添加：引入

正常响应代码：200

错误代码：404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
bios	body	数组	可选的 Bios 设置列表。它包括以下字段“created_at”、“updated_at”、“links”、“name”、“value”、“attribute_type”、“allowable_values”、“lower_bound”、“max_length”、“min_length”、“read_only”、“reset_required”、“unique”、“upper_bound”
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
name	body	字符串	节点的 Bios 设置名称，例如 `virtualization`。
value	body	字符串	节点的 Bios 设置值，例如“on”。可能为 `null`。
attribute_type	body	字符串	描述 Bios 设置类型的字符串。可能为 `null`。
allowable_values	body	数组	允许值列表。可能为 `null`。
lower_bound	body	整数	允许的最低整数值。可能为 `null`。
max_length	body	整数	值的最大字符串长度。可能为 `null`。
min_length	body	整数	值的最小字符串长度。可能为 `null`。
read_only	body	布尔值	此 Bios 设置为只读，无法更改。可能为 `null`。
reset_required	body	布尔值	设置此 Bios 设置后需要节点重启。可能为 `null`。
unique	body	布尔值	此 Bios 设置对该节点是唯一的。可能为 `null`。
upper_bound	body	整数	允许的最高整数值。可能为 `null`。

节点 Bios 设置示例列表

{
  "bios": [
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "bookmark"
        }
      ],
      "name": "Virtualization",
      "value": "Enabled",
      "attribute_type": "Enumeration",
      "allowable_values": ["Enabled", "Disabled"],
      "lower_bound": null,
      "max_length": null,
      "min_length": null,
      "read_only": false,
      "reset_required": null,
      "unique": null,
      "upper_bound": null
    }
  ]
}

GET

/v1/nodes/{node_ident}/bios/{bios_setting}

显示节点的单个 Bios 设置

返回与 node_ident 关联的特定 bios bios_setting 的内容。

在版本 1.74 中添加：引入了来自 BIOS 注册表的字段。

正常响应代码：200

错误代码：404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
bios_setting	路径	字符串	Bios 设置的名称。

响应¶

名称	入参	类型	描述
<key>	body	字典	包含 Bios 设置定义的字典。它包括以下字段“created_at”、“updated_at”、“links”、“name”、“value”。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
name	body	字符串	节点的 Bios 设置名称，例如 `virtualization`。
value	body	字符串	节点的 Bios 设置值，例如“on”。可能为 `null`。
attribute_type	body	字符串	描述 Bios 设置类型的字符串。可能为 `null`。
allowable_values	body	数组	允许值列表。可能为 `null`。
lower_bound	body	整数	允许的最低整数值。可能为 `null`。
max_length	body	整数	值的最大字符串长度。可能为 `null`。
min_length	body	整数	值的最小字符串长度。可能为 `null`。
read_only	body	布尔值	此 Bios 设置为只读，无法更改。可能为 `null`。
reset_required	body	布尔值	设置此 Bios 设置后需要节点重启。可能为 `null`。
unique	body	布尔值	此 Bios 设置对该节点是唯一的。可能为 `null`。
upper_bound	body	整数	允许的最高整数值。可能为 `null`。

节点 Bios 设置详细信息示例

{
  "virtualization": {
    "created_at": "2016-08-18T22:28:49.653974+00:00",
    "updated_at": "2016-08-18T22:28:49.653974+00:00",
    "links": [
      {
        "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
        "rel": "self"
      },
      {
        "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
        "rel": "bookmark"
      }
    ],
    "name": "Virtualization",
    "value": "Enabled",
    "attribute_type": "Enumeration",
    "allowable_values": ["Enabled", "Disabled"],
    "lower_bound": null,
    "max_length": null,
    "min_length": null,
    "read_only": false,
    "reset_required": null,
    "unique": null,
    "upper_bound": null
  }
}

节点固件 (nodes)¶

在版本 1.86 中添加。

给定节点标识符（uuid 或 name），API 暴露与该节点关联的所有固件组件列表。

这些端点不允许修改固件组件；应该使用 clean steps 来完成。

GET

/v1/nodes/{node_ident}/firmware

按节点列出所有固件组件

返回与 node_ident 关联的固件组件列表。

正常响应代码：200

错误代码：404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
firmware	body	数组	节点固件组件列表。它包括以下字段“created_at”、“updated_at”、“component”、“initial_version”、“current_version”、“last_version_flashed”
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
组件	body	字符串	节点的固件组件，例如“bios”。
initial_version	body	字符串	固件组件的初始版本。
current_version	body	字符串	固件组件的当前版本。
last_version_flashed	body	字符串	固件组件的上次刷新版本。

节点固件组件列表示例

{
  "firmware": [
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "component": "BMC",
      "initial_version": "v1.0.0",
      "current_version": "v1.2.0",
      "last_version_flashed": "v1.2.0"
    },
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "component": "BIOS",
      "initial_version": "v1.0.0",
      "current_version": "v1.1.5",
      "last_version_flashed": "v1.1.5"
    }
  ]
}

Conductors (conductors)¶

在版本 1.49 中添加。

通过 conductors 资源列出 Conductor 资源。

Conductor 资源是只读的，无法创建、更新或删除。

GET

/v1/conductors

列出 Conductors

返回 Bare Metal 服务所知的 Conductor 列表。

默认情况下，此查询将返回每个 Conductor 的主机名、Conductor 组和活动状态。当查询字符串中的 detail 设置为 True 时，将返回资源的完整表示形式。

正常响应代码：200

请求¶

名称	入参	类型	描述
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个 Conductor 的 `hostname` 和 `alive` 字段 GET /v1/conductors?fields=hostname,alive
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。

响应¶

名称	入参	类型	描述
hostname	body	数组	此 Conductor 的主机名。
conductor_group	body	字符串	节点的 conductor 组。最多 255 个字符的区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
alive	body	布尔值	Conductor 状态指示 Conductor 是否被认为处于活动状态。
驱动程序	body	数组	驱动程序对象列表。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

Conductor 列表响应示例

{
  "conductors": [
    {
      "hostname": "compute1.localdomain",
      "conductor_group": "",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
          "rel": "bookmark"
        }
      ],
      "alive": false
    },
    {
      "hostname": "compute2.localdomain",
      "conductor_group": "",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
          "rel": "bookmark"
        }
      ],
      "alive": true
    }
  ]
}

详细的 Conductor 列表响应示例

{
  "conductors": [
    {
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
          "rel": "bookmark"
        }
      ],
      "created_at": "2018-08-07T08:39:21+00:00",
      "hostname": "compute1.localdomain",
      "conductor_group": "",
      "updated_at": "2018-11-30T07:07:23+00:00",
      "alive": false,
      "drivers": [
        "ipmi"
      ]
    },
    {
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
          "rel": "bookmark"
        }
      ],
      "created_at": "2018-12-05T07:03:19+00:00",
      "hostname": "compute2.localdomain",
      "conductor_group": "",
      "updated_at": "2018-12-05T07:03:21+00:00",
      "alive": true,
      "drivers": [
        "ipmi"
      ]
    }
  ]
}

GET

/v1/conductors/{hostname}

显示 Conductor 详细信息

显示 Conductor 的详细信息。默认情况下，这将返回资源的完整表示形式；可以提供可选的 fields 参数以仅返回指定的集合。

正常响应代码：200

错误代码：400,403,404,406

请求¶

名称

入参

类型

描述

hostname

路径

字符串

Conductor 的主机名。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个 Conductor 的 hostname 和 alive 字段

GET /v1/conductors?fields=hostname,alive

响应¶

名称	入参	类型	描述
hostname	body	数组	此 Conductor 的主机名。
conductor_group	body	字符串	节点的 conductor 组。最多 255 个字符的区分大小写的字符串，包含 `a-z`、`0-9`、`_`、`-` 和 `.`。
alive	body	布尔值	Conductor 状态指示 Conductor 是否被认为处于活动状态。
驱动程序	body	数组	驱动程序对象列表。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

Conductor 的 JSON 表示示例

{
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
      "rel": "bookmark"
    }
  ],
  "created_at": "2018-12-05T07:03:19+00:00",
  "hostname": "compute2.localdomain",
  "conductor_group": "",
  "updated_at": "2018-12-05T07:03:21+00:00",
  "alive": true,
  "drivers": [
    "ipmi"
  ]
}

分配 (allocations)¶

Allocation 资源表示请求查找和分配节点以进行部署。

在版本 1.52 中添加：引入了 Allocation API。

POST

/v1/allocations

创建分配

创建分配。

可以通过资源类和特征请求节点。此外，节点可以在客户端进行预过滤，并将结果的 UUID 和/或名称列表作为 candidate_nodes 提交。否则，将考虑所有节点。

如果满足以下所有条件，则节点适合分配

provision_state 为 available
power_state 不为 null
maintenance 为 false
instance_uuid 为 null
resource_class 与请求的资源类匹配
traits 列表包含所有请求的特征

分配过程是异步的。新的分配以 allocating 状态返回，并且该过程在后台继续。如果成功，node_uuid 字段将填充节点的 UUID，并且节点的 instance_uuid 字段设置为分配的 UUID。

如果您想为已部署的节点回填分配，可以将此节点的 UUID 或名称传递给 node。在这种情况下，分配会立即创建，绕过正常的分配过程。其他参数必须缺失或与提供的节点匹配。

在版本 1.52 中添加：引入了 Allocation API。

在版本 1.58 中添加：添加了回填分配的支持。

在版本 1.60 中添加：引入了 owner 字段。

在版本 1.79 中添加：具有与分配 name 相同的名称的节点将被移动到派生的候选列表的开头。

正常响应代码：201

错误响应代码：400、401、403、409、503

请求¶

名称	入参	类型	描述
resource_class	body	字符串	分配的请求资源类。只有在回填分配时（将设置为这种情况下的节点的 `resource_class`）才缺少。
candidate_nodes (可选)	body	数组	应考虑用于此分配的节点列表（名称或 UUID）。如果未提供，将考虑所有可用节点。
name (可选)	body	字符串	分配的唯一名称。
traits (可选)	body	数组	分配的请求特征列表。
uuid (可选)	body	字符串	资源的 UUID。
extra (可选)	body	对象	一组或多组任意元数据键值对。
node (可选)	body	字符串	用于绕过正常分配过程创建分配的节点 UUID 或名称。警告不得将此字段用于请求具有一个候选节点的常规分配，请使用 `candidate_nodes` 代替。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。

请求示例¶

{
    "name": "allocation-1",
    "resource_class": "bm-large"
}

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
candidate_nodes	body	数组	是候选分配的节点 UUID 列表。
last_error	body	字符串	如果分配处于 `error` 状态，则为分配的错误消息，否则为 `null`。
name	body	字符串	分配的唯一名称。
node_uuid	body	字符串	分配给分配的节点的 UUID。如果尚未分配节点，则为 `null`。
resource_class	body	字符串	分配请求的资源类。如果通过回填创建分配并且目标节点未设置资源类，则可能为 `null`。
state	body	字符串	分配的当前状态。以下之一 `allocating` - 正在进行分配。 `active` - 分配完成，并且分配了 `node_uuid`。 `error` - 分配失败，有关详细信息，请参阅 `last_error`。
traits	body	数组	请求的特征列表。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "candidate_nodes": [],
  "created_at": "2019-02-20T09:43:58+00:00",
  "extra": {},
  "last_error": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "bookmark"
    }
  ],
  "name": "allocation-1",
  "node_uuid": null,
  "owner": null,
  "resource_class": "bm-large",
  "state": "allocating",
  "traits": [],
  "updated_at": null,
  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}

GET

/v1/allocations

列出分配

列出所有分配。

在版本 1.52 中添加：引入了 Allocation API。

在版本 1.60 中添加：引入了 owner 字段。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
node (可选)	查询	字符串	按节点 UUID 或名称过滤分配列表。
resource_class (可选)	查询	字符串	过滤返回的节点列表，并仅返回具有指定的资源类的节点。
state (可选)	查询	字符串	按分配状态过滤分配列表，为 `active`、`allocating` 或 `error` 中的一个。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
candidate_nodes	body	数组	是候选分配的节点 UUID 列表。
last_error	body	字符串	如果分配处于 `error` 状态，则为分配的错误消息，否则为 `null`。
name	body	字符串	分配的唯一名称。
node_uuid	body	字符串	分配给分配的节点的 UUID。如果尚未分配节点，则为 `null`。
resource_class	body	字符串	分配请求的资源类。如果通过回填创建分配并且目标节点未设置资源类，则可能为 `null`。
state	body	字符串	分配的当前状态。以下之一 `allocating` - 正在进行分配。 `active` - 分配完成，并且分配了 `node_uuid`。 `error` - 分配失败，有关详细信息，请参阅 `last_error`。
traits	body	数组	请求的特征列表。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "allocations": [
    {
      "candidate_nodes": [],
      "created_at": "2019-02-20T09:43:58+00:00",
      "extra": {},
      "last_error": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
          "rel": "bookmark"
        }
      ],
      "name": "allocation-1",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "owner": null,
      "resource_class": "bm-large",
      "state": "active",
      "traits": [],
      "updated_at": "2019-02-20T09:43:58+00:00",
      "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
    },
    {
      "candidate_nodes": [],
      "created_at": "2019-02-20T09:43:58+00:00",
      "extra": {},
      "last_error": "Failed to process allocation eff80f47-75f0-4d41-b1aa-cf07c201adac: no available nodes match the resource class bm-large.",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
          "rel": "bookmark"
        }
      ],
      "name": "allocation-2",
      "node_uuid": null,
      "owner": null,
      "resource_class": "bm-large",
      "state": "error",
      "traits": [
        "CUSTOM_GOLD"
      ],
      "updated_at": "2019-02-20T09:43:58+00:00",
      "uuid": "eff80f47-75f0-4d41-b1aa-cf07c201adac"
    }
  ]
}

GET

/v1/allocations/{allocation_id}

显示分配详细信息

显示分配的详细信息。

在版本 1.52 中添加：引入了 Allocation API。

在版本 1.60 中添加：引入了 owner 字段。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称

入参

类型

描述

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

allocation_id

路径

字符串

分配的 UUID 或名称。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
candidate_nodes	body	数组	是候选分配的节点 UUID 列表。
last_error	body	字符串	如果分配处于 `error` 状态，则为分配的错误消息，否则为 `null`。
name	body	字符串	分配的唯一名称。
node_uuid	body	字符串	分配给分配的节点的 UUID。如果尚未分配节点，则为 `null`。
resource_class	body	字符串	分配请求的资源类。如果通过回填创建分配并且目标节点未设置资源类，则可能为 `null`。
state	body	字符串	分配的当前状态。以下之一 `allocating` - 正在进行分配。 `active` - 分配完成，并且分配了 `node_uuid`。 `error` - 分配失败，有关详细信息，请参阅 `last_error`。
traits	body	数组	请求的特征列表。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "candidate_nodes": [],
  "created_at": "2019-02-20T09:43:58+00:00",
  "extra": {},
  "last_error": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "bookmark"
    }
  ],
  "name": "allocation-1",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "owner": null,
  "resource_class": "bm-large",
  "state": "active",
  "traits": [],
  "updated_at": "2019-02-20T09:43:58+00:00",
  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}

PATCH

/v1/allocations/{allocation_id}

更新分配

更新分配。仅允许更新名称和额外字段。

在版本 1.57 中添加：引入了分配更新 API。

正常响应代码：200

错误响应代码：400、401、403、404、409、503

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

名称	入参	类型	描述
allocation_id	路径	字符串	分配的 UUID 或名称。
name (可选)	body	字符串	分配的唯一名称。
extra (可选)	body	对象	一组或多组任意元数据键值对。

请求示例¶

[
    {
        "op": "add",
        "path": "/extra/foo",
        "value": "bar"
    }
]

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
candidate_nodes	body	数组	是候选分配的节点 UUID 列表。
last_error	body	字符串	如果分配处于 `error` 状态，则为分配的错误消息，否则为 `null`。
name	body	字符串	分配的唯一名称。
node_uuid	body	字符串	分配给分配的节点的 UUID。如果尚未分配节点，则为 `null`。
resource_class	body	字符串	分配请求的资源类。如果通过回填创建分配并且目标节点未设置资源类，则可能为 `null`。
state	body	字符串	分配的当前状态。以下之一 `allocating` - 正在进行分配。 `active` - 分配完成，并且分配了 `node_uuid`。 `error` - 分配失败，有关详细信息，请参阅 `last_error`。
traits	body	数组	请求的特征列表。
owner (可选)	body	字符串	拥有该对象的租户的字符串或 UUID。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "node_uuid": null,
  "uuid": "241db410-7b04-4b1c-87ae-4e336435db08",
  "links": [
    {
      "href": "http://10.66.169.122/v1/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
      "rel": "self"
    },
    {
      "href": "http://10.66.169.122/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
      "rel": "bookmark"
    }
  ],
  "extra":
    {
      "foo": "bar"
    },
  "last_error": null,
  "created_at": "2019-06-04T07:46:25+00:00",
  "owner": null,
  "resource_class": "CUSTOM_GOLD",
  "updated_at": "2019-06-06T03:28:19.496960+00:00",
  "traits": [],
  "state": "error",
  "candidate_nodes": [],
  "name": "test_allocation"
}

DELETE

/v1/allocations/{allocation_id}

删除分配

删除分配。

如果分配具有关联的节点，则节点的 instance_uuid 将重置。

如果分配具有分配的节点并且节点为 active 且不在维护模式中，则删除将失败。

在版本 1.52 中添加：引入了 Allocation API。

正常响应代码：204

错误响应代码：400、401、403、404、409、503

请求¶

名称	入参	类型	描述
allocation_id	路径	字符串	分配的 UUID 或名称。

节点分配 (allocations, nodes)¶

给定节点标识符（uuid 或 name），API 允许获取和删除关联的分配。

在版本 1.52 中添加：引入了 Allocation API。

GET

/v1/nodes/{node_ident}/allocation

显示节点分配

显示一个分配的详细信息。

在版本 1.52 中添加：引入了 Allocation API。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称

入参

类型

描述

node_ident

路径

字符串

节点的 UUID 或名称。

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
candidate_nodes	body	数组	是候选分配的节点 UUID 列表。
last_error	body	字符串	如果分配处于 `error` 状态，则为分配的错误消息，否则为 `null`。
name	body	字符串	分配的唯一名称。
node_uuid	body	字符串	分配给分配的节点的 UUID。如果尚未分配节点，则为 `null`。
resource_class	body	字符串	分配请求的资源类。如果通过回填创建分配并且目标节点未设置资源类，则可能为 `null`。
state	body	字符串	分配的当前状态。以下之一 `allocating` - 正在进行分配。 `active` - 分配完成，并且分配了 `node_uuid`。 `error` - 分配失败，有关详细信息，请参阅 `last_error`。
traits	body	数组	请求的特征列表。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "candidate_nodes": [],
  "created_at": "2019-02-20T09:43:58+00:00",
  "extra": {},
  "last_error": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "bookmark"
    }
  ],
  "name": "allocation-1",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "owner": null,
  "resource_class": "bm-large",
  "state": "active",
  "traits": [],
  "updated_at": "2019-02-20T09:43:58+00:00",
  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}

DELETE

/v1/nodes/{node_ident}/allocation

删除节点分配

删除此节点的分配并重置其 instance_uuid。

如果节点分配处于 active 状态且不在 maintenance 模式下，则删除将失败。

在版本 1.52 中添加：引入了 Allocation API。

正常响应代码：204

错误响应代码：400、401、403、404、409、503

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

部署模板 (deploy_templates)¶

部署模板资源表示可在节点部署期间执行的一系列部署步骤。如果在部署时，模板的名称与节点 instance_info.traits 中的一个特征匹配，则该模板将与节点匹配。

1.55版本新增：引入了部署模板 API。

POST

/v1/deploy_templates

创建部署模板

创建部署模板。

1.55版本新增：引入了部署模板 API。

正常响应代码：201

错误响应代码：400、401、403、409

请求¶

名称	入参	类型	描述
name	body	字符串	部署模板的唯一名称。
steps	body	数组	部署模板的部署步骤。必须是包含至少一个部署步骤的字典列表。有关步骤参数，请参阅请求步骤。
uuid (可选)	body	字符串	资源的 UUID。
extra (可选)	body	对象	一组或多组任意元数据键值对。

请求步骤¶

名称	入参	类型	描述
接口	body	字符串	驱动程序接口的名称。
步骤	body	字符串	驱动程序接口上部署步骤方法的名称。
参数	body	对象	传递给部署步骤方法的参数字典。
priority	body	整数	步骤的非负整数优先级。值为 `0` 将禁用该步骤。

请求示例¶

{
    "extra": {},
    "name": "CUSTOM_HYPERTHREADING_ON",
    "steps": [
        {
            "interface": "bios",
            "step": "apply_configuration",
            "args": {
                "settings": [
                    {
                        "name": "LogicalProc",
                        "value": "Enabled"
                    }
                ]
            },
            "priority": 150
        }
    ]
}

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	部署模板的唯一名称。
steps	body	数组	部署模板的部署步骤。必须是包含至少一个部署步骤的字典列表。有关步骤参数，请参阅请求步骤。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_HYPERTHREADING_ON",
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "priority": 150,
      "step": "apply_configuration"
    }
  ],
  "updated_at": null,
  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}

GET

/v1/deploy_templates

列出部署模板

列出所有部署模板。

1.55版本新增：引入了部署模板 API。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	部署模板的唯一名称。
steps	body	数组	部署模板的部署步骤。必须是包含至少一个部署步骤的字典列表。有关步骤参数，请参阅请求步骤。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

示例部署模板列表响应

{
  "deploy_templates": [
    {
      "links": [
        {
          "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "self"
        },
        {
          "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "bookmark"
        }
      ],
      "name": "CUSTOM_HYPERTHREADING_ON",
      "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
    }
  ]
}

示例详细部署模板列表响应

{
  "deploy_templates": [
    {
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "self"
        },
        {
          "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "bookmark"
        }
      ],
      "name": "CUSTOM_HYPERTHREADING_ON",
      "steps": [
        {
          "args": {
            "settings": [
              {
                "name": "LogicalProc",
                "value": "Enabled"
              }
            ]
          },
          "interface": "bios",
          "priority": 150,
          "step": "apply_configuration"
        }
      ],
      "updated_at": null,
      "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
    }
  ]
}

GET

/v1/deploy_templates/{deploy_template_id}

显示部署模板详细信息

显示部署模板的详细信息。

1.55版本新增：引入了部署模板 API。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称

入参

类型

描述

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

deploy_template_id

路径

字符串

部署模板的 UUID 或名称。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	部署模板的唯一名称。
steps	body	数组	部署模板的部署步骤。必须是包含至少一个部署步骤的字典列表。有关步骤参数，请参阅请求步骤。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_HYPERTHREADING_ON",
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "priority": 150,
      "step": "apply_configuration"
    }
  ],
  "updated_at": null,
  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}

PATCH

/v1/deploy_templates/{deploy_template_id}

更新部署模板

更新部署模板。

1.55版本新增：引入了部署模板 API。

正常响应代码：200

错误响应代码：400、401、403、404、409

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

请求¶

名称	入参	类型	描述
deploy_template_id	路径	字符串	部署模板的 UUID 或名称。

[
   {
      "path" : "/name",
      "value" : "CUSTOM_HT_ON",
      "op" : "replace"
   }
]

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	部署模板的唯一名称。
steps	body	数组	部署模板的部署步骤。必须是包含至少一个部署步骤的字典列表。有关步骤参数，请参阅请求步骤。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_HT_ON",
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "priority": 150,
      "step": "apply_configuration"
    }
  ],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}

DELETE

/v1/deploy_templates/{deploy_template_id}

删除部署模板

删除部署模板。

1.55版本新增：引入了部署模板 API。

正常响应代码：204

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
deploy_template_id	路径	字符串	部署模板的 UUID 或名称。

运行手册 (runbooks)¶

运行手册资源表示一系列定义要在节点上执行的操作的步骤集合。运行手册使用户能够以预定义的自动化方式执行复杂的操作。如果运行手册的名称与节点中的一个特征匹配，则该运行手册将与节点匹配。

1.92版本新增：引入了运行手册 API。

POST

/v1/runbooks

创建运行手册

创建运行手册。

1.92版本新增：引入了运行手册 API。

正常响应代码：201

错误响应代码：400、401、403、409

请求¶

名称	入参	类型	描述
name	body	字符串	运行手册的唯一名称。它必须以 `CUSTOM_` 为前缀，使其符合 TRAITS_SCHEMA 格式。运行手册名称必须与指示其可以在节点上运行的节点特征匹配。
steps	body	数组	运行手册模板的运行手册步骤。必须是包含至少一个运行手册步骤的字典列表。有关步骤参数，请参阅请求运行手册步骤。
disable_ramdisk (可选)	body	布尔值	在使用运行手册进行清理或维护操作时，是否启动 ramdisk。
uuid (可选)	body	字符串	资源的 UUID。
extra (可选)	body	对象	一组或多组任意元数据键值对。

请求运行手册步骤¶

名称	入参	类型	描述
接口	body	字符串	驱动程序接口的名称。
步骤	body	字符串	驱动程序接口上运行手册步骤方法的名称。
参数	body	对象	传递给运行手册步骤方法的参数字典。
order	body	整数	步骤的非负整数顺序。

请求示例¶

{
    "extra": {},
    "name": "CUSTOM_AWESOME",
    "steps": [
        {
            "interface": "bios",
            "step": "apply_configuration",
            "args": {
                "settings": [
                    {
                        "name": "LogicalProc",
                        "value": "Enabled"
                    }
                ]
            },
            "order": 1
        }
    ]
}

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	运行手册的唯一名称。它必须以 `CUSTOM_` 为前缀，使其符合 TRAITS_SCHEMA 格式。运行手册名称必须与指示其可以在节点上运行的节点特征匹配。
steps	body	数组	运行手册模板的运行手册步骤。必须是包含至少一个运行手册步骤的字典列表。有关步骤参数，请参阅请求运行手册步骤。
disable_ramdisk (可选)	body	布尔值	如果设置为 `true`，ironic-python-agent ramdisk 将不会在清理期间启动。只有明确标记为不需要 ramdisk 的清理步骤才能在此模式下执行。仅允许进行手动清理。
extra	body	对象	一组或多组任意元数据键值对。
public (可选)	body	布尔值	指示运行手册是否可供公开使用。如果 `runbook_owner` 不为 `null`，则此项必须为 `false`。
owner (可选)	body	字符串	运行手册所有者的唯一标识符。如果 `runbook_public` 为 `true`，则此项必须为 `null`。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "created_at": "2024-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_AWESOME",
  "public": false,
  "owner": null,
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "order": 1,
      "step": "apply_configuration"
    }
  ],
  "updated_at": null,
  "uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}

GET

/v1/runbooks

列出运行手册

列出所有运行手册。

1.92版本新增：引入了运行手册 API。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	运行手册的唯一名称。它必须以 `CUSTOM_` 为前缀，使其符合 TRAITS_SCHEMA 格式。运行手册名称必须与指示其可以在节点上运行的节点特征匹配。
disable_ramdisk (可选)	body	布尔值	如果设置为 `true`，ironic-python-agent ramdisk 将不会在清理期间启动。只有明确标记为不需要 ramdisk 的清理步骤才能在此模式下执行。仅允许进行手动清理。
steps	body	数组	运行手册模板的运行手册步骤。必须是包含至少一个运行手册步骤的字典列表。有关步骤参数，请参阅请求运行手册步骤。
extra	body	对象	一组或多组任意元数据键值对。
public (可选)	body	布尔值	指示运行手册是否可供公开使用。如果 `runbook_owner` 不为 `null`，则此项必须为 `false`。
owner (可选)	body	字符串	运行手册所有者的唯一标识符。如果 `runbook_public` 为 `true`，则此项必须为 `null`。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

示例运行手册列表响应

{
  "runbooks": [
    {
      "links": [
        {
          "href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
          "rel": "self"
        },
        {
          "href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
          "rel": "bookmark"
        }
      ],
      "name": "CUSTOM_AWESOME",
      "uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
    }
  ]
}

示例详细运行手册列表响应

{
  "runbooks": [
    {
      "created_at": "2024-08-18T22:28:48.643434+11:11",
      "disable_ramdisk": false,
      "extra": {},
      "links": [
        {
          "href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
          "rel": "self"
        },
        {
          "href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
          "rel": "bookmark"
        }
      ],
      "name": "CUSTOM_AWESOME",
      "public": false,
      "owner": null,
      "steps": [
        {
          "args": {
            "settings": [
              {
                "name": "LogicalProc",
                "value": "Enabled"
              }
            ]
          },
          "interface": "bios",
          "order": 1,
          "step": "apply_configuration"
        }
      ],
      "updated_at": null,
      "uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
    }
  ]
}

GET

/v1/runbooks/{runbook_id}

显示运行手册详细信息

显示运行手册的详细信息。

1.92版本新增：引入了运行手册 API。

正常响应代码：200

错误响应代码：400、401、403、404

请求参数¶

名称

入参

类型

描述

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

runbook_id

路径

字符串

runbook 的 UUID 或名称。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	运行手册的唯一名称。它必须以 `CUSTOM_` 为前缀，使其符合 TRAITS_SCHEMA 格式。运行手册名称必须与指示其可以在节点上运行的节点特征匹配。
steps	body	数组	运行手册模板的运行手册步骤。必须是包含至少一个运行手册步骤的字典列表。有关步骤参数，请参阅请求运行手册步骤。
disable_ramdisk (可选)	body	布尔值	如果设置为 `true`，ironic-python-agent ramdisk 将不会在清理期间启动。只有明确标记为不需要 ramdisk 的清理步骤才能在此模式下执行。仅允许进行手动清理。
extra	body	对象	一组或多组任意元数据键值对。
public (可选)	body	布尔值	指示运行手册是否可供公开使用。如果 `runbook_owner` 不为 `null`，则此项必须为 `false`。
owner (可选)	body	字符串	运行手册所有者的唯一标识符。如果 `runbook_public` 为 `true`，则此项必须为 `null`。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
  "created_at": "2024-08-18T22:28:48.643434+11:11",
  "disable_ramdisk": false,
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_AWESOME",
  "public": false,
  "owner": null,
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "order": 1,
      "step": "apply_configuration"
    }
  ],
  "updated_at": null,
  "uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}

PATCH

/v1/runbooks/{runbook_id}

更新运行手册

更新运行手册。

1.92版本新增：引入了运行手册 API。

正常响应代码：200

错误响应代码：400、401、403、404、409

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

请求¶

名称	入参	类型	描述
runbook_id	路径	字符串	runbook 的 UUID 或名称。

[
   {
      "path" : "/name",
      "value" : "CUSTOM_AWESOME2",
      "op" : "replace"
   }
]

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
name	body	字符串	运行手册的唯一名称。它必须以 `CUSTOM_` 为前缀，使其符合 TRAITS_SCHEMA 格式。运行手册名称必须与指示其可以在节点上运行的节点特征匹配。
steps	body	数组	运行手册模板的运行手册步骤。必须是包含至少一个运行手册步骤的字典列表。有关步骤参数，请参阅请求运行手册步骤。
disable_ramdisk (可选)	body	布尔值	如果设置为 `true`，ironic-python-agent ramdisk 将不会在清理期间启动。只有明确标记为不需要 ramdisk 的清理步骤才能在此模式下执行。仅允许进行手动清理。
extra	body	对象	一组或多组任意元数据键值对。
public (可选)	body	布尔值	指示运行手册是否可供公开使用。如果 `runbook_owner` 不为 `null`，则此项必须为 `false`。
owner (可选)	body	字符串	运行手册所有者的唯一标识符。如果 `runbook_public` 为 `true`，则此项必须为 `null`。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

{
  "created_at": "2024-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_AWESOME2",
  "public": false,
  "owner": null,
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "order": 1,
      "step": "apply_configuration"
    }
  ],
  "updated_at": "2024-08-18T22:28:49.653974+00:00",
  "uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}

DELETE

/v1/runbooks/{runbook_id}

删除运行手册

删除运行手册。

1.92版本新增：引入了运行手册 API。

正常响应代码：204

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
runbook_id	路径	字符串	runbook 的 UUID 或名称。

节点历史记录¶

1.78版本新增。

通过 API 1.78 版本通过 v1/nodes/{node_ident}/history 端点提供从节点获取事件历史记录的功能。在默认策略配置中，只有“系统”范围的用户以及列出的与节点关联的所有者才能列出和检索节点。

GET

/v1/nodes/{node_ident}/history

列出节点的历史记录条目

正常响应代码：200

错误代码：400,401,403,404

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。

响应¶

名称	入参	类型	描述
history	body	数组	附加到此节点的历史事件。

来自节点的历史事件示例列表

{
  "history": [
    {
      "uuid": "e5840e39-b4ba-4a93-8071-cff9aa2c9633",
      "created_at": "2021-09-15T17:45:04.686541+00:00",
      "severity": "ERROR",
      "event": "Something is wrong",
      "links": [
        {
          "href": "https:///v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/history/e5840e39-b4ba-4a93-8071-cff9aa2c9633",
          "rel": "self"
        }
      ]
    }
  ]
}

GET

/v1/nodes/{node_ident}/history/{history_event_uuid}

检索特定的历史记录条目

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
history_event_uuid	路径	字符串	历史事件的 UUID。

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
user	body	字符串	表示导致记录事件的用户。
severity	body	字符串	返回事件的严重程度指示器。通常，这将指示这是一个错误还是信息条目。
事件	body	字符串	与此错误相关的节点记录的事件消息正文。
event_type	body	字符串	简短的描述性字符串，指示发生错误的地点，以便 API 用户/系统操作员能够识别特定区域的操作中重复出现的问题，例如“部署”、“控制台”、“清理”、“监控”。
conductor	body	数组	此 Conductor 的主机名。

删除节点的历史记录条目¶

由于历史记录记录的不可变性，无法通过 REST API 删除记录。记录和最终过期的历史记录由 conductor 管理。

节点清单¶

1.81版本新增。

给定节点标识符，API 通过 v1/nodes/{node_ident}/inventory 端点提供对与节点关联的内省数据的访问。

清单的格式来自 ironic-python-agent，目前在 agent inventory documentation 中有文档说明。

GET

/v1/nodes/{node_ident}/inventory

显示节点清单

正常响应代码：200

错误代码

404 (NodeNotFound, InventoryNotRecorded)

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。

响应¶

名称	入参	类型	描述
inventory (可选)	body	JSON	此节点的清单。
plugin_data (可选)	body	JSON	此节点的插件数据。

来自节点的清单示例

{
  "inventory": {
    "interfaces":[
      {
        "name":"eth0",
        "mac_address":"52:54:00:90:35:d6",
        "ipv4_address":"192.168.122.128",
        "ipv6_address":"fe80::5054:ff:fe90:35d6%eth0",
        "has_carrier":true,
        "lldp":null,
        "vendor":"0x1af4",
        "product":"0x0001"
      }
    ],
    "cpu":{
      "model_name":"QEMU Virtual CPU version 2.5+",
      "frequency":null,
      "count":1,
      "architecture":"x86_64"
    }
  },
  "plugin_data":{
    "macs":[
      "52:54:00:90:35:d6"
    ],
    "local_gb":10,
    "cpu_arch":"x86_64",
    "memory_mb":2048
  }
}

分片¶

本节描述了返回 Bare Metal 服务中节点分片分布的 API 端点。分片是一种在 Bare Metal 服务中对节点进行分组的方式。它们被 API 客户端用于将节点分成组，从而实现水平扩展。

分片不会直接添加到或从 Bare Metal 服务中删除。相反，操作员可以将节点配置到给定的分片中，方法是将 shard 键设置为任何表示分片的唯一字符串值。

注意

Bare Metal 服务不直接使用分片。相反，它依赖于 API 客户端和外部服务使用分片将节点分成更小的责任区域。

GET

/v1/shards

分片

1.82版本新增。

存在 /v1/shards 端点，以允许查询所有已定义分片之间的节点分布。

正常响应代码：200

错误响应代码：400 403 404

请求¶

此端点不接受任何请求参数。

响应¶

返回一个分片列表以及分配给每个分片的节点数。列表按降序计数排序。

名称	入参	类型	描述
name (可选)	body	字符串	分片的名称。值为“None”表示具有空分片值的节点数。
count (可选)	body	整数	具有此当前字符串作为其分配分片值的节点数。

响应示例¶

{
  "shards": [
    {
      "count": 47,
      "name": "example_shard1"
    },
    {
      "count": 46,
      "name": "example_shard2"
    }
  ]
}

检查规则 (inspection_rules)¶

检查规则由在检查期间针对检查数据进行评估的条件和在满足条件时在节点上运行的操作组成。

1.96版本新增：引入了检查规则 API。

POST

/v1/inspection_rules

创建检查规则

创建检查规则。

1.96版本新增：引入了检查规则 API。

正常响应代码：201

错误响应代码：400、401、403、409

请求¶

名称	入参	类型	描述
uuid (可选)	body	字符串	资源的 UUID。
description (可选)	body	字符串	有关此规则的信息文本。
conditions (可选)	body	数组	在应用规则之前要检查的条件列表。条件是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’和‘multiple’。
动作	body	数组	要在检查期间运行的操作列表。操作是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’。
phase (可选)	body	字符串	指定规则应运行的阶段，默认为“main”。
priority (可选)	body	int	规则的非负整数优先级。指定规则在执行期间的优先级级别。所有规则可以使用 0 到 9999 之间的优先级，负值和高于 10000 的值保留给内置规则。默认优先级为 0。
敏感 (可选)	body	字符串	指示规则是否包含敏感信息。敏感规则还可以查看检查数据中的敏感字段。

请求检查规则条件¶

名称	入参	类型	描述
op	body	字符串	使用指定的参数运行条件的运算符。
参数	body	数组	一个列表（类似于 Python 的 `args`）或一个字典（类似于 Python 的 `*kwargs`），其中包含条件运算符的参数。
循环 (可选)	body	数组	这是一个 Ansible 样式的循环字段。它包含要对相同条件进行迭代的项目列表或字典。
多重 (可选)	body	字符串	确定如何组合所有循环迭代的结果，条件在“任何”检查通过时返回 true，或者只有在“全部”检查通过时，或者“第一个”或“最后一个”检查通过时返回 true。

请求检查规则操作¶

名称	入参	类型	描述
op	body	字符串	在满足条件时执行的运算符，并带有指定的参数。
参数	body	数组	一个列表（类似于 Python 的 `args`）或一个字典（类似于 Python 的 `*kwargs`），其中包含操作运算符的参数。
循环 (可选)	body	数组	这是一个 Ansible 样式的循环字段。它包含要对相同操作进行迭代的项目列表或字典。

请求示例¶

{
    "description": "BMC credentials",
    "phase": "main",
    "priority": 100,
    "sensitive": true,
    "conditions": [
      {
        "op": "contains",
        "args": {"value": "{inventory[system_vendor][manufacturer]}", "regex": "(?i)dell"}
      },
      {
        "op": "is-true",
        "args": {"value": "{node.auto_discovered}"}
      }
    ],
    "actions": [
      {
        "op": "set-attribute",
        "args": {"path": "/driver", "value": "idrac"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "driver_info.redfish_address", "value": "https://{inventory[bmc_address]}"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "/driver_info/redfish_username", "value": "admin"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "/driver_info/redfish_password", "value": "password"}
      }
    ]
  }

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
description (可选)	body	字符串	有关此规则的信息文本。
conditions (可选)	body	数组	在应用规则之前要检查的条件列表。条件是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’和‘multiple’。
动作	body	数组	要在检查期间运行的操作列表。操作是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’。
phase (可选)	body	字符串	指定规则应运行的阶段，默认为“main”。
priority (可选)	body	int	规则的非负整数优先级。指定规则在执行期间的优先级级别。所有规则可以使用 0 到 9999 之间的优先级，负值和高于 10000 的值保留给内置规则。默认优先级为 0。
敏感 (可选)	body	字符串	指示规则是否包含敏感信息。敏感规则还可以查看检查数据中的敏感字段。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
    "created_at": "2025-03-18T22:28:48.643434+11:11",
    "description": "BMC credentials",
    "phase": "main",
    "priority": 100,
    "sensitive": true,
    "actions": null,
    "conditions": null,
    "links": [
      {
        "href": "http://10.60.253.180:6385/v1/inspection_rules/783bf33a-a8e3-1e23-a645-1e95a1f95186",
        "rel": "self"
      },
      {
        "href": "http://10.60.253.180:6385/inspection_rules/783bf33a-a8e3-1e23-a645-1e95a1f95186",
        "rel": "bookmark"
      }
    ],
    "updated_at": null,
    "uuid": "783bf33a-a8e3-1e23-a645-1e95a1f95186"
  }

GET

/v1/inspection_rules

列出检查规则

列出所有检查规则。

1.96版本新增：引入了检查规则 API。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。
phase (可选)	body	字符串	指定规则应运行的阶段，默认为“main”。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
description (可选)	body	字符串	有关此规则的信息文本。
phase (可选)	body	字符串	指定规则应运行的阶段，默认为“main”。
priority (可选)	body	int	规则的非负整数优先级。指定规则在执行期间的优先级级别。所有规则可以使用 0 到 9999 之间的优先级，负值和高于 10000 的值保留给内置规则。默认优先级为 0。
敏感 (可选)	body	字符串	指示规则是否包含敏感信息。敏感规则还可以查看检查数据中的敏感字段。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
conditions (可选)	body	数组	在应用规则之前要检查的条件列表。条件是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’和‘multiple’。
动作	body	数组	要在检查期间运行的操作列表。操作是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’。

响应示例¶

示例检查规则列表响应

{
    "inspection_rules": [
      {
        "description": "BMC credentials",
        "phase": "main",
        "priority": 100,
        "sensitive": true,
        "links": [
          {
            "href": "http://10.60.253.180:6385/v1/inspection_rules/783bf33a-a8e3-1e23-a645-1e95a1f95186",
            "rel": "self"
          },
          {
            "href": "http://10.60.253.180:6385/inspection_rules/783bf33a-a8e3-1e23-a645-1e95a1f95186",
            "rel": "bookmark"
          }
        ],
        "uuid": "783bf33a-a8e3-1e23-a645-1e95a1f95186"
      },
      {
        "description": "Set properties on discovered data",
        "phase": "main",
        "priority": 50,
        "sensitive": false,
        "links": [
          {
            "href": "http://10.60.253.180:6385/v1/inspection_rules/1f3ee449-08cd-9e3f-e1e5-9cfda674081a",
            "rel": "self"
          },
          {
            "href": "http://10.60.253.180:6385/inspection_rules/1f3ee449-08cd-9e3f-e1e5-9cfda674081a",
            "rel": "bookmark"
          }
        ],
        "uuid": "1f3ee449-08cd-9e3f-e1e5-9cfda674081a"
      },
      {
        "description": "Memory systems",
        "phase": "main",
        "priority": 0,
        "sensitive": false,
        "links": [
          {
            "href": "http://10.60.253.180:6385/v1/inspection_rules/210055f4-7367-ff8d-ae42-f4f9e8e85e8a",
            "rel": "self"
          },
          {
            "href": "http://10.60.253.180:6385/inspection_rules/210055f4-7367-ff8d-ae42-f4f9e8e85e8a",
            "rel": "bookmark"
          }
        ],
        "uuid": "210055f4-7367-ff8d-ae42-f4f9e8e85e8a"
      }
    ]
  }

示例详细检查规则列表响应

{
    "inspection_rules": [
      {
        "created_at": "2025-03-14T15:37:29.542187+00:00",
        "description": "Set properties on discovered data",
        "phase": "main",
        "priority": 50,
        "sensitive": false,
        "conditions": [
          {
            "op": "is-true",
            "args": {"value": "{inventory[cpu][count]}"}
          }
        ],
        "actions": [
          {
            "op": "set-attribute",
            "args": {"path": "/properties/cpus", "value": "{inventory[cpu][count]}"}
          },
          {
            "op": "set-attribute",
            "args": {"path": "/properties/memory_mb", "value": "{inventory[memory][physical_mb]}"}
          },
          {
            "op": "set-attribute",
            "args": {"path": "/properties/cpu_arch", "value": "{inventory[cpu][architecture]}"}
          }
        ],
        "links": [
          {
            "href": "http://10.60.253.180:6385/v1/inspection_rules/75a6c1f7-2de0-47b3-9c54-8e6ef3a27bcd",
            "rel": "self"
          },
          {
            "href": "http://10.60.253.180:6385/inspection_rules/75a6c1f7-2de0-47b3-9c54-8e6ef3a27bcd",
            "rel": "bookmark"
          }
        ],
        "updated_at": null,
        "uuid": "783bf33a-a8e3-1e23-a645-1e95a1f95186"
      }
    ]
  }

GET

/v1/inspection_rules/{rule_id}

显示检查规则详细信息

显示检查规则的详细信息。

1.96版本新增：引入了检查规则 API。

正常响应代码：200

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
rule_id (可选)	body	字符串	检查规则的 UUID。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
description (可选)	body	字符串	有关此规则的信息文本。
conditions (可选)	body	数组	在应用规则之前要检查的条件列表。条件是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’和‘multiple’。
动作	body	数组	要在检查期间运行的操作列表。操作是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’。
phase (可选)	body	字符串	指定规则应运行的阶段，默认为“main”。
priority (可选)	body	int	规则的非负整数优先级。指定规则在执行期间的优先级级别。所有规则可以使用 0 到 9999 之间的优先级，负值和高于 10000 的值保留给内置规则。默认优先级为 0。
敏感 (可选)	body	字符串	指示规则是否包含敏感信息。敏感规则还可以查看检查数据中的敏感字段。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

响应示例¶

{
    "created_at": "2025-03-18T22:28:48.643434+11:11",
    "description": "Set properties on discovered data",
    "phase": "main",
    "priority": 50,
    "sensitive": false,
    "conditions": [
      {
        "op": "is-true",
        "args": {"value": "{inventory[cpu][count]}"}
      }
    ],
    "actions": [
      {
        "op": "set-attribute",
        "args": {"path": "/properties/cpus", "value": "{inventory[cpu][count]}"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "/properties/memory_mb", "value": "{inventory[memory][physical_mb]}"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "/properties/cpu_arch", "value": "{inventory[cpu][architecture]}"}
      }
    ],
    "links": [
      {
        "href": "http://10.60.253.180:6385/v1/inspection_rules/1f3ee449-08cd-9e3f-e1e5-9cfda674081a",
        "rel": "self"
      },
      {
        "href": "http://10.60.253.180:6385/inspection_rules/1f3ee449-08cd-9e3f-e1e5-9cfda674081a",
        "rel": "bookmark"
      }
    ],
    "updated_at": null,
    "uuid": "1f3ee449-08cd-9e3f-e1e5-9cfda674081a"
  }

PATCH

/v1/inspection_rules/{rule_id}

更新检查规则

更新一个检查规则。

1.96版本新增：引入了检查规则 API。

正常响应代码：200

错误响应代码：400、401、403、404、409

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

名称	入参	类型	描述
rule_id (可选)	body	字符串	检查规则的 UUID。

[
    {
      "path": "/description",
      "value": "Updated rule for setting hardware properties",
      "op": "replace"
    },
    {
      "path": "/priority",
      "value": 75,
      "op": "replace"
    },
    {
      "path": "/conditions/0",
      "value": {
        "op": "is-true",
        "args": {"value": "{inventory[cpu][count]}"}
      },
      "op": "replace"
    },
    {
      "path": "/actions/-",
      "value": {
        "op": "set-attribute",
        "args": {"path": "/properties/local_gb", "value": "{inventory[disks][0][size]}"}
      },
      "op": "add"
    }
  ]

响应¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
description (可选)	body	字符串	有关此规则的信息文本。
conditions (可选)	body	数组	在应用规则之前要检查的条件列表。条件是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’和‘multiple’。
动作	body	数组	要在检查期间运行的操作列表。操作是一个字典或列表，需要键‘op’和‘args’，以及可选键‘loop’。
phase (可选)	body	字符串	指定规则应运行的阶段，默认为“main”。
priority (可选)	body	int	规则的非负整数优先级。指定规则在执行期间的优先级级别。所有规则可以使用 0 到 9999 之间的优先级，负值和高于 10000 的值保留给内置规则。默认优先级为 0。
敏感 (可选)	body	字符串	指示规则是否包含敏感信息。敏感规则还可以查看检查数据中的敏感字段。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。

{
    "created_at": "2025-03-23T22:28:48.643434+11:11",
    "description": "Updated rule for setting hardware properties",
    "phase": "main",
    "priority": 75,
    "sensitive": false,
    "conditions": [
      {
        "op": "is-true",
        "args": {"value": "{inventory[cpu][count]}"}
      }
    ],
    "actions": [
      {
        "op": "set-attribute",
        "args": {"path": "/properties/cpus", "value": "{inventory[cpu][count]}"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "/properties/memory_mb", "value": "{inventory[memory][physical_mb]}"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "/properties/cpu_arch", "value": "{inventory[cpu][architecture]}"}
      },
      {
        "op": "set-attribute",
        "args": {"path": "/properties/local_gb", "value": "{inventory[disks][0][size]}"}
      }
    ],
    "links": [
      {
        "href": "http://10.60.253.180:6385/v1/inspection_rules/1f3ee449-08cd-9e3f-e1e5-9cfda674081a",
        "rel": "self"
      },
      {
        "href": "http://10.60.253.180:6385/inspection_rules/1f3ee449-08cd-9e3f-e1e5-9cfda674081a",
        "rel": "bookmark"
      }
    ],
    "uuid": "1f3ee449-08cd-9e3f-e1e5-9cfda674081a",
    "updated_at": "2025-03-24T11:42:18.763029+00:00"
  }

DELETE

/v1/inspection_rules/{rule_id}

删除检查规则

删除一个检查规则。

1.96版本新增：引入了检查规则 API。

正常响应代码：204

错误响应代码：400、401、403、404

请求¶

名称	入参	类型	描述
rule_id (可选)	body	字符串	检查规则的 UUID。

DELETE

/v1/inspection_rules

删除所有检查规则

删除所有非内置检查规则。

1.96版本新增：引入了检查规则 API。

正常响应代码：204

错误响应代码：400、401、403

机箱 (chassis)¶

机箱资源类型最初被设想为一种分组节点资源的方式。对此的支持仍然存在于 REST API 中，但是非常有限。机箱对象今天除了作为列出节点组的方式外，不提供任何功能。

不鼓励使用此资源，并且将来可能会被弃用和删除。

GET

/v1/chassis/detail

列出带有详细信息的机箱

列出所有带有详细信息的机箱。

正常响应代码：200

请求¶

名称	入参	类型	描述
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
chassis	body	数组	一个 `chassis` 对象。
description	body	字符串	关于 Ironic 服务的描述性文本。
extra	body	对象	一组或多组任意元数据键值对。

响应示例¶

{
  "chassis": [
    {
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "description": "Sample chassis",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "bookmark"
        }
      ],
      "nodes": [
        {
          "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
          "rel": "bookmark"
        }
      ],
      "updated_at": null,
      "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
    }
  ]
}

GET

/v1/chassis/{chassis_id}

显示机箱详细信息

显示机箱的详细信息。

正常响应代码：200

请求¶

名称

入参

类型

描述

fields (可选)

查询

数组

要在响应中返回的一个或多个字段。

例如，以下请求仅返回每个节点的 uuid 和 name 字段

GET /v1/nodes?fields=uuid,name

chassis_id

路径

字符串

机箱的 UUID。

响应参数¶

名称	入参	类型	描述
uuid	body	字符串	资源的 UUID。
chassis	body	数组	一个 `chassis` 对象。
description	body	字符串	关于 Ironic 服务的描述性文本。
extra	body	对象	一组或多组任意元数据键值对。

响应示例¶

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "description": "Sample chassis",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "bookmark"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "bookmark"
    }
  ],
  "updated_at": null,
  "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}

PATCH

/v1/chassis/{chassis_id}

更新机箱

更新一个机箱。

正常响应代码：200

请求¶

PATCH 请求的 BODY 必须是 JSON PATCH 文档，符合 RFC 6902。

名称	入参	类型	描述
chassis_id	路径	字符串	机箱的 UUID。
description (可选)	body	字符串	关于 Ironic 服务的描述性文本。
extra (可选)	body	对象	一组或多组任意元数据键值对。

请求示例¶

[
    {
        "op": "replace",
        "path": "/description",
        "value": "Updated Chassis"
    }
]

响应参数¶

名称	入参	类型	描述
description	body	字符串	关于 Ironic 服务的描述性文本。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
chassis	body	数组	一个 `chassis` 对象。
nodes	body	数组	链接到此机箱中包含的节点集合。
uuid	body	字符串	资源的 UUID。

响应示例¶

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "description": "Updated Chassis",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "bookmark"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "bookmark"
    }
  ],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}

DELETE

/v1/chassis/{chassis_id}

删除机箱

删除一个机箱。

请求¶

名称	入参	类型	描述
chassis_id	路径	字符串	机箱的 UUID。

POST

/v1/chassis

创建机箱

创建一个机箱。

错误响应代码：201,413,415,405,404,403,401,400,503,409,

请求¶

名称	入参	类型	描述
uuid (可选)	body	字符串	资源的 UUID。
description (可选)	body	字符串	关于 Ironic 服务的描述性文本。
extra (可选)	body	对象	一组或多组任意元数据键值对。

请求示例¶

{
    "description": "Sample chassis"
}

响应参数¶

名称	入参	类型	描述
description	body	字符串	关于 Ironic 服务的描述性文本。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
nodes	body	数组	链接到此机箱中包含的节点集合。
uuid	body	字符串	资源的 UUID。

响应示例¶

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "description": "Sample chassis",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "bookmark"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "bookmark"
    }
  ],
  "updated_at": null,
  "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}

GET

/v1/chassis

列出机箱

列出所有机箱。

在版本 1.43 中添加：添加了 detail 布尔请求参数。当指定 True 时，响应将包含有关每个机箱的完整详细信息。

正常响应代码：200

请求¶

名称	入参	类型	描述
limit (可选)	查询	整数	请求一页的项目大小。返回最多限制值数量的项目。使用 `limit` 参数进行初始有限请求，并将响应中最后一个看到的项目的 ID 作为 `marker` 参数值用于后续有限请求。此值不能大于配置的 `[api]` 部分中的 `max_limit` 选项。如果高于 `max_limit`，则仅返回 `max-limit` 个资源。
marker (可选)	查询	字符串	最后一个已查看项目的 ID。使用 `limit` 参数进行初始限制请求，并在后续限制请求中使用响应中最后一个已查看项目的 ID 作为 `marker` 参数值。
sort_dir (可选)	查询	字符串	按请求的排序方向对响应进行排序。有效值为 `asc`（升序）或 `desc`（降序）。默认值为 `asc`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
sort_key (可选)	查询	字符串	按此属性值对响应进行排序。默认值为 `id`。可以指定多个排序键和排序方向查询参数。如果在配对中省略了排序方向，则 API 使用服务器属性的自然排序方向作为 `sort_key` 提供。
fields (可选)	查询	数组	要在响应中返回的一个或多个字段。例如，以下请求仅返回每个节点的 `uuid` 和 `name` 字段 GET /v1/nodes?fields=uuid,name
detail (可选)	查询	布尔值	是否显示资源的详细信息。如果指定了 `fields` 参数，则不能设置为 True。

响应参数¶

名称	入参	类型	描述
description	body	字符串	关于 Ironic 服务的描述性文本。
links	body	数组	一个相对链接列表。包括 self 和 bookmark 链接。
extra	body	对象	一组或多组任意元数据键值对。
created_at	body	字符串	资源的创建 UTC 日期和时间，ISO 8601 格式。
updated_at	body	字符串	资源的更新 UTC 日期和时间，ISO 8601 格式。可能为“null”。
nodes	body	数组	链接到此机箱中包含的节点集合。
uuid	body	字符串	资源的 UUID。

响应示例¶

{
  "chassis": [
    {
      "description": "Sample chassis",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "bookmark"
        }
      ],
      "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
    }
  ]
}

实用工具¶

本节描述了 ironic-python-agent ramdisk 在与 Bare Metal 服务通信时使用的两个 API 端点。这些先前作为供应商透传方法公开，但是，由于 ironic-python-agent 已成为标准 ramdisk 代理，因此这些方法已成为官方 REST API 的一部分。

注意

提醒操作员不要将 Bare Metal 服务的 API 暴露给不安全的网络。 下面列出的两个 API 端点都可供未经身份验证的客户端使用，因为启动 ironic-python-agent ramdisk 的默认方法不会向代理提供 keystone 凭据。

注意

如果您的驱动程序支持，则可以在 ramdisk 中包含密钥，或通过启动方法传递密钥；如果这样做，您可以配置这些端点以需要身份验证，方法是更改策略规则 baremetal:driver:ipa_lookup 和 baremetal:node:ipa_heartbeat。鉴于此，建议操作员确保此端点仅在 provisioning 和 cleaning 网络上可用。

GET

/v1/lookup

代理查找

在版本 1.22 中添加。

在 REST API 的根目录中公开了一个 /lookup 方法。这仅应由 ironic-python-agent ramdisk 使用，以从 Bare Metal 服务检索所需的配置数据。

默认情况下，/v1/lookup 将仅匹配预期正在运行 ironic-python-agent ramdisk 的节点（例如，因为 Bare Metal 服务刚刚启动了部署）。它不能用作通用搜索机制，尽管可以通过设置 [api] restrict_lookup = false ironic-api 服务的配置选项来更改此行为。

查询字符串应包含 node_uuid 或 addresses 查询参数。如果找到匹配的节点，将返回有关该节点的信息。

正常响应代码：200

错误响应代码：400 404

请求¶

名称	入参	类型	描述
node_uuid (可选)	查询	字符串	可选的节点 UUID。
addresses (可选)	查询	数组	一个或多个端口地址的可选列表。

响应¶

仅返回 ironic-python-agent 进程所需的节点信息。

名称	入参	类型	描述
node	body	JSON	包含节点字段“uuid”、“properties”、“instance_info”和“driver_internal_info”的 JSON 文档；由 ironic-python-agent 进程在对节点进行操作时使用。
config	body	JSON	用于 ironic-python-agent 进程的配置数据的 JSON 文档。

响应示例¶

{
  "config": {
    "heartbeat_timeout": 300,
    "metrics": {
      "backend": "noop",
      "global_prefix": null,
      "prepend_host": false,
      "prepend_host_reverse": true,
      "prepend_uuid": false
    },
    "metrics_statsd": {
      "statsd_host": "localhost",
      "statsd_port": 8125
    }
  },
  "node": {
    "driver_internal_info": {
      "clean_steps": null
    },
    "instance_info": {},
    "links": [
      {
        "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
        "rel": "self"
      },
      {
        "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
        "rel": "bookmark"
      }
    ],
    "properties": {},
    "uuid": "6d85703a-565d-469a-96ce-30b6de53079d"
  }
}

POST

/v1/heartbeat/{node_ident}

代理心跳

在版本 1.22 中添加。

在 REST API 的根目录中公开了一个 /heartbeat 方法。这用作来自 ironic-python-agent ramdisk 的回调，以便活动 ramdisk 可以定期联系 Bare Metal 服务并提供当前联系代理的 URL。

正常响应代码：202

错误响应代码：400 404

在版本 1.36 中添加：用于在心跳期间将 Ironic Python Agent 的版本传递给 Ironic 的 agent_version 参数

在版本 1.62 中添加：用于在心跳期间将 Ironic Python Agent 的令牌传递给 Ironic 的 agent_token 参数

请求¶

名称	入参	类型	描述
node_ident	路径	字符串	节点的 UUID 或名称。
callback_url	查询	字符串	活动 ironic-python-agent ramdisk 的 URL，发送回 Bare Metal 服务并在置备操作期间临时存储。
agent_version	查询	字符串	ironic-python-agent ramdisk 的版本，发送回 Bare Metal 服务并在置备期间存储。
agent_token	查询	字符串	ironic-python-agent ramdisk 的令牌，发送到 Bare Metal 服务进行身份验证。