Intersight.PowerShell - the PowerShell module for the Cisco Intersight

Cisco Intersight is a cloud operations platform that delivers intelligent visualization, optimization, and orchestration for applications and infrastructure across your hybrid environment. With Intersight, you get all of the benefits of SaaS delivery and full lifecycle management of distributed Intersight-connected servers and third-party storage across data centers, remote sites, branch offices, and edge environments. This empowers you to analyze, update, fix, and automate your environment in ways that were not possible with prior generations’ tools. As a result, your organization can achieve significant TCO savings and deliver applications faster in support of new business initiatives.

The Cisco Intersight API is a programmatic interface that uses the REST architecture to provide access to the Intersight Management Information Model. The Intersight.PowerShell cmdlets are generated based on the Cisco Intersight OpenAPI 3.x specification. The latest specification can be downloaded from here. The Cisco Intersight.PowerShell module is updated frequently to be in sync with the OpenAPI version deployed at https://intersight.com

• Intersight.PowerShell version: 1.0.11.2024101709
• C# SDK version: 1.0.11.2024101709 For more information, please visit https://intersight.com/help

Getting Started

1. Installation

   1.1. Requirements

   1.2. Install

   1.2.1 Install from PowerShell Gallery

   1.2.2 Install from GitHub

   1.2.3 Uninstall Intersight.PowerShell

2. Authentication

3. Creating an Object

   3.1. Create Organization

   3.2. Create Ntp Policy

   3.3 Initialize cmdlets

   3.4. Create Boot precision policy

4. Reading Objects

   4.1 Reading list of objects

   4.2 Read object based on specified parameter

   4.3. Reading Objects Using a Query parameter

5. Updating Objects

6. Deleting Objects

7. Generic Cmdlets

   7.1. Get-IntersightManagedObject

   7.2. New-IntersightManagedObject

   7.3 Set-IntersightManagedObject

   7.4 Remove-IntersightManagedObject

8. Patch Document using application/json-patch+json

9. Examples

   9.1. Example - Server Configuration

   9.2. Example - Firmware Upgrade

   9.3. Example - OS Install

10. Targets

    10.1. Claiming a Target

    10.2. Unclaiming a Target

    10.3. Claiming an Appliance

11. Triggering a Workflow

12. Monitoring a Workflow

13. Debugging

14. Cmdlets

15. Changelog

1. Installation

1.1. Requirements

• PowerShell 7.3.3 or later
• net6.0 SDK or later

Dependencies

Intersight.dll : Intersight C# SDK, generated using openaapi-generator

1.2. Install

The latest Intersight.PowerShell moudle can be found at,

• PowerShell gallery
• [GitHub release page] (https://github.com/CiscoDevNet/intersight-powershell/releases)

To install form PSGallery

Install-Module -Name Intersight.PowerShell

To install from the source, run the following command to build and install the PowerShell module locally:

build.ps1
Import-Module -Name '.\Intersight.PowerShell' -Verbose

1.2.3 Uninstall Intersight.PowerShell

Remove-Module -FullyQualifiedName @{ModuleName = "Intersight.PowerShell"; ModuleVersion = "1.0.11.2024101709"}

or

Remove-Module -Name Intersight.PowerShell

2. Authentication

Environment configuration is required before Intersight cmdlets can be used. The following properties need to be set,

BasePath :- connection URL of Intersight cloud or appliance, default value is https://intersight.com
ApiKeyId :- Api Key Identifier - A user can generate it by logging into intersight.com or onprem portal.
ApiKeyFilePath :- ApiKeyFilePath is the path of the secrect key file which is in pem format. (RSA key or ECDSA key)
HashAlgorithm :- Accepted values are SHA256 and SHA512
HttpSignerHeader :- requires the name of the headers used for http signing. For Intersight the minimum required headers are "(request-target)", "Host", "Date", "Digest"

To explore the other supported cmdlet parameter like KeyPassPhrase, Proxy, SignatureValidityPeriod and SkipCertificateCheck refer the cmdlet help.

Authenticate the user

Intersight.PowerShell supports only HttpSigning Auth.

$onprem = @{
    BasePath = "https://intersight.com"
    ApiKeyId = "xxxxx27564612d30dxxxxx/5f21c9d97564612d30dd575a/5f9a8b877564612xxxxxxxx"
    ApiKeyFilePath = "C:\\secretKey.txt"
    HttpSigningHeader =  @("(request-target)", "Host", "Date", "Digest")
}

PS C:\> Set-IntersightConfiguration @onprem

PS C:\> Get-IntersightConfiguration

BasePath                : https://intersight.com
ApiKeyId                : xxxxx27564612d30dxxxxx/5f21c9d97564612d30dd575a/5f9a8b877564612xxxxxxxx
ApiKeyFilePath          : C:\\secretKey.txt
ApiKeyPassPhrase        :
Proxy                   :
HashAlgorithm           : SHA256
HttpSigningHeader       : {(request-target), Host, Date, Digest}
SignatureValidityPeriod : 0

3. Creating an Object

New cmdlet is used to create a new object in Intersight. User can specify the required properties using the cmdlet parameter. For more details on parameters and their types please refer to the cmdlet help.

Initialize cmdlets help create objects of complex type locally. These can be passed as parameter to the New cmdlets.

3.1. Create an Organization

The cmdlet New-IntersightOrganizationOrganization is used to create a Organization object.

PS C:\> $newOrg = New-IntersightOrganizationOrganization -Name PSOrg
PS C:\> $newOrg

ClassId                           : OrganizationOrganization
ObjectType                        : OrganizationOrganization
Description                       :
Name                              : PSOrg
Account                           : class IamAccountRelationship {
                                      ActualInstance: class MoMoRef {
                                      ClassId: MoMoRef
                                      ObjectType: IamAccount
                                      Moid: 5f21c2527564612d30dd3c06
                                      Selector:
                                      Link: https://xxxxxxx.xxx.com/api/v1/iam/Accounts/5f21c2527564612d30dd3c06
                                      AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                                    }

                                    }

ResourceGroups                    :
AdditionalProperties              : {}
AccountMoid                       : 5f21c2527564612d30dd3c06
CreateTime                        : 23-03-2021 07:03:01
DomainGroupMoid                   : 5f21c2527564612d30dd3c07
ModTime                           : 23-03-2021 07:03:01
Moid                              : 605992a56972652d30f7a714
Owners                            : {5f21c2527564612d30dd3c06}
SharedScope                       :
Tags                              : {}
VersionContext                    :
_0ClusterReplicationNetworkPolicy :
Ancestors                         :
Parent                            :
PermissionResources               : {class MoBaseMoRelationship {
                                      ActualInstance: class MoMoRef {
                                      ClassId: MoMoRef
                                      ObjectType: OrganizationOrganization
                                      Moid: 605992a56972652d30f7a714
                                      Selector:
                                      Link:
                                    https://xxxxxxx.xxx.com/api/v1/organization/Organizations/605992a56972652d30f7a714
                                      AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                                    }

                                    }
                                    }
DisplayNames                      :

3.2. Create a Ntp policy.

The cmdlet New-IntersightNtpPolicy is used to create a NTP Policy. Organization reference is derived from $newOrg variable which was created in the previous example.

PS C:\> $ntpPolicy = New-IntersightNtpPolicy -Name "PSNtp" -Description "ntp policy for PSOrg" -NtpServers @("22.22.22.22","77.77.77.77") -Enabled $true -Timezone IndianMauritius -Organization $newOrg
PS C:\> $ntpPolicy

ClassId                           : NtpPolicy
ObjectType                        : NtpPolicy
Timezone                          : IndianMauritius
Enabled                           : True
NtpServers                        : {22.22.22.22, 77.77.77.77}
ApplianceAccount                  :
Organization                      : class OrganizationOrganizationRelationship {
                                      ActualInstance: class MoMoRef {
                                      ClassId: MoMoRef
                                      ObjectType: OrganizationOrganization
                                      Moid: 605992a56972652d30f7a714
                                      Selector:
                                      Link:
                                    https://xxxxxxx.xxx.com/api/v1/organization/Organizations/605992a56972652d30f7a714
                                      AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                                    }

                                    }

Profiles                          :
AdditionalProperties              : {}
Description                       : ntp policy for PSOrg
Name                              : PSNtp
AccountMoid                       : 5f21c2527564612d30dd3c06
CreateTime                        : 23-03-2021 07:10:58
DomainGroupMoid                   : 5f21c2527564612d30dd3c07
ModTime                           : 23-03-2021 07:10:58
Moid                              : 605994826275722d3037017f
Owners                            : {5f21c2527564612d30dd3c06}
SharedScope                       :
Tags                              : {}
VersionContext                    :
_0ClusterReplicationNetworkPolicy :
Ancestors                         :
Parent                            :
PermissionResources               : {class MoBaseMoRelationship {
                                      ActualInstance: class MoMoRef {
                                      ClassId: MoMoRef
                                      ObjectType: OrganizationOrganization
                                      Moid: 605992a56972652d30f7a714
                                      Selector:
                                      Link:
                                    https://xxxxxxx.xxx.com/api/v1/organization/Organizations/605992a56972652d30f7a714
                                      AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                                    }

                                    }
                                    }
DisplayNames                      :

3.3. Initialize Cmdlets

Initialize cmdlets are used to create complex objects locally, which can be passed to the New or Set cmdlets parameter. For example, Boot precision policy accepts list of complex typ: BootDevices. Each boot device has it's own set of properties. Initialize cmdlets are used to create the required boot device object and these are passed to New-IntersightBootPrecisionPolicy cmdlet.

PS C:\>  $uefiBoot = Initialize-IntersightBootUefiShell -Name uefi -Enabled $true
PS C:\> $uefiBoot

AdditionalProperties : {}
ClassId              : 0
ObjectType           : 0
Enabled              : True
Name                 : uefi

# Above cmdlet creates the BootUefiShell object locally which can be passed to BootDevices parameter of New-IntersightBootPrecisionPolicy.

PS C:\> $vmediaBoot =  Initialize-IntersightBootVirtualMedia -Enabled $true -Subtype CimcMappedHdd -Name "vMedia"
PS C:\> $vmediaBoot

ClassId              : BootVirtualMedia
ObjectType           : BootVirtualMedia
Subtype              : CimcMappedHdd
AdditionalProperties : {}
Enabled              : True
Name                 : vMedia

# Above cmdlet creates the BootVirtualMedia object locally which can be passed to BootDevices parameter of New-IntersightBootPrecisionPolicy.

PS C:\> $bootUsb = Initialize-IntersightBootUsb -Name usb -Subtype UsbFdd -Enabled $true
PS C:\> $bootUsb

ClassId              : BootUsb
ObjectType           : BootUsb
Subtype              : UsbFdd
AdditionalProperties : {}
Enabled              : True
Name                 : usb

$org = Get-IntersightOrganizationOrganization -Name default #here we get the existing default org. One can create new Organization using New-IntersightOrganizationOrganization cmdlets.
$vmediaBoot = Initialize-IntersightBootVirtualMedia -Enabled $true -Subtype CimcMappedHdd -Name "vMedia"
$usbBoot = Initialize-IntersightBootUsb -Name usb -Subtype UsbFdd -Enabled $true
$uefiBoot = Initialize-IntersightBootUefiShell -Name uefi -Enabled $true
$BootPrecisionPolicy = New-IntersightBootPrecisionPolicy -Name testBootPrecision -BootDevices @($vmediaBoot, $usbBoot, $uefiBoot) -Organization $org 

4. Reading Objects

Get cmdlets are used to read objects from Intersight. For example, Get-IntersightNtpPolicy fetches NTP policies. The cmdlets follow Get-Intersight naming pattern.

4.1. Reading list of objects

When the Get cmdlet is used without any parameter, it returns list of objects. The return type is a collection, even when there is a single object.

PS C:\> $list = Get-IntersightNtpPolicy
PS C:\> $list.Count
10

4.2. Read object based on specified parameter

Filters can be specified on Get Cmdlets to narrow down the results.

PS C:\> $getNtp = Get-IntersightNtpPolicy -Name PSNtp
PS C:\> $getNtp

ClassId                           : NtpPolicy
ObjectType                        : NtpPolicy
Timezone                          : IndianMauritius
Enabled                           : True
NtpServers                        : {22.22.22.22, 77.77.77.77}
ApplianceAccount                  :
Organization                      : class OrganizationOrganizationRelationship {
                                      ActualInstance: class MoMoRef {
                                      ClassId: MoMoRef
                                      ObjectType: OrganizationOrganization
                                      Moid: 605992a56972652d30f7a714
                                      Selector:
                                      Link:
                                    https://xxxxxxx.xxx.com/api/v1/organization/Organizations/605992a56972652d30f7a714
                                      AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                                    }

                                    }

Profiles                          : {}
AdditionalProperties              : {}
Description                       : ntp policy for PSOrg
Name                              : PSNtp
AccountMoid                       : 5f21c2527564612d30dd3c06
CreateTime                        : 23-03-2021 07:10:58
DomainGroupMoid                   : 5f21c2527564612d30dd3c07
ModTime                           : 23-03-2021 07:10:58
Moid                              : 605994826275722d3037017f
Owners                            : {5f21c2527564612d30dd3c06}
SharedScope                       :
Tags                              : {}
VersionContext                    :
_0ClusterReplicationNetworkPolicy :
Ancestors                         : {}
Parent                            :
PermissionResources               : {class MoBaseMoRelationship {
                                      ActualInstance: class MoMoRef {
                                      ClassId: MoMoRef
                                      ObjectType: OrganizationOrganization
                                      Moid: 605992a56972652d30f7a714
                                      Selector:
                                      Link:
                                    https://xxxxxxx.xxx.com/api/v1/organization/Organizations/605992a56972652d30f7a714
                                      AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                                    }

                                    }
                                    }
DisplayNames                      :

4.3. Reading Objects Using a Query parameter

Get cmdlets accepts all the query parameter which specified in the OpenAPI document.

Note := The cmdlet return type is different when the query parameter is used with Get cmdlets.

PS C:\> $result = Get-IntersightKvmPolicy -Count $true

Count AdditionalProperties ObjectType
----- -------------------- ----------
  404 {}                   mo.DocumentCount

PS C:\> $result = Get-IntersightSolPolicy -InlineCount allpages
PS C:\> $result

Count                : 461
Results              : {....}
AdditionalProperties : {}
ObjectType           : sol.Policy.List

PS C:\> $Result = Get-IntersightSolPolicy -Filter `Name eq TestSOl`
PS C:\> $Result

Count                : 0
Results              : {class SolPolicy {
                         class PolicyAbstractPolicy {
                           class MoBaseMo {
                             ClassId: 0
                             ObjectType: 0
                             AccountMoid: 5a640b4b31776876789ac747
                             CreateTime: 22-01-2018 06:36:05
                             DomainGroupMoid: 5aecd93c6a7a6e7277f7131e
                             ModTime: 02-07-2021 08:03:07
                             Moid: 5a6586556c64673268778839
                             Owners: System.Collections.Generic.List`1[System.String]
                             SharedScope:
                             Tags: System.Collections.Generic.List`1[Intersight.Model.MoTag]
                             VersionContext:
                             Ancestors: System.Collections.Generic.List`1[Intersight.Model.MoBaseMoRelationship]
                             Parent:
                             PermissionResources: System.Collections.Generic.List`1[Intersight.Model.MoBaseMoRelationship]
                             DisplayNames:
                             AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                           }

                           ClassId: 0
                           ObjectType: 0
                           Description:
                           Name: SOL_Enable_Jatin
                           AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                         }

                         ClassId: SolPolicy
                         ObjectType: SolPolicy
                         BaudRate: NUMBER_115200
                         ComPort: Com0
                         Enabled: True
                         SshPort: 2373
                         Organization: class OrganizationOrganizationRelationship {
                         ActualInstance: class MoMoRef {
                         ClassId: MoMoRef
                         ObjectType: OrganizationOrganization
                         Moid: 5dd020d36972652d31e238b5
                         Selector:
                         Link: https://staging.starshipcloud.com/api/v1/organization/Organizations/5dd020d36972652d31e238b5
                         AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                       }

                       }

                         Profiles: System.Collections.Generic.List`1[Intersight.Model.PolicyAbstractConfigProfileRelationship]
                         AdditionalProperties: System.Collections.Generic.Dictionary`2[System.String,System.Object]
                       }
                       }
AdditionalProperties : {}
ObjectType           : sol.Policy.List

5. Updating Objects

Set cmdlet are used to update objects.

The below updates the Description of the specified NTP Policy.

PS C:\> Get-IntersightNtpPolicy -Name TestNtp | Set-IntersightNtpPolicy -Description "The is demo update"

The following snippet adds the additional Boot devices to an existing boot precision policy.

$boot = Get-IntersightBootPrecisionPolicy -Name BootPrecesion_1

$bootDevices = $boot.BootDevices
#Create boot policy with Iscsci and localCdd device.
$iscsi = Initialize-IntersightBootIscsi -Name "iscsi" -Slot "MLOM" 
$bootDevices += $iscsi

$localcdd = Initialize-IntersightBootLocalCdd -Name "cdd" 
$bootDevices += $localCdd

$boot | Set-IntersightBootPrecisionPolicy -BootDevices $bootDevices

6. Deleting Objects

Remove cmdlets are used to delete objects. Delete Cmdlets returns null on a successful deletion. Cmdlet pattern Remove-Intersight

PS C:\> Get-IntersightKvmPolicy -Name TestKvm | Remove-IntersightKvmPolicy

PS C:\> Remove-IntersightNtpPolicy -Moid xxxxxxxxxxxxxxxxxxxxxxxx 

7. Generic Cmdlets

Generic cmdlets provide an alternate way of performing the Create/Update/Get and delete operation on any MO. This cmdlet is also useful when the specific cmdlet is not available. This cmdlet accepts the json input or hashtable. Generic cmdlets also accept pipeline inputs from the non-generic cmdlets.

7.1. Get-IntersightManagedObject

Get-IntersightManagedObject cmdlet fetchs the object list based on the specified ObjectType. It also supports query parameter similar to the specific Get cmdlets.

PS C:\> $result = Get-IntersightManagedObject -ObjectType server.Profile

# Above cmdlet returns the list of server profile MO in json format.

PS C:\> $result = Get-IntersightManagedObject -ObjectType server.Profile -Name TestSP

# Above cmdlet fetch the server profile named "TestSP", $result contains single MO in json format.

PS C:\> $result = Get-IntersightManagedObject -ObjectType -InlineCount allpages

# Above cmdlet gets the Count, Results and ObjectType in json format.

PS C:\> $Obj = $result | ConvertFrom-Json

# $result  can be piped to ConvertFrom-Json to get the PSObjet.

7.2. New-IntersightManagedObject

New-IntersightManagedObject creates objects of the specified ObjectType. It also support the json payload using the parameter -JsonRequestBody to create a new object.

PS C:\> $result = New-IntersightManagedObject -ObjectType ntp.Policy -AdditionProperties @{ Name = "testNtp", NtpServers = @("12.12.12.12"), Organization = @{ Moid = "xxxxxxxxxxxx", ClassId = "mo.MoRef", ObjectType = "organization.Organization"  } }

# Above cmdlet creates the MO ntp policy.

PS C:\> $jsonPayload = `{
  "ObjectType" : "ntp.Policy",
  "Description": "ntp policy created using generic cmdlet.",
  "NtpServers": ["11.11.11.11","33.33.33.33"],
  "Organization": {
    "Moid" : "xxxxxxxxxxxxxx",
    "ObjectType": "organization.Organization"
    "ClassId":"mo.MoRef"
  }
}`

PS C:\> $result = New-IntersightManagedObject -JsonRequestBody $jsonPayload

# Above cmdlet creates the ntp.Policy object using a json payload.

7.3. Set-IntersightManagedObject

Set-IntersightManagedObject updates an object with specified ObjectType and Moid. It also support the json payload using the parameter -JsonRequestBody.

PS C:\> $result = Set-IntersightManagedObject -ObjectType ntp.Policy -Moid xxxxxxxxxxx -AdditionProperties @{ NtpServers = @("12.12.12.12") }

# Above cmdlet sets the NtpServers of the specified ntp.Policy object.

PS C:\> $jsonPayload = `{
  "ObjectType" : "ntp.Policy",
  "Moid": "xxxxxxxxxxxxxxxxx",
  "Description": "ntp policy created using generic cmdlet.",
  "NtpServers": ["11.11.11.11","33.33.33.33"]
}`

PS C:\> $result = Set-IntersightManagedObject -JsonRequestBody $jsonPayload

# Above cmdlet update the ntp.Policy using a json payload.

7.4. Remove-IntersightManagedObject

Remove-IntersightManagedObject deletes the object specified by ObjectType and Moid. It also supports pipeline input from a non-generic cmdlet.

PS C:\> Remove-IntersightManagedObject -ObjectType ntp.Policy -Moid xxxxxxxxxxxxxxx

# Above cmdlet deletes the NTP policy.

PS C:\> Get-IntersightNtpPolicy -Name TestSP | Remove-IntersightManagedObject

# Above cmdlet deletes the NTP policy which was recevied from pipeline using Get-IntersightNtpPolicy.

8. Patch document using application/josn-patch+json content type

Invoke-IntersightPatchDocument cmdlet supports content type application/json-patch+json. It accepts the payload as an json or list of PatchDocument objects. To create the PatchDocument object user can use the cmdlet Initialize-IntersightPatchDocument. For more details refer the cmdlet help.

The below snippet is used to patch the object using Invoke-IntersightPatchDocument,

Initialize-IntersightPatchDocument -Op Add -Path /NtpServer/- -Value "11.11.11.11"
Get-IntersightNtpPolicy -Name TestNtp| Invoke-IntersightPatchDocument -PatchDocument @($ntpServers)

# Above snippet appends the "11.11.11.11" to the NtpServers

$Tags = `[
  { "op": "add",  "path": "/Tags/-", "value": {"Key": "Department", "Value": "123456"} }
]`
Get-IntersightNtpPolicy -Name TestNtp| Invoke-IntersightPatchDocument -JsonPatchDocument $Tags

# Above snippet adds a new tag to the Ntp.Policy

9. Examples

9.1. Example - Server Configuration

Refer to Server Configuration

9.2. Example - Firmware Upgrade

Refer to Direct Firmware Upgrade

Refer to Network Firmware Upgrade

9.3. Example - OS Install

Refer to OS Install

10. Targets

10.1. Claiming a Target

10.2. Unclaiming a Target

10.3. Claiming an Appliance

11. Triggering a Workflow

12. Monitoring a Workflow

13. Debugging

14. Changelog

For changelog refer to CHANGELOG.md

15. Cmdlets

Please visit gettingStarted.md for Intersight Auth configuration and cmdlet usage.

Documentation for Cmdlets

All URIs are relative to **