Showing results for 
Search instead for 
Did you mean: 

Automated Intersight Device Claim


Cisco Intersight Automated Device Claim and API Usage

This document provides an overview of automated UCS and HyperFlex device claim using the Cisco Intersight API and Python SDK.  See the Intersight API Overview for more information on the Intersight API and how to use API keys for automation with Python and other scripting or programming languages.  For general information on Intersight, visit Cisco Intersight - Cisco

Automated Device Claim Demo

  • The video demo of automated device claim includes information on the device claim process and shows how device connector and Intersight APIs can be used with Python to gather device information and interact with Intersight.

Intersight Python SDK

  • Intersight's Python SDK is hosted on GitHub at  The GitHub pages have install and usage instructions including example scripts for device claim and device delete.  Requirements and installation instructions for the Python SDK are summarized as follows:

Python Examples

  • The examples directory of the Python SDK has several scripts and sample data files for using the Intersight API and interacting with devices during device claim.  The '-h' command line option can be used to get help on using the examples:

usage: [-h] [-a API_PARAMS] -d DEVICES

optional arguments:

  -h, --help            show this help message and exit

  -a API_PARAMS, --api_params API_PARAMS

                        JSON file with Intersight API parameters. Default:


  -d DEVICES, --devices DEVICES

                        JSON file with device access information (device

                        hostname, username, password, and proxy settings if


Intersight API Parameters

  • Scripts in the examples directory read Intersight API information from the intersight_api_params.json file by default or the user can specify a different file with the '-a' command line option.  The example_intersight_api_params.json shows the api URI, API Key ID, and Private Key file location parameters required to interact with the Intersight API:


    "api_base_uri": "",

    "api_key_id": "<api key id from Intersight portal>",

    "api_private_key_file": "<directory path to>SecretKey.txt"


  • API key information should be customized based on keys generated from (User Profile->Generate API Keys).

Device information and Device Connector API Usage

Automating the device claim process involves connecting to devices through each device's device connector API.  The device connector API provides the following features:

  • Enable/Disable device connector services.
  • Configure the device access mode as Read-Only or Allow Control.
  • Configure HTTPS connections to Intersight through a proxy.
  • Retrieve Device ID and Claim Codes from a device.

The device connector API requires authentication with each local device being claimed.  Information for each device can be passed to the script and the examples directory within the Python SDK provides an example_devices.json file with device type, hostname, username/password, and other optional information (proxy and read-only access mode) needed for accessing each device:



        "device_type": "ucsm",

        "hostname": "",

        "password": "password",

        "proxy_host": "",

        "proxy_port": 80,

        "username": "admin",

        "read_only": true



        "device_type": "ucsm",

        "hostname": "",

        "password": "password",

        "username": "admin",

        "read_only": true



        "device_type": "imc",

        "hostname": "",

        "password": "password",

        "proxy_host": "",

        "proxy_port": 80,

        "username": "admin"



Data Organization with Ansible

While not required for using the script, Ansible provides a simple way to use the script to make parallel calls to many devices and organize data for the devices being claimed.  The example_inventory file shows how to organize device information into groups and share variables between groups:


sjc18-l12-ucs2: hostname= device_type=ucsm read_only=true

sjc18-l13-ucs1-hx: hostname= device_type=ucsm

sjc18-l14-ucs1: hostname= device_type=ucsm read_only=true

sjc18-c240m5-76: hostname= device_type=imc


sjc02-d23-ucs1: hostname= device_type=ucsm read_only=true














The example_claim.yml playbook shows how to use variable passed in from the inventory and call the script using Ansible's script module:


- hosts: ucs

  connection: local

  gather_facts: no


    # override on command line if needed

    api_params_file: intersight_api_params.json


    PYTHONPATH: "{{ playbook_dir }}"


  # default values that can be overridden in inventory

  - name: Default to no proxy settings


      proxy_host: ''

      proxy_port: 0

    when: proxy_host is not defined or proxy_port is not defined

  - name: Default access mode to allow control (read-only false)


      read_only: false

    when: read_only is not defined

  - name: Define JSON string passed to claim script


      # JSON for each host being claimed.

      # Quotes and whitespace are importantant for the JSON string passed to claim script.

      # ----------

      stash_json: ' { "hostname": "{{ hostname }}",

        "username": "{{ username }}",

        "password": "{{ password }}",

        "device_type": "{{ device_type }}",

        "proxy_host": "{{ proxy_host }}",

        "proxy_port": "{{ proxy_port }}",

        "read_only": "{{ read_only }}"


  - name: Claim devices

    script: -a "{{ api_params_file }}" -d ' [{{ stash_json }}]'

    register: result

    changed_when: '"true" in result.stdout'

CreatePlease to create content
Content for Community-Ad
July's Community Spotlight Awards