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	支持：不支持	处于差异模式时，将返回有关已更改内容（或可能需要在 check_mode 下更改的内容）的详细信息。

备注

注意

• XML 片段不需要身份验证 Cookie，模块会自动注入。

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

• 任何请求的 configConfMo 更改都返回状态“已修改”，即使与之前的配置没有实际更改。因此，此模块将在后续运行中始终报告更改。如果 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)

集合链接

• 问题追踪器
• 代码仓库 (源码)
• 寻求帮助
• 提交错误报告
• 请求新功能
• 通讯