imc_rest - Manage Cisco IMC hardware through its REST API

New in version 2.4.

Synopsis

Requirements (on host that executes module)

  • lxml
  • xmljson >= 0.1.8

Options

parameter required default choices comments
content
 no
When used instead of path, sets the content of the API requests directly.
This may be convenient to template simple requests, for anything complex use the template module.
You can collate multiple IMC XML fragments and they will be processed sequentially in a single stream, the Cisco IMC output is subsequently merged.
Parameter content is mutual exclusive with parameter path.
hostname
 yes
IP Address or hostname of Cisco IMC, resolvable by Ansible control host.
aliases: host, ip
password
 no password
The password to use for authentication.
path
 no
Name of the absolute path of the filename that includes the body of the http request being sent to the Cisco IMC REST API.
Parameter path is mutual exclusive with parameter content.
aliases: src
protocol
 no https
  • http
  • https
Connection protocol to use.
timeout
 no 60
The socket level timeout in seconds.
This is the time that every single connection (every fragment) can spend. If this timeout is reached, the module will fail with a Connection failure indicating that The read operation timed out.
username
 no admin
Username used to login to the switch.
aliases: user
validate_certs
 no yes
  • yes
  • no
If no, SSL certificates will not be validated.
This should only set to no used on personally controlled sites using self-signed certificates.

Examples

- name: Power down server
  imc_rest:
    hostname: '{{ imc_hostname }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: no
    content: |
      <configConfMo><inConfig>
        <computeRackUnit dn="sys/rack-unit-1" adminPower="down"/>
      </inConfig></configConfMo>
  delegate_to: localhost

- name: Configure IMC using multiple XML fragments
  imc_rest:
    hostname: '{{ imc_hostname }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: no
    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
  imc_rest:
    hostname: '{{ imc_hostname }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: no
    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
  imc_rest:
    hostname: '{{ imc_host }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: no
    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
  imc_rest:
    hostname: '{{ imc_host }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: no
    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
  imc_rest:
    hostname: '{{ imc_host }}'
    username: '{{ imc_username }}'
    password: '{{ imc_password }}'
    validate_certs: no
    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

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
aaLogin
Cisco IMC XML output for the login, translated to JSON using Cobra convention
 success dict "attributes": { "cookie": "", "outCookie": "1498902428/9de6dc36-417c-157c-106c-139efe2dc02a", "outPriv": "admin", "outRefreshPeriod": "600", "outSessionId": "114", "outVersion": "2.0(13e)", "response": "yes" }
configConfMo
Cisco IMC XML output for any configConfMo XML fragments, translated to JSON using Cobra convention
 success dict
elapsed
Elapsed time in seconds
 always int 31
error
Cisco IMC XML error output for last request, translated to JSON using Cobra convention
 failed dict "attributes": { "cookie": "", "errorCode": "ERR-xml-parse-error", "errorDescr": "XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed. ", "invocationResult": "594", "response": "yes" }
error_code
Cisco IMC error code
 failed string ERR-xml-parse-error
error_text
Cisco IMC error message
 failed string XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed.
input
RAW XML input sent to the Cisco IMC, causing the error
 failed string <configConfMo><inConfig><computeRackUnit dn="sys/rack-unit-1" admin_Power="down"/></inConfig></configConfMo>
output
RAW XML output eceived from the Cisco IMC, with error details
 failed string <error cookie="" response="yes" errorCode="ERR-xml-parse-error" invocationResult="594" errorDescr="XML PARSING ERROR: Element 'computeRackUnit', attribute 'admin_Power': The attribute 'admin_Power' is not allowed.\n"/>
response
HTTP response message, including content length
 always string OK (729 bytes)
status
The HTTP response status code
 always dict 200

Notes

Note

  • The XML fragments don’t need an authentication cookie, this is injected by the module automatically.
  • The Cisco IMC XML output is being translated to JSON using the Cobra convention.
  • Any configConfMo change requested has a return status of ‘modified’, even if there was no actual change from the previous configuration. As a result, this module will always report a change on subsequent runs. In case this behaviour is fixed in a future update to Cisco IMC, this module will automatically adapt.
  • If you get a Connection failure related to The read operation timed out increase the timeout parameter. Some XML fragments can take longer than the default timeout.
  • More information about the IMC REST API is available from http://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/c/sw/api/3_0/b_Cisco_IMC_api_301.html

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/imc_rest_module.html