Cisco Intersight Automated Target Claim and API Usage
This document provides an overview of automated UCS and HyperFlex target (device) claim using the Cisco Intersight API and Python SDK. See the Intersight Python Package Overview for more information on the Intersight Python SDK and how to use API keys for automation with Python. For general information on Intersight, visit Cisco Intersight - Cisco
Intersight Python SDK
- Intersight's Python SDK is hosted on GitHub at https://github.com/CiscoDevNet/intersight-python. The GitHub pages have install and usage instructions including example scripts. Requirements and installation instructions for the Python SDK are summarized as follows:
Requirements
Installation using pip
- Verify that you only have one Intersight SDK active (older Intersight SDKs may conflict). "intersight" is the correct package name, and you can check installed packages with pip:
$ pip list
Package Version
------------------ ----------
<snip>
intersight 1.0.9.4437
Intersight-OpenAPI 1.0.9.3181
- The above example also shows an older Intersight-OpenAPI package installed. You will need to pip uninstall any older Intersight-OpenAPI packages to avoid conflicts
- pip uninstall Intersight-OpenAPI
Python Target Claim and other Examples
- The https://github.com/CiscoDevNet/intersight-python-utils repository has examples using the Python SDK including a config_targets subdirectory with automated target claim examples. After installing the Intersight Python SDK, you can clone the intersight-python-utils repository:
git clone https://github.com/CiscoDevNet/intersight-python-utils.git
- Go to the config_targets subdirectory in the repo
cd intersight-python-utils/config_targets
- Setup API credentials. Environment variables can be set with API key and private key information:
export INTERSIGHT_API_PRIVATE_KEY=/Users/guest/Downloads/v3_SecretKey.txt
export INTERSIGHT_API_KEY_ID=596cc...
- Copy and edit example_targets.json with information on your targets. A list of targets can be provided in the .json file:
[
{
"device_type": "imc",
"hostname": "172.28.225.122",
"password": "…",
"proxy_host": "proxy-wsa.esl.cisco.com",
"proxy_port": 80,
"username": "admin",
"read_only": false
}
]
(proxy_ fields are only needed if your devices are behind a proxy)
- Run the claim_target.py script from the config_targets subdirectory and provide your target config file:
python claim_target.py -t sjc07_devices.json
Data Organization with Ansible
While not required for using the claim_target.py script, Ansible provides a simple way to use the claim_target.py 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:
[sjc07]
172.28.225.122 device_type=imc
172.28.225.20 device_type=ucs
[sjc07:vars]
password=...
[behind_proxy:children]
sjc07
[behind_proxy:vars]
proxy_host=proxy-wsa.esl.cisco.com
proxy_port=80
[all:children]
sjc07
[all:vars]
username=admin
The example_claim.yml playbook shows how to use variable passed in from the inventory and call the claim_target.py script using Ansible's script module:
---
- hosts: all
connection: local
gather_facts: false
vars:
# override on command line if needed
target_hostname: "{{ inventory_hostname }}"
target_username: "{{ username | default('admin') }}"
target_password: "{{ password }}"
platform_type: "{{ device_type | default('ucs') }}"
target_proxy_host: "{{ proxy_host | default('') }}"
target_proxy_port: "{{ proxy_port | default(0) }}"
target_read_only: "{{ read_only | default(false) }}"
environment:
PYTHONPATH: "{{ playbook_dir }}"
tasks:
- name: Define JSON string passed to claim script
set_fact:
# JSON for each host being claimed.
# Quotes and whitespace are importantant for the JSON string passed to claim script.
# ----------
stash_json: ' { "hostname": "{{ target_hostname }}",
"username": "{{ target_username }}",
"password": "{{ target_password }}",
"device_type": "{{ platform_type }}",
"proxy_host": "{{ target_proxy_host }}",
"proxy_port": "{{ target_proxy_port }}",
"read_only": "{{ target_read_only }}"
}'
- name: Claim targets
script: /usr/bin/env python claim_target.py -t ' [{{ stash_json }}]'
register: result
changed_when: '"true" in result.stdout'
Below is an example using Ansible to allow for target claim run in parallel.
- Copy and edit the example_inventory for your target systems. Target local management IPs are used as the inventory_hostname in example_inventory and local management credentials also must be provided.
- Run the example_claim.yml playbook to claim targets in Intersight. Note that the playbook should be run from the config_targets subdirectory since the script will use the credentials module in the parent (../) directory.
$ pwd
/Users/dsoper/Documents/intersight-python-utils/config_targets
$ ansible-playbook -i tme_inventory example_claim.yml
PLAY [all] ******************************************************************************************************************************************************************************
TASK [Define JSON string passed to claim script] ****************************************************************************************************************************************
ok: [172.28.225.122]
ok: [172.28.225.20]
TASK [Claim targets] ********************************************************************************************************************************************************************
ok: [172.28.225.20]
...
