Community

VSC Provisioning and Cloning PowerShell Cmdlets

by costea Former NetApp Employee on ‎2011-06-14 06:33 AM - edited on ‎2014-09-25 01:02 PM by Community Manager

The Virtual Storage Console (VSC) Provisioning and Cloning Application Programming Interface (API) was initially released with (Rapid Cloning Utility) RCU version 2.1.  The API is exposed using Simple Object Access Protocol (SOAP).  This API can be thought of as a 'higher level' API which makes use of the NetApp Controller API (know as the Manage ONTAP SDK) and the VMware Virtual Center API (known as the VMware vSphere Web Services SDK).  Neither additional API is required for an application or script to consume the RCU API.

 

The RCU API is designed to be leveraged with the VMware vSphere Web Services SDK to offload the intricacies of storage object cloning while cloning virtual machines. To this end, the managed object reference returned by the VMware vSphere Web Services SDK is used to identify components in the vCenter Inventory. You can view this information using the Managed Object Browser on the vCenter server.

 

The documentation for the Provisioning and Cloning API is found in Appendix B of the NetApp Virtual Storage Console 2.1 for VMware vSphere Provisioning and Cloning Administration Guide.  A set of PowerShell cmdlets have been written that wrap calls into the API.  Attached below are two zip files containing the PowerShell cmdlets and some sample scripts of how to use it.

 

These cmdlets can be used in conjunction with the NetApp Data OnTap PowerShell Toolkit and the VMware vSphere PowerCLI to easily manage your Virtual Infrastructure.

 

These cmdlets are now deprecated.  To use the latest NetApp VSC PowerShell cmdlets go here: https://communities.netapp.com/thread/25368

Comments
toorr Former NetApp Employee on ‎2012-08-13 07:18 AM

Hi.. I am new to the Kamino stuff and work for NetApp Professional Services (my email address is raj.toora@netapp.com), however, I do have some experience with DOT powershell.

I have downloaded the Kamino powershell cmdlets and have managed to import the modules and connect to the vcentre

  • Import-Module Kamino
  • Connect_kamino 172.18.1.5

I am not sure how to use the CMDLETS,  for example,could you give me an example full syntax for:

  • Start-KaminoClone  

I have tried to run some of the sample scripts however, I am having issues with the options which I need to change in the script.

CloneInSingleNewDatastore.ps1 (for example)


Connect-Kamino 10.61.167.168 -Credential Administrator  =      (IP address of the VCentre)

$targetMoref = Get-KaminoManagedObjectRef MFIT1 Datacenter  = (What does the MFIT1 Datacentre mean?)

$controllerSpec = New-KaminoControllerSpec 10.61.167.51 -Credential root =  (IP address of the NetApp controller)

$cloneSourceMoref = Get-KaminoManagedObjectRef tiny VirtualMachine   = (what does the tiny mean? is this an existing VM?)

Many thanks in adance.

Name                          Category  Synopsis
----                          --------  --------
Connect-Kamino                CmdletConnect to the web service hosting the Kamino Provisioning and Cloning APIs.
Get-KaminoManagedObjectRef    CmdletGet the managed object reference (aka MORef) string for a vCenter object.
Get-KaminoVirtualMachine      CmdletGet vmSpec objects for all virtual machines that were created based on th...
Get-KaminoVmFileSpec          CmdletGet vmFileSpec objects that define a virtual machine clone source.
New-KaminoControllerSpec      CmdletConvenience cmdlet to create a controllerSpec object with the ability to ...
New-KaminoDatastore           CmdletCreate a new VMware datastore.
Remove-KaminoDatastore        CmdletDelete a VMware datastore.
Set-KaminoDatastoreSize       CmdletResize a VMware datastore.
Start-KaminoClone             CmdletStart a Kamino rapid cloning operation.
Start-KaminoRedeploy          CmdletStart a Kamino virtual machine redeploy operation.
about_Kamino                  HelpFile
costea Former NetApp Employee on ‎2012-08-13 08:06 AM

You can invoke "man Start-KaminoClone -Full" to see the full syntax.  The examples are pretty much self-documenting.  The first IP is indeed the IP of the vCenter.  MFIT1 is the datacenter name.  The second IP is the netapp controller.  And tiny is the name of the VM you want to clone from.

toorr Former NetApp Employee on ‎2012-08-15 05:38 AM

Hi

Firstly, thanks for your reply.

I have changed the parameters below  and I am now getting the error below.

Looks like an issue with the controllerSpec?

Kamino PS.jpg

# This sample code is provided AS IS, with no support or warranties of any

# kind, including but not limited to warranties of merchantability or

# fitness of any kind, expressed or implied.

#

# Copyright (c) 2011 NetApp, Inc.

# All rights reserved.

#

# This example shows how to create new virtual machines within a new datastore.

#

# The Get-KaminoManagedObjectRef cmdlet will not work in cases where you have the same name

on two different objects.

# It is safer to build your own moref strings.

#

# @author George Costea, NetApp (costea@netapp.com)

#

Connect-Kamino 172.16.1.5 -Credential Administrator

$targetMoref = Get-KaminoManagedObjectRef Training Datacenter

$controllerSpec = New-KaminoControllerSpec 172.16.1.100 -Credential root

$cloneSourceMoref = Get-KaminoManagedObjectRef w2k3vm VirtualMachine

$files = Get-KaminoVmFileSpec $cloneSourceMoref

foreach ($file in $files)

{

    # null out the moref of the datastore since we are creating a new one

    $file.destDatastoreSpec.mor = $null

   

    # configure the new datastore

    $file.destDatastoreSpec.containerName = "demo"   # aggr name

    $file.destDatastoreSpec.sizeInMB = 10240

    $file.destDatastoreSpec.sizeInMBSpecified = $true

    $file.destDatastoreSpec.thinProvision = $true

    $file.destDatastoreSpec.volAutoGrow = $true

    $file.destDatastoreSpec.volAutoGrowInc = 1024

    $file.destDatastoreSpec.volAutoGrowIncSpecified = $true

    $file.destDatastoreSpec.volAutoGrowMax = 20480

    $file.destDatastoreSpec.volAutoGrowMaxSpecified = $true

    $file.destDatastoreSpec.protocol = "NFS"

    # set the datastore name

    $file.destDatastoreSpec.datastoreNames = "apiNFSDemo"

    $file.destDatastoreSpec.numDatastores = 1

    $file.destDatastoreSpec.controller = controllerSpec;

}

$cloneSpec = New-Object com.netapp.kamino.wsapi.cloneSpec

$cloneSpec.templateMoref = $cloneSourceMoref;

$cloneSpec.containerMoref = $targetMoref;

$clones = New-Object com.netapp.kamino.wsapi.cloneSpecEntry[] 3

# clone 1

$entry = New-Object com.netapp.kamino.wsapi.cloneSpecEntry

$entry.key = "moe"

$vmSpec = New-Object com.netapp.kamino.wsapi.vmSpec

# build a MAC address

$macAddresses = New-Object com.netapp.kamino.wsapi.vmSpecEntry[] 1

$macAddress = New-Object com.netapp.kamino.wsapi.vmSpecEntry

$macAddress.key = "Network Adapter 1"

$macAddress.value = "00:50:56:81:4e:e0"

$macAddresses[0] = $macAddress

$vmSpec.macAddress = $macAddresses

$entry.value = $vmSpec

$clones[0] = $entry

#clone 2

$entry = New-Object com.netapp.kamino.wsapi.cloneSpecEntry

$entry.key = "larry"

$vmSpec = New-Object com.netapp.kamino.wsapi.vmSpec

$vmSpec.powerOn = $true

$entry.value = $vmSpec

$clones[1] = $entry

#clone 3

$entry = New-Object com.netapp.kamino.wsapi.cloneSpecEntry

$entry.key = "curly"

$vmSpec = New-Object com.netapp.kamino.wsapi.vmSpec

# build a guest customization spec

$custSpec = New-Object com.netapp.kamino.wsapi.guestCustomizationSpec

$custSpec.name = "stooges"

$vmSpec.custSpec = $custSpec

$entry.value = $vmSpec

$clones[2] = $entry

# complete building the clone spec

$cloneSpec.files = $files

$cloneSpec.clones = $clones

$taskRef = Start-KaminoClone $cloneSpec

$taskRef

costea Former NetApp Employee on ‎2012-08-15 05:56 AM

You've got a typo. 

$file.destDatastoreSpec.controller = controllerSpec;

should be changed to

$file.destDatastoreSpec.controller = $controllerSpec;

toorr Former NetApp Employee on ‎2012-08-15 06:11 AM

thanks.. the typo was actually in the original script i downloaded (CloneInSingleNewDatastore), i just corrected it.

however, I now get the error below?

NetApp rapid clone virtual machine

w2k3vm

Error

Failed to get system info. :Connection refused: connect

Administrator

VC

8/15/2012 6:06:29 AM

8/15/2012 6:06:29 AM

8/15/2012 6:06:37 AM

PS C:\Windows\System32\WindowsPowerShell\v1.0\Modules\Kamino> .\CloneInSingleNewDatastore.ps1

 

VCenterHostname    : 172.16.1.5

VCenterAddress     : 172.16.1.5

VCenterCredentials : System.Net.NetworkCredential

ServiceHostname    :

ServiceAddress     : 172.16.1.5

VCenterVersion     : 5.0.0

Task:task-224

PS C:\Windows\System32\WindowsPowerShell\v1.0\Modules\Kamino>

costea Former NetApp Employee on ‎2012-08-15 08:00 AM

You can look at the kamino.log file for more details but my guess is that you have configured ssh on your controller but didn't specify that on the $controllerSpec.

on ‎2012-10-03 04:57 AM

Hi, Is there a way to pass the password into the powershell script so that I can run this script on a schedule without intervention ? Cheers

costea Former NetApp Employee on ‎2012-10-03 05:44 AM

Sure, you can do something like this:

$password = ConvertTo-SecureString -AsPlainText -Force "password"

$creds = New-Object System.Management.Automation.PSCredential "root",$password

Connect-Kamino 10.61.167.168 -Credential $creds -Timeout 120000

on ‎2012-10-03 05:49 AM

Superb ! Thanks a million costea

on ‎2012-10-03 07:24 AM

Hi Costea,

I have another question now that I seem to have it working. Through the Vitrual Center I can specify to power on the machine and apply customisation on the redeploy. I cant see a way when performing a redeploy via powershell I can apply these same settings. Do you have any idea ? Cheers

costea Former NetApp Employee on ‎2012-10-03 09:59 AM

Just do the same setting on the clones that were done in the other script:

# build a guest customization spec

$custSpec = New-Object com.netapp.kamino.wsapi.guestCustomizationSpec

$custSpec.name = "Windows7"

# add an entry for each of the vms based on the source

$clones = New-Object com.netapp.kamino.wsapi.cloneSpecEntry[] $vms.Length

for ($i = 0; $i -LT $vms.Length; $i++)

{

   $clones[$i] = New-Object com.netapp.kamino.wsapi.cloneSpecEntry

   $vms[$i].custSpec = $custSpec   # add this line to specify the custSpec on the vmSpec.

   $clones[$i].key = $vms[$i].vmMoref

   $clones[$i].value = $vms[$i]

}

on ‎2012-10-04 04:17 AM

Hi George,

I am really sorry, but I am still struggling with this slightly. I have

managed to get the password part working fine and I have applied your

suggestions to the script, however it does not seem to be using the

customization that I want. Looking in vmware I can see that the name of the

custSpec.name should be what I have entered. (See the screen shot below

from VM)

(Embedded image moved to file: pic25996.gif)

This is my Powershell script, I have removed our specific bits and replaced

with friendly names. I am really sorry to keep asking for your help as it

almost seems like I am getting you to write what I need but I would really

appreciate your advise on this.

Import-Module kamino

$password = ConvertTo-SecureString -AsPlainText -Force "xxxxx"

$netpassword = ConvertTo-SecureString -AsPlainText -Force "xxxx"

$creds = New-Object System.Management.Automation.PSCredential "domain

\username",$password

$controllers = New-Object com.netapp.kamino.wsapi.controllerSpec[] 1

Connect-Kamino virtualcentreserver -Credential $creds -Timeout 120000

-ServiceHost IPAddresofHost

$targetMoref = Get-KaminoManagedObjectRef DCName Datacenter

$netcreds = New-Object System.Management.Automation.PSCredential

"root",$netpassword

$controllerSpec = New-KaminoControllerSpec netappfiler -Credential

$netcreds

$controllers[0] = $controllerSpec

$cloneSourceMoref = Get-KaminoManagedObjectRef vmtemplatemachinename

VirtualMachine

$vms = Get-KaminoVirtualMachine $cloneSourceMoref

#build the clone spec

$cloneSpec = New-Object com.netapp.kamino.wsapi.cloneSpec

$cloneSpec.templateMoref = $cloneSourceMoref;

  1. build a guest customization spec

$custSpec = New-Object com.netapp.kamino.wsapi.guestCustomizationSpec

$custSpec.name = "RDS-Clone"

  1. add an entry for each of the vms based on the source

$clones = New-Object com.netapp.kamino.wsapi.cloneSpecEntry[] $vms.Length

for ($i = 0; $i -LT $vms.Length; $i++)

{

   $clones[$i] = New-Object com.netapp.kamino.wsapi.cloneSpecEntry

   $vms[$i].custSpec = $custSpec   # add this line to specify the custSpec

on the vmSpec.

   $clones[$i].key = $vms[$i].vmMoref

   $clones[$i].value = $vms[$i]

}

$cloneSpec.clones = $clones

$taskRef = Start-KaminoRedeploy $cloneSpec $controllers

$taskRef

costea Former NetApp Employee on ‎2012-10-04 07:59 AM

You might want to take a look at the kamino.log file found where you installed the VSC.  That should show you the API request coming in and if something is missing.  BTW, I'm not seeing the images above so I can't comment on them.

on ‎2012-10-04 09:27 AM

Hi costea,

I have had a look in the logs and I cant see anything that gives any indication of a problem. I have deployed using the VCS snapin in the Virtual Center and done a redeploy but not specified the Customization Specification, nor to power the servers on after redeploy. When I do this it clones them, applies the customization and powers them on. Which is exactly what I want.

When I run the powershell script it powers them down, performs the flexclone and thats it.

Looking at the XML file in the log they look exactly the same other than the machine name, when I do it through the GUI the first reference to the machine name in <key> is the actual name of the server, however when I do it via powershell I see it asVirtualMachine:vm-1224456.

Other than that the information in the log looks the same for both, but no matter what I do, I am unable to get the machine to apply the customization and power on. We are using VSC 4 not sure if that makes any difference.

Any help would be really appreciated, as I would love to get this sorted. What I have seen so far is superb. Cheers.

NetApp Employee on ‎2012-10-04 01:22 PM

Based on your description of the behavior, it sure sounds like the customization spec is not being properly attached to the request spec.

So, first I'd like to establish that the request is being properly formatted.  Can you capture the SOAP request that is being sent? (there are lots of SOAP proxies available on the internet that can intercept and display what is sent to the VSC SOAP endpoint/URL).

While the commandlets are for VSC 2.1.x and this is VSC 4.0, there may be a mismatch there, but let's establish what is being sent first.

Thanks,

Brian

on ‎2012-10-05 04:52 AM

brianjm,

I think this is the information that you are after

<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><redeployVMs xmlns="http://server.kamino.netapp.com/"><arg0 xmlns=""><cloneSpec><clones><entry><key>VirtualMachine:vm-190849</key><value><custSpec><name>RDS-Clone</name><useVmName>false</useVmName></custSpec><powerOn>false</powerOn><vmMoref>VirtualMachine:vm-190849</vmMoref></value></entry><entry><key>VirtualMachine:vm-190848</key><value><custSpec><name>RDS-Clone</name><useVmName>false</useVmName></custSpec><powerOn>false</powerOn><vmMoref>VirtualMachine:vm-190848</vmMoref></value></entry></clones><templateMoref>VirtualMachine:vm-190845</templateMoref></cloneSpec><serviceUrl>https://192.168.3.xxx/sdk</serviceUrl><vcPassword>xxxxxxx</vcPassword><vcUser>xxxxxxxx</vcUser></arg0><arg1 xmlns=""><actuallyOpsMgr>false</actuallyOpsMgr><ipAddress>192.168.3.xxx</ipAddress><password>xxxxxx</password><port>0</port><ssl>false</ssl><username>xxxxxx</username></arg1></redeployVMs></soap:Body></soap:Envelope>

This is from the Kamino Log

2012-10-05 11:36:49,625 (326650364@qtp-13817227-132) DEBUG [ApiImpl] - ApiImpl: XML dump of request (this will be repeated in VmCloner.class):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<requestSpec>

    <cloneSpec>

        <clones>

            <entry>

                <key>VirtualMachine:vm-190848</key>

                <value>

                    <powerOn>false</powerOn>

                    <vmMoref>VirtualMachine:vm-190848</vmMoref>

                </value>

            </entry>

            <entry>

                <key>VirtualMachine:vm-190849</key>

                <value>

                    <powerOn>false</powerOn>

                    <vmMoref>VirtualMachine:vm-190849</vmMoref>

                </value>

            </entry>

        </clones>

        <templateMoref>VirtualMachine:vm-190845</templateMoref>

    </cloneSpec>

    <serviceUrl>https://192.168.3.xxx/sdk</serviceUrl>

    <vcUser>vmservice</vcUser>

</requestSpec>

This is the script

The only thing removed is the bit at the top that sets the user names and password to connect to the Virtual Center and Kamino (both are on different servers)

$controllers[0] = $controllerSpec

$cloneSourceMoref = Get-KaminoManagedObjectRef rdsflextemplate02 VirtualMachine

$vms = Get-KaminoVirtualMachine $cloneSourceMoref

# build the clone spec

$cloneSpec = New-Object com.netapp.kamino.wsapi.cloneSpec

$cloneSpec.templateMoref = $cloneSourceMoref

# build a guest customization spec

$custSpec = New-Object com.netapp.kamino.wsapi.guestCustomizationSpec

$custSpec.name = "RDS-Clone"

# add an entry for each of the vms based on the source

$clones = New-Object com.netapp.kamino.wsapi.cloneSpecEntry[] $vms.Length

for ($i = 0; $i -LT $vms.Length; $i++)

{

   $clones[$i] = New-Object com.netapp.kamino.wsapi.cloneSpecEntry

   $vms[$i].custSpec = $custSpec

   $clones[$i].key = $vms[$i].vmMoref

   $clones[$i].value = $vms[$i]

}

$cloneSpec.clones = $clones

$taskRef = Start-KaminoRedeploy $cloneSpec $controllers

$taskRef

NetApp Employee on ‎2012-10-08 08:03 AM

Thanks for the trace.

If you look at the request XML (dumped into the log), you'll see that there is nothing there about which guest customization spec to use.

Also, I don't see any place in your script that creates the com.netapp.kamino.wsapi.vmSpec.... and that's where the customization should go.

So, in the loop where you create the new "cloneSpecEntry", I think you'll need something like the following:

$vmSpec = New-Object com.netapp.kamino.wsapi.vmSpec

# attach the customization

$vmSpec.custSpec = $custSpec

# attach the vmSpec to the entry

$entry.value = $vmSpec

The line in your current loop:

$vms[$i].custSpec = $custSpec

is invalid, as it is trying to attach a customization spec to the list of VMs that come back from vCenter, not the list/array of VM cloning specs being sent.

You might also want to look at the script embedded by "toorr" on Aug 15 higher up in this thread.  It shows how to attach a customization spec (which was taken from the samples zip attached to the initial post that created this thread).

on ‎2012-10-10 01:09 AM

After a bit of messing around I have finally got the script working, there are a few tweaks that I will do at some point, mainly to specifiy the RAM and CPU. The script basically connects to the VC and then redeploys to all hosts based on the specified clone master (VM Template) the issue that I was having was that the script was working but in order to apply the customization spec to multiple machines you need to specify the vm name of the machine not the vmMoref. So I have added a bit into the script to convert the vmmoref to the vm name and than it all seemed to work.

Thanks to all that helped out with getting me to the solution... here is my script.

Connect-VIServer *virtualcenterserver* #Used for vmMoref to VM Name

Import-Module kamino

$password = ConvertTo-SecureString -AsPlainText -Force "*password*"

$netpassword = ConvertTo-SecureString -AsPlainText -Force "*password*"

$creds = New-Object System.Management.Automation.PSCredential "*vmusername*",$password

$controllers = New-Object com.netapp.kamino.wsapi.controllerSpec[] 1

Connect-Kamino *virtualcenterserver* -Credential $creds -Timeout 120000 -ServiceHost *ipaddress if different server*

$targetMoref = Get-KaminoManagedObjectRef *VM Datacenter Name* Datacenter

$netcreds = New-Object System.Management.Automation.PSCredential "*Netapp User Name*",$netpassword

$controllerSpec = New-KaminoControllerSpec *Netapp Filer Name* -Credential $netcreds

$controllers[0] = $controllerSpec

$cloneSourceMoref = Get-KaminoManagedObjectRef *VM Template Used to Redeploy* VirtualMachine

$vms = Get-KaminoVirtualMachine $cloneSourceMoref

$cloneSpec = New-Object com.netapp.kamino.wsapi.cloneSpec

$cloneSpec.templateMoref = $cloneSourceMoref

$clones = New-Object com.netapp.kamino.wsapi.cloneSpecEntry[] $vms.Length

for ($i = 0; $i -LT $vms.Length; $i++)

{

    $clones[$i] = New-Object com.netapp.kamino.wsapi.cloneSpecEntry

   

    #Get the VM Name from the vmMoref - needs converting from VirtualMachine:vm-id to VirtualMachine-vm-id

    $e = $vms[$i].vmMoref.Substring(18)

    $vmmorefstr = 'VirtualMachine-vm-' + $e

    $vmname = Get-VM | select name,id | where{$_.id -eq $vmmorefstr}

    $clones[$i].key = $vmname.name

   

   

    $vmSpec = New-Object com.netapp.kamino.wsapi.vmSpec

    $vmSpec.vmMoref = $vms[$i].vmMoref

   

    # build a guest customization spec

    $custSpec = New-Object com.netapp.kamino.wsapi.guestCustomizationSpec

    $custSpec.name = "*VM Customisation Specification*"

    $custSpec.useVmName = "True"

    $vmSpec.custSpec = $custSpec

    $vmSpec.powerOn = "True"

    $clones[$i].value = $vmSpec

}

$cloneSpec.clones = $clones

$taskRef = Start-KaminoRedeploy $cloneSpec $controllers

$taskRef

on ‎2012-11-21 02:27 AM

Hi,

I understand that Kamino is the PowerShell interface to the 'Provisioning and Cloning' part of the Virtual Storage Console (VSC). Is there somewhere information about any API for the Space Reclamation part? With VSC 4.1 installed it's possible to perform space reclamation by rights-clicking on a VM, I would like to automate this.

Any help would be appreciated.

NetApp Employee on ‎2012-11-26 07:19 AM

Unfortunately, space reclamation is not offered as part of the API.  It can only be accessed via the GUI.

Warning!

This NetApp Community is public and open website that is indexed by search engines such as Google. Participation in the NetApp Community is voluntary. All content posted on the NetApp Community is publicly viewable and available. This includes the rich text editor which is not encrypted for https.

In accordance to our Code of Conduct and Community Terms of Use DO NOT post or attach the following:

  • Software files (compressed or uncompressed)
  • Files that require an End User License Agreement (EULA)
  • Confidential information
  • Personal data you do not want publicly available
  • Another’s personally identifiable information
  • Copyrighted materials without the permission of the copyright owner

Files and content that do not abide by the Community Terms of Use or Code of Conduct will be removed. Continued non-compliance may result in NetApp Community account restrictions or termination.