community.general.imc_rest – Manage Cisco IMC hardware through its REST API
Note
This plugin is part of the community.general collection (version 3.8.3).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
To use it in a playbook, specify: community.general.imc_rest
.
Synopsis
Provides direct access to the Cisco IMC REST API.
Perform any configuration changes and actions that the Cisco IMC supports.
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
Requirements
The below requirements are needed on the host that executes this module.
lxml
xmljson >= 0.1.8
Parameters
Parameter |
Comments |
---|---|
When used instead of This may be convenient to template simple requests, for anything complex use the ansible.builtin.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 |
|
IP Address or hostname of Cisco IMC, resolvable by Ansible control host. |
|
The password to use for authentication. Default: “password” |
|
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 |
|
Connection protocol to use. Choices:
|
|
The socket level timeout in seconds. This is the time that every single connection (every fragment) can spend. If this Default: 60 |
|
Username used to login to the switch. Default: “admin” |
|
If This should only set to Choices:
|
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 toThe read operation timed out
increase thetimeout
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
Examples
- name: Power down server
community.general.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
community.general.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
community.general.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
community.general.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
community.general.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
community.general.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, the following are the fields unique to this module:
Key |
Description |
---|---|
Cisco IMC XML output for the login, translated to JSON using Cobra convention Returned: success Sample: “\”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” |
|
Cisco IMC XML output for any configConfMo XML fragments, translated to JSON using Cobra convention Returned: success Sample: “” |
|
Elapsed time in seconds Returned: always Sample: 31 |
|
Cisco IMC XML error output for last request, translated to JSON using Cobra convention Returned: failed Sample: “\”attributes\”: {\n \”cookie\”: \”\”,\n \”errorCode\”: \”ERR-xml-parse-error\”,\n \”errorDescr\”: \”XML PARSING ERROR: Element \u0027computeRackUnit\u0027, attribute \u0027admin_Power\u0027: The attribute \u0027admin_Power\u0027 is not allowed. \”,\n \”invocationResult\”: \”594\”,\n \”response\”: \”yes\”\n}\n” |
|
Cisco IMC error code Returned: failed Sample: “ERR-xml-parse-error” |
|
Cisco IMC error message Returned: failed Sample: “XML PARSING ERROR: Element \u0027computeRackUnit\u0027, attribute \u0027admin_Power\u0027: The attribute \u0027admin_Power\u0027 is not allowed.\n” |
|
RAW XML input sent to the Cisco IMC, causing the error Returned: failed Sample: “\u003cconfigConfMo\u003e\u003cinConfig\u003e\u003ccomputeRackUnit dn=\”sys/rack-unit-1\” admin_Power=\”down\”/\u003e\u003c/inConfig\u003e\u003c/configConfMo\u003e\n” |
|
RAW XML output received from the Cisco IMC, with error details Returned: failed Sample: “\u003cerror cookie=\”\”\n response=\”yes\”\n errorCode=\”ERR-xml-parse-error\”\n invocationResult=\”594\”\n errorDescr=\”XML PARSING ERROR: Element \u0027computeRackUnit\u0027, attribute \u0027admin_Power\u0027: The attribute \u0027admin_Power\u0027 is not allowed.\\n\”/\u003e\n” |
|
HTTP response message, including content length Returned: always Sample: “OK (729 bytes)” |
|
The HTTP response status code Returned: always Sample: 200 |
Authors
Dag Wieers (@dagwieers)