Configure CIMC through Ansible Rest API Module

Introduction

This document describes how to configure Cisco Integrated Management Controller(CIMC) through the Ansible REST API module.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• UCS CIMC
  
• API
• Ansible

Components Used

• UCS C220-M4,version 4.1(2f)
  

• A client running postman and ansible version 2.14.5

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

CIMC API Overview

All the physical and logical components that comprise Cisco UCS are represented in a hierarchical management information model (MIM), also referred to as the MIT. Each node in the tree represents a managed object (MO) or group of objects that contains its administrative state and its operational state.

The hierarchical structure starts at the top (sys) and contains parent and child nodes. Each node in this tree is a managed object and each object in Cisco UCS has a unique distinguished name (DN) that describes the object and its place in the tree. Managed objects are abstractions of the Cisco UCS resources, such as CPUs, DIMMs, adapter cards, fans, and power supply units.

Illustration of the CIMC MIM Structure:

|——sys———————————––– (sys)
     |——rack-unit-1————————(sys/rack-unit-1)
          |——adaptor-1————————(sys/rack-unit-1/adaptor-1)
          |——psu-1————————(sys/rack-unit-1/psu-1)
          |——psu-2————————(sys/rack-unit-1/psu-2)

Object Naming:

• DN: The distinguished name enables you to unambiguously identify a target object.
• RN: The relative name identifies an object within the context of its parent object. 

For example, this distinguished name:

<dn = "sys/rack-unit-1/adaptor-1/host-eth-eth2"/>

Is composed of 4 relative names:

topSystem MO: rn="sys"
computeRackUnit MO: rn ="rack-unit-1"
adaptorUnit MO: rn="adaptor-<id>"
adaptorHostEthIf MO: rn="host-eth-<id>"

API Used in this Article:

• Authentication: aaaLogin. Initial method for logging in. Use the aaaLogin method to get a valid cookie. 

• Query: configResolveDn. Retrieves objects by DN. 
  

• Configuration: configConfMo. The configConfMo method is used to configure one or more properties in a Managed Object (MO). The MO to be configured is uniquely identified by a Distinguished Name (DN).

Note:

Many query methods include a inHierarchical argument that accepts a Boolean value (true/yes or false/no). When set to true, this argument causes the method to return all child objects within the hierarchy.

Configurations

1. Find the class or DN of the CIMC Managed Object (MO)

To automate the configuration of CIMC via its API, it is essential to determine the specific class or Distinguished Name (DN) information associated with the Managed Objects (MOs) you wish to configure.

1a. Use the API to log in to the CIMC and retrieve the cookie information

Send a POST request to https://{{apic_cimc_ip}}/nuova  and specify the aaaLogin method. Input a username and password.

<aaaLogin
    inName='{{ cimc_username }}'
    inPassword={{ cimc_password }}'>
</aaaLogin>

Copy the cookie from the API response.

Alternatively, you can utilize curl to fetch the cookie information.

curl -k -d "<aaaLogin inName='{{ cimc_username }} ' inPassword='{{ cimc_password }}'></aaaLogin>" https://apic_cimc_ip/nuova

1b. Using the API query method configResolveDn to retrieve all Managed Object (MO) information

When using configResolveDn with inHierarchical="true" and dn="sys/", it retrieves all Managed Object (MO) information from CIMC.

configResolveDn: The configResolveDn method retrieves a single managed object for a specified DN.

inHierarchical=true: When set to true, it returns all child node information. This combination enables fetching all nodes and sub-nodes MO information from CIMC.

dn="sys/": This is the top root of MIT.

API Response:

Copy the Postman execution response to a text editor such as Notepad, PyCharm, or Visual Studio Code for subsequent searching of the class and DN based on MO.

Example 1: Query the class and DN of the timezone

The timezone configured in the current CIMC GUI is "Asia/Shanghai".

Search for 'Asia/Shanghai' from the results returned by Postman in step 1b. The timezone is "Asia/Shanghai", the class is "topSystem", and the DN is "sys/".

<configResolveDn cookie="85da25da6c/c6f2adca-5d27-ba55-a780-9e33548f595c" response="yes" dn="sys/">
    <outConfig>
        <topSystem dn="sys" address="a.b.c.d" currentTime="Wed Apr 10 01:05:12 2024
" localTime="Wed Apr 10 09:05:12 2024 CST +0800" timeZone="Asia/Shanghai"mode="stand-alone" name="dlc-aci01-apic1" fipsEnable="disabled" ccEnable="disabled" >

Example 2: Query the class and DN of the hostname

The hostname configured in the current CIMC GUI is "dlc-aci01-apic1".

<mgmtIf rn="if-1" description="Management Interface Network Settings" id="1" extEnabled="yes" extIp="a.b.c.d" extMask="255.255.255.0" extGw="a.b.c.z" 
ifType="physical" mac="00:A3:8E:E3:7A:DC" hostname="dlc-aci01-apic1"dhcpEnable="no" dnsUsingDhcp="no" ddnsEnable="yes" ddnsDomain="" 
dnsPreferred="a.b.c.z" dnsAlternate="0.0.0.0" ddnsRefreshInterval="0" nicMode="dedicated" vicSlot="0" nicRedundancy="none" 
vlanEnable="no" vlanId="1" vlanPriority="0" portProfile="" v6extEnabled="no" v6extIp="::" v6extGw="::" v6prefix="64" v6linkLocal="::" 
v6SlaacIp="::" v6dhcpEnable="no" v6dnsUsingDhcp="no" v6dnsPreferred="::" v6dnsAlternate="::" subject="blade" autoNeg="enabled" 
adminNetSpeed="auto" adminDuplex="auto" operNetSpeed="1Gbps" operDuplex="full" >

Then, query CIMC visore from https://CIMC_IP/visore.html, the hostname "dlc-aci01-apic1" corresponds to the DN= `sys/rack-unit-1/mgmt/if-1`.

2. Managing CIMC via REST API

• In step 1, you have already identified the class and distinguished name (DN) corresponding to the managed object (MO).

• You can use the Ansible community.general.imc_rest module to manage CIMC via API. Detail info refers to: imc_rest_module Documentation

Use the API method configResolveClass to retrieve Information

configResolveClass: The method retrieves managed object in a given class. If inHierarchical=true, the results contain children. Taking querying firmware version as an example, use API method configResolveClass and specify the classID of the MO.

Ansible script content output:

- name: IMC login and check
  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: |
      <!-- firmware version -->
      <configResolveClassinHierarchical='false'classId='firmwareRunning'/>

Use API method configConfMo to modify the Configuration

To modify the configuration of MO using the CIMC API, utilize the configConfMo method. This method is designed to configure or modify the settings of a specific MO. When invoking configConfMo, it is important to provide the exact class or DN  information of the MO you wish to modify.

Ansible script content output:

   - name: change CIMC description
     community.general.imc_rest:
       hostname: '{{ imc_hostname }}'
       username: '{{ imc_username }}'
       password: '{{ imc_password }}'
       validate_certs: false  
       content: |
        <configConfMo><inConfig>
         <computeRackUnit dn="sys/rack-unit-1" usrLbl="new_lab_CIMC_description"/>
        </inConfig></configConfMo>examples: 

3. CIMC Automation Configuration Workflow Example

Cisco APIC is Cisco ACI controller software installed on UCS C220 series. The workflow illustrates the automated process of re-imaging APIC software.

1. Login to CIMC with pre-check
  - Retrieve firmware version
  - Retrieve faults
  - Retrieve TPM status
2. Update CIMC configurations
  - Update management hostname
  - Update Description
  - Update Timezone
  - Update ntp
  - Enable SOL
  - Update CIMC mapping vmedia
  - Update CIMC boot order to CIMC-map
  - Reboot CIMC
3. Ansible run shell expect to monitor installation status and enter iso link for APIC installation speed up
4. Retrieve CIMC post installation status
  - Update CIMC boot order back to HDD
  - Power-on host

Ansible module example:

Note: The example only includes content info, full ansible module refers to community.general.imc_rest module from Ansible official website

- name: Login to CIMC with pre-check
    content: |
      <!-- firmware version -->
      <configResolveClass inHierarchical='false' classId='firmwareRunning'/>

      <!-- fault -->
      <configResolveClass inHierarchical='false' classId='faultInst'/>

      <!-- TPM status -->
      <configResolveClass inHierarchical='false' classId='equipmentTpm'/>


- name: IMC update CIMC infra info
    content: |
      <!-- Configure hostname -->
      <configConfMo><inConfig>
        <mgmtIf dn="sys/rack-unit-1/mgmt/if-1" hostname="dlc-aci01-apic1"/>
      </inConfig></configConfMo>

      <!-- Configure description -->
      <configConfMo><inConfig>
        <computeRackUnit dn="sys/rack-unit-1" usrLbl="ACI Lab - POD01 - dlc-aci01-apic1"/>
      </inConfig></configConfMo>

      <!-- Configure timeZone -->
      <configConfMo><inConfig>
        <topSystem dn="sys" timeZone="Asia/Shanghai"/>
      </inConfig></configConfMo>

      <!-- Configure NTP -->
      <configConfMo><inConfig>
        <commNtpProvider dn="sys/svc-ext/ntp-svc" ntpServer1="ntp.esl.cisco.com"/>
      </inConfig></configConfMo>


- name: Update CIMC configurations
    content: |
      <!-- IMC change boot order to CIMC-map -->
      <configConfMo><inConfig>
        <lsbootVMedia dn="sys/rack-unit-1/boot-precision/vm-CIMC-map" name="CIMC-map" type="VMEDIA" subtype="cimc-mapped-dvd"  order="1" state="Enabled" />
      </inConfig></configConfMo>

      <!-- CIMC mapping vmedia -->
      <configConfMo><inConfig>
        <commVMediaMap volumeName="ACI-automation" map="www" remoteShare="http://a.b.c.d/Images/ACI/4/4.2/" remoteFile="aci-apic-dk9.4.2.6l.iso" dn="sys/svc-ext/vmedia-svc/vmmap-ACI-automation" ></commVMediaMap>
      </inConfig></configConfMo>

      <!-- CIMC hard reset -->
      <configConfMo><inConfig>
        <computeRackUnit dn="sys/rack-unit-1" adminPower="hard-reset-immediate" />
      </inConfig></configConfMo>

# Ansible run shell expect to monitor installation status and enter iso link for APIC installation speed up
- name: copy apic init script to
  template:
    src: "init.sh"
    dest: /tmp/init.sh
  delegate_to: localhost

- name: Make script executable
  file:
    path: /tmp/init.sh
    mode: "+x"
  delegate_to: localhost
  tags:
    - render
    - init

- name: Run the generated script
  command: /tmp/init.sh
  delegate_to: localhost
  changed_when: no
  tags:
    - script

- name: Retrieve CIMC post installation status
    content: |
      <!-- delete exists CIMC mapping -->
      <configConfMo><inConfig>
        <lsbootVMedia dn="sys/rack-unit-1/boot-precision/vm-CIMC-map" name="CIMC-map" status='removed'/>
      </inConfig></configConfMo>
      <!-- delete exists CIMC mapping vmedia -->
      <configConfMo><inConfig>
        <commVMediaMap dn="sys/svc-ext/vmedia-svc/vmmap-ACI-automation" volumeName="ACI-automation" status='removed' ></commVMediaMap>
      </inConfig></configConfMo>
      <!-- Reconfigure IMC to boot from storage -->
      <configConfMo><inConfig>
        <lsbootStorage dn="sys/rack-unit-1/boot-policy/storage-read-write" access="read-write" order="1" type="storage"/>
      </inConfig></configConfMo>

      <!-- CIMC power up -->
      <configConfMo><inConfig>
        <computeRackUnit dn="sys/rack-unit-1" adminPower="up" />
      </inConfig></configConfMo>
  delegate_to: localhost
  tags:
    - retrieve_CIMC_status

Related Information

Cisco UCS Rack-Mount Servers Cisco IMC XML API Programmer's Guide

community.general.imc_rest module – Manage Cisco IMC hardware through its REST API

UCS Manager Information Model Reference