community.general.imc_rest 模块 – 通过其 REST API 管理 Cisco IMC 硬件

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

如果您使用的是 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。

要在 Playbook 中使用它，请指定：community.general.imc_rest。

概要

• 提供对 Cisco IMC REST API 的直接访问。

• 执行 Cisco IMC 支持的任何配置更改和操作。

• 有关 IMC REST API 的更多信息，请访问 http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/c/sw/api/3_0/b_Cisco_IMC_api_301.html。

要求

以下要求需要在执行此模块的主机上满足。

• lxml

• xmljson >= 0.1.8

参数

参数	注释
content 字符串	当使用它代替 path 时，直接设置 API 请求的内容。 这可能便于模板化简单的请求，对于任何复杂的操作，请使用 ansible.builtin.template 模块。 您可以整理多个 IMC XML 片段，它们将在单个流中按顺序处理，Cisco IMC 输出随后会合并。 参数 content 与参数 path 互斥。
hostname 别名: host, ip 字符串 / 必需	Cisco IMC 的 IP 地址或主机名，可由 Ansible 控制主机解析。
password 字符串	用于身份验证的密码。 默认: "password"
path 别名: src, config_file 路径	包含发送到 Cisco IMC REST API 的 http 请求主体的文件名的绝对路径名称。 参数 path 与参数 content 互斥。
protocol 字符串	要使用的连接协议。 选项 "http" "https" ← (默认)
timeout 整数	套接字级别的超时时间（以秒为单位）。 这是每个连接（每个片段）可以花费的时间。如果达到此 timeout，则模块将失败并显示 Connection failure，指示 The read operation timed out。 默认: 60
username 别名: user 字符串	用于登录交换机的用户名。 默认: "admin"
validate_certs 布尔值	如果 false，则不会验证 SSL 证书。 只有在使用自签名证书的个人控制站点上才应将其设置为 false。 选项 false true ← (默认)

属性

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 模式下运行，并返回更改状态预测，而无需修改目标。
diff_mode	支持: 无	当处于 diff 模式时，将返回有关已更改（或可能需要在 check_mode 中更改）的详细信息。

注意

注意

• XML 片段不需要身份验证 cookie，此 cookie 由模块自动注入。

• Cisco IMC XML 输出正在使用 Cobra 约定转换为 JSON。

• 任何 configConfMo 更改请求的返回状态均为“modified”，即使与之前的配置相比没有实际更改。因此，此模块始终会在后续运行中报告更改。如果此行为在 Cisco IMC 的未来更新中得到修复，则此模块将自动适应。

• 如果您遇到与 The read operation timed out 相关的 Connection failure，请增加 timeout 参数。某些 XML 片段可能需要比默认超时更长的时间。

• 有关 IMC REST API 的更多信息，请访问 http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/c/sw/api/3_0/b_Cisco_IMC_api_301.html

示例

- name: Power down server
  community.general.imc_rest:
    hostname: '{{ imc_hostname }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: false  # only do this when you trust the network!
    content: |
      <configConfMo><inConfig>
        <computeRackUnit dn="sys/rack-unit-1" adminPower="down"/>
      </inConfig></configConfMo>
  delegate_to: localhost

- name: Configure IMC using multiple XML fragments
  community.general.imc_rest:
    hostname: '{{ imc_hostname }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: false  # only do this when you trust the network!
    timeout: 120
    content: |
      <!-- Configure Serial-on-LAN -->
      <configConfMo><inConfig>
        <solIf dn="sys/rack-unit-1/sol-if" adminState="enable" speed=="115200" comport="com0"/>
      </inConfig></configConfMo>

      <!-- Configure Console Redirection -->
      <configConfMo><inConfig>
        <biosVfConsoleRedirection dn="sys/rack-unit-1/bios/bios-settings/Console-redirection"
          vpBaudRate="115200"
          vpConsoleRedirection="com-0"
          vpFlowControl="none"
          vpTerminalType="vt100"
          vpPuttyKeyPad="LINUX"
          vpRedirectionAfterPOST="Always Enable"/>
      </inConfig></configConfMo>
  delegate_to: localhost

- name: Enable PXE boot and power-cycle server
  community.general.imc_rest:
    hostname: '{{ imc_hostname }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: false  # only do this when you trust the network!
    content: |
      <!-- Configure PXE boot -->
      <configConfMo><inConfig>
        <lsbootLan dn="sys/rack-unit-1/boot-policy/lan-read-only" access="read-only" order="1" prot="pxe" type="lan"/>
      </inConfig></configConfMo>

      <!-- Power cycle server -->
      <configConfMo><inConfig>
        <computeRackUnit dn="sys/rack-unit-1" adminPower="cycle-immediate"/>
      </inConfig></configConfMo>
  delegate_to: localhost

- name: Reconfigure IMC to boot from storage
  community.general.imc_rest:
    hostname: '{{ imc_host }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: false  # only do this when you trust the network!
    content: |
      <configConfMo><inConfig>
        <lsbootStorage dn="sys/rack-unit-1/boot-policy/storage-read-write" access="read-write" order="1" type="storage"/>
      </inConfig></configConfMo>
  delegate_to: localhost

- name: Add customer description to server
  community.general.imc_rest:
    hostname: '{{ imc_host }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: false  # only do this when you trust the network!
    content: |
        <configConfMo><inConfig>
          <computeRackUnit dn="sys/rack-unit-1" usrLbl="Customer Lab - POD{{ pod_id }} - {{ inventory_hostname_short }}"/>
        </inConfig></configConfMo>
    delegate_to: localhost

- name: Disable HTTP and increase session timeout to max value 10800 secs
  community.general.imc_rest:
    hostname: '{{ imc_host }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: false  # only do this when you trust the network!
    timeout: 120
    content: |
        <configConfMo><inConfig>
          <commHttp dn="sys/svc-ext/http-svc" adminState="disabled"/>
        </inConfig></configConfMo>

        <configConfMo><inConfig>
          <commHttps dn="sys/svc-ext/https-svc" adminState="enabled" sessionTimeout="10800"/>
        </inConfig></configConfMo>
    delegate_to: localhost

返回值

通用返回值记录在此处，以下是此模块独有的字段

键	描述
aaLogin 字典	Cisco IMC 登录的 XML 输出，使用 Cobra 约定转换为 JSON 返回: 成功 示例: "\"attributes\": {\n    \"cookie\": \"\",\n    \"outCookie\": \"1498902428/9de6dc36-417c-157c-106c-139efe2dc02a\",\n    \"outPriv\": \"admin\",\n    \"outRefreshPeriod\": \"600\",\n    \"outSessionId\": \"114\",\n    \"outVersion\": \"2.0(13e)\",\n    \"response\": \"yes\"\n}\n"
configConfMo 字典	任何 configConfMo XML 片段的 Cisco IMC XML 输出，使用 Cobra 约定转换为 JSON 返回: 成功 示例: ""
elapsed 整数	经过的时间（以秒为单位） 返回: 始终 示例: 31
error 字典	最后一次请求的 Cisco IMC XML 错误输出，使用 Cobra 约定转换为 JSON 返回: 失败 示例: "\"attributes\": {\n    \"cookie\": \"\",\n    \"errorCode\": \"ERR-xml-parse-error\",\n    \"errorDescr\": \"XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed. \",\n    \"invocationResult\": \"594\",\n    \"response\": \"yes\"\n}\n"
error_code 字符串	Cisco IMC 错误代码 返回: 失败 示例: "ERR-xml-parse-error"
error_text 字符串	Cisco IMC 错误消息 返回: 失败 示例: "XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed.\n"
input 字符串	发送到 Cisco IMC 的原始 XML 输入，导致错误 返回: 失败 示例: "<configConfMo><inConfig><computeRackUnit dn=\"sys/rack-unit-1\" admin_Power=\"down\"/></inConfig></configConfMo>\n"
output 字符串	从 Cisco IMC 收到的原始 XML 输出，包含错误详细信息 返回: 失败 示例: "<error cookie=\"\"\n  response=\"yes\"\n  errorCode=\"ERR-xml-parse-error\"\n  invocationResult=\"594\"\n  errorDescr=\"XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed.\\n\"/>\n"
response 字符串	HTTP 响应消息，包括内容长度 返回: 始终 示例: "OK (729 bytes)"
status 字典	HTTP 响应状态代码 返回: 始终 示例: 200

作者

• Dag Wieers (@dagwieers)

合集链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助
• 提交错误报告
• 请求功能
• 通信