Tag Archives: powershell

Create a vRA Tenant and set Directory and Administrator Configuration with PowervRA

One of the reasons behind creating PowervRA was as a consultant I often have the need to quickly spin up vRA Tenants and / or components within those Tenants to facilitate development or testing work of other things I am automating. PowervRA contains three functions, which when joined together would make a basic vRA Tenant available for use: New-vRATenant, New-vRATenantDirectory and Add-vRAPrincipalToTenantRole.

The following code example demonstrates how to use these in conjunction with each other to make a vRA Tenant (make sure to first of all have generated an API token with Connect-vRAServer with an account that has permission to create a vRA Tenant):

Note that since New-vRATenantDirectory has a lot of parameters, I have taken advantage of the ability to instead provide the necessary JSON text directly to it.

The result is a fresh vRA Tenant with a Directory configured and admin accounts assigned to both the Tenant Admins and Infrastructure Admins roles:

CreateTenantPowervRA02

 

CreateTenantPowervRA01

Find the vRO Workflow ID for an Advanced Service Blueprint with PowervRA

A colleague asked me the other day about how it might be possible to find out which vRO workflow was mapped to an Advanced Service Blueprint (or XaaS Blueprint) in vRA. If you look in the vRA GUI after a Service Blueprint has been created you can’t see which vRO workflow is mapped.

During the creation of the Service Blueprint there is a Workflow tab to select the vRO Workflow:

ServiceBlueprintPowervRA01

 

However, once it has been created, there is no longer a Workflow tab, so you can’t see which vRO workflow is used:
ServiceBlueprintPowervRA02

By using PowervRA though we find this information. The object returned by Get-vRAServiceBlueprint contains a WorkflowId property:

ServiceBlueprintPowervRA03

We can now take that WorkflowId and find the corresponding workflow in vRO. Unless you have memorised all of the workflow IDs then you can issue a REST request to vRO to find out more. The following example uses PowerShell to query the vRO REST API for the WorkflowID above (note that we have to deal with self-signed certificates):

If we look at the data stored in the Workflows variable, we can see the name of the workflow in vRO (OK in this example it’s the same name as the Service Blueprint, but it might well not be in another example):

ServiceBlueprintPowervRA04

Also, if you look at $Workflows.relations.link you will see the first result shows the path in vRO to track down the workflow:ServiceBlueprintPowervRA05

i.e., it can be found in the top-level folder named Test:

 

ServiceBlueprintPowervRA06

Automate vRealize Automation with PowerShell: Introducing PowervRA

While putting together the PowerCLI book 2nd Edition we initially included in the proposed Table of Contents a chapter on vRealize Automation. However, it was fairly apparent that at that time (early 2015) there wasn’t a lot which could be done to fill out the chapter with good content. Firstly, most of the relevant content would be included in the vRO chapter, i.e. use vRA to call a vRO workflow to run PowerShell scripts. Secondly, automating elements within vRA 6.x could be done in part via the REST API, but a) there was a roughly 50 / 50 split between what was in the REST API vs Windows IaaS and b) I didn’t really have the time to make both a PowerShell toolkit for vRA and write a book about PowerCLI.

So we shelved that chapter and I put the thought to the back of my mind that I would revisit the idea when vRA 7 came out and the likelihood of greater coverage in the vRA REST API. At the start  of 2016 this topic came up in a conversation with Xtravirt colleague Craig Gumbley who it turned out had the same idea for making a PowerShell vRA toolkit. So we decided to combine our efforts to produce a PowerShell toolkit for vRA for both our own use as consultants and also to share with the community; consequently the project PowervRA was born.

Initial Release

For the initial release we have 60 functions available covering a sizeable chunk of the vRA 7 REST API. Compatibility is currently as follows:

vRA: version 7.0 – some of the functions may work with version 6.2.x, but we haven’t tested them (yet). Also, they have not been tested with 7.0.1.

PowerShell: version 4 is required.  We haven’t tested yet with version 5, although we wouldn’t expect significant issues.

You can get it from Github  or the PowerShell Gallery

We have provided an install script on Github if you are using PowerShell v4. If you have v5 you can get it from the PowerShell Gallery with:

Getting Started

Get yourself a copy of the module via one of the above methods or simply downloading the zip, unblocking the file and unzipping,  then copying it to somewhere in your $env:PSModulePath.

PowervRA01

PowervRA02

Import the module first:

You can observe the functions contained in the module with the following command:

Before running any of the functions to do anything within vRA, you will first of all need to make a connection to the vRA appliance. If you are using self signed certificates, ensure that you use the IgnoreCertRequirements parameter. :

You’ll receive a response, which most importantly contains an authentication token. This response is stored automatically in a Global variable: $vRAConnection. Values in this variable will be reused when using functions in the module, which basically means you don’t need to get a new authentication token each time, nor have to specify it with a function – it’s done for you.

Each of the functions has help built-in, alternatively you can visit this site http://powervra.readthedocs.org

Example Use Case: Create a vRA Tenant

Having made a connection to the appliance, it’s now time to start using some of the functions. To create a Tenant in vRA we need to have made a connection to vRA with an account that has permissions to do so in the default tenant (typically [email protected]) and then it is as simple as the following:

PowervRA03

PowervRA04

If you look through the rest of the functions, you may notice that a lot of them contain a JSON parameter. So if you know the JSON required for the REST API request or are working with a system that produces it as an output, you can do something like the following:

The Future

VMware may put out something official at some point (I have no inside info on that, it could be weeks, months, years away or not even planned right now). Until that happens Craig and I have various things planned including greater coverage of the API, dealing with any feedback from this release and looking at automating some of our own testing so that we can more easily figure out which vRA versions are supported.

In the meantime, fill your boots and if you want to help us, feel free to get involved via the Develop branch on GitHub.

 

PowerCLI Book 2nd Edition is Now Available!

…..well in Kindle format anyway :-) The paperback version will be available on 11th January in the US and 12th January in the UK and according to the publisher, apparently in book shops from the 19th January. Seriously, if you actually see one in a book shop then please send me a photo, since I’ve not seen that happen outside of a VMworld.

 

9781118925119.pdf

With my fellow authors, Luc Dekens, Glenn Sizemore, Brian Graf, Andrew Sullivan and Matt Boren, we spent the best part of 2015 putting this book together. The 1st edition was written in 2010 and published in 2011; since then the VMware virtualisation landscape has changed significantly from pretty much VMware vSphere infrastructure and P2V projects and maybe some desktop work with VMware View to a wide variety of Management, Desktop, Application, Infrastructure and Cloud products.

Given this expansion of products and the fact the we all buy tech books ourselves and want value for money from them, we didn’t want to just ship an updated version to cover what was in the 1st Edition and make sure it worked with the latest versions of vSphere, PowerCLI and PowerShell. So as well as updating every chapter to make sure it worked with vSphere 6, PowerCLI 6 and PowerShell 4, and adding or replacing content and code to make sure it was still relevant (for instance the Distributed Switch is now covered out of the box, previously we contributed our own functions), we had the foolish excellent idea to add a number of additional chapters covering things such as:

  • vCloud Director
  • vCloud Air
  • vRealize Orchestrator
  • Site Recovery Manager
  • PowerActions
  • and an introduction to DevOps topics

Additionally the original Storage and Network chapter was split into two and content on new technologies VSAN and NSX added appropriately. To be honest each of VSAN and NSX could probably have their own chapters…maybe next time 😉

This took the page count to 984, around almost 200 pages more than the 1st edition, which is almost the size on its own of some tech books. Unfortunately, this partly led to the book taking longer than it should have to complete and there were still areas that we would have liked to include, but had to make some tough decisions not to or it would never have seen the light of day. As a wise man often says….

JeffreySnover2

While there is some introductory content in some of the chapters, this is not a book that typically runs you through how to use each of the PowerCLI cmdlets in their relevant areas, rather this is a book that goes beyond what ships out of the box and into areas where you will need to do some of the hard work yourself.  We had some negative feedback that the 1st edition was not better in introductory areas and may well do so again this time; there are other great PowerCLI books out there now which will do a better job for beginners. So imagine the front cover has Deepdive stamped across it and that will give you a better feel for what to expect.

Personally I feel I made a way better contribution to this book than the previous one for various reasons:

  • I was involved from the beginning, rather than parachuting in halfway through to try and get the book out of the door.
  • Consequently I was able to think about and plan for the content of the chapters I was responsible for, rather than just trying to make the deadline for each chapter.
  • Being used to the publisher’s Word template and what was required in them. There are so many rules about fonts, spacing and expectations around how the chapter needs to be laid out, that you seem to be just expected to know and first time round caused a lot of pain and time wasted.
  • A supportive employer, Xtravirt, who were interested in what I was doing, rather than one who previously was not.
  • A big thank you to our Technical Editor, Matt Boren, who left no stone unturned in making sure my code was not only accurate, but also some outstanding suggestions to help me improve. Some of which I have taken forward for everything PowerShell based that I write now. In fact he liked the experience so much, he even got roped into contributing some of the book content himself.
  • I actually had a reasonable idea about the technologies involved……;-)

 

Last time round I guessed how much time I spent on my contribution. Being curious, I decided to track it this time. It’s also something I get asked about now and again by people considering writing a tech book, so now I can refer them to some data 😉

Originally I was going to track the data by week, but since it went on so long it ended up being by month. I’m not sure if writing a book with code samples requires more or less effort than a tech book without them. On the one hand you almost have to produce double the content; explanatory written text and create code to make stuff happen. On the other hand at least the code uses up some pages when printed in the book :-)

BookHours

In total I spent 330.5 hours (that extra 0.5 was crucial) of my own time on the effort for this book between Jan and Nov 2015, and remember there were 5 other authors. So if you are thinking about getting involved in a project like this then consider carefully whether you are able to commit to the level of time you may have to give up for it. I’m not sure how representative this is for authors of other tech books, but I never talked to one who didn’t say something like “you have no idea how much effort it takes”. Similar to last time, I pretty much worked on it most evenings Mon – Thu and stayed away from it over the weekend so that it did not impact my family life too much. (Although my children are now 5 years older and consequently don’t go to bed so early – which meant starting later and finishing too late regularly) It did mean I didn’t see my friends much during weekday evenings, which is when I tend to catch up with them, for about 6 months, but something has to give. I think my blog and podcast content suffered a fair bit too.

You’ll see that most of the original effort was in the early months either producing content for new chapters, or updating content for existing ones. I was actually originally expecting to be pretty much done by April, but for various reasons I took on a bit more than originally planned and April – June was spent producing more content and some early feedback reviews. August – November was pretty much taken up with reviews.

Reviews are something which I think vary from publisher to publisher, but for Wiley it pretty much follows this:

 

Author Review

If you can recognise your original text after it has been through all that process, then well done :-)

So at least three responses required per chapter, multiply that by the number of chapters you commit to and then try finding time to write new chapters and respond to reviews both on similar deadlines. Pro tip: get your new content out of the way early on so you can do the reviews in peace –  see Jan / Feb in the chart 😉

With all that effort though, it is a personally (not financially) rewarding experience. I think both times I’ve said “Never again!” too many times, but I suspect it may happen one day. I’m confident that if it’s something you are interested in and you buy a copy that you will find it useful. I genuinely would happily buy a copy with my own money for the content I have seen the other guys produce for it.

Final comment: Writing in a foreign language also brings some difficulties. Having your own English ‘corrected’ to the US version requires a fair amount of patience. Not necessarily spelling differences, but phrases that are commonly understood this side of the Atlantic, but not the other. I’ll just leave this here……

Update 03/02/2016: Due to some issues mentioned in the comments around downloading the sample files, I have attached (most of) them here:

 

PowerShell Quick Tip: Testing JSON Syntax

I’ve been working a lot with JSON files recently and quite regularly I need to update their content for testing of code changes. While editing the files I want to make sure I don’t introduce an error by making a syntax error in the JSON file. I’ve been using a quick way in PowerShell to test the JSON is clean and if not, to point me at the line in the file where there is a problem.

Take the following example JSON:


{"people": [
{
"name": "John Smith",
"city": "London",
"country": "United Kingdom",
"age": 27
},
{
"name": "George Burns",
"city": "New York",
"country": "USA",
"age": 32
}
] }

I can check this in PowerShell by creating a Here-String of the JSON, then using the ConvertFrom-JSON cmdlet.


$text = @"
{"people": [
{
"name": "John Smith",
"city": "London",
"country": "United Kingdom",
"age": 27
},
{
"name": "George Burns",
"city": "New York",
"country": "USA",
"age": 32
}
] }
"@

$json = $text | ConvertFrom-Json

If there are no issues then I get no errors back and additionally can examine the $json variable to check the contents:


$json.people

JSON01

However, if there is a syntax error in the JSON text then I will get something like this:

JSON02

This line:

ConvertFrom-Json : Invalid object passed in, ‘:’ or ‘}’ expected. (88): {“people”: [

gives us a number, 88, of the character in the string where there is a problem. To head straight to the problem area use:


$text.substring(88)

This will show us text after the error:

JSON03

and if we look at the text I gave I missed out a ” at the end of “city”: “London, 


{"people": [
{
"name": "John Smith",
"city": "London,
"country": "United Kingdom",
"age": 27
},
{
"name": "George Burns",
"city": "New York",
"country": "USA",
"age": 32
}
] }

 

Onyx for the vSphere Web Client

The original Project Onyx (also here) was a VMware Fling which intercepted calls between the C# vSphere client and vCenter and could translate things you did in the GUI client to code in your choice of languages; SOAP, C#, PowerCLI, and JavaScript. This was really useful if say a thing you needed to do was not yet covered by a PowerCLI cmdlet, or you wanted to try and make it faster by using Get-View, or you didn’t know how to code it in JavaScript for vRO.

An issue arose however with the release of the vSphere Web Client, since Project Onyx did not support that method of intercepting calls. When VMware started moving new functionality only into the Web Client, that meant you could not use Project Onyx to figure out the code for those new features.

Enter a new VMware Fling – Onyx for the vSphere Web Client!

Some smart guys have now brought this same functionality to the vSphere Web Client. Let’s take a look at an example of how it works.

First of all follow the instructions on the Fling site to get it installed. Currently it supports vCenter 6.0. Note the warning about only using this Fling in your test environment (that’s where you write and test all of your code anyway right? 😉 )
WARNING: This fling replaces core Web Client files and may cause issues with stability and
patching of future versions of the web client, please only continue with this installation if you are
using a test or dev environment.

Once installed and the vSphere Web Client service has restarted, you will see a new menu item for Onyx.

Onyx01

Currently there is only PowerCLI.NET available as a code output choice. I’m hoping that since it is a drop down menu, there are more to come. I’ve already put in a Feature Request for JavaScript for handy use with vRO 😉

Onyx02

You can either Start and Stop recording from this area or very handily they have added the same buttons in the top right hand corner so that you can Start and Stop recording from anywhere in the Web Client.

Onyx03

So start the recording and navigate to the thing that you want to do. For this example we’ll turn on HA for a cluster.

Onyx03b

Once complete, stop the recording.

Onyx04

Now head back to the Onyx section of the Web Client and observe the code required to make that change.

Onyx05


$spec = New-Object VMware.Vim.ClusterConfigSpecEx
$spec.dasConfig = New-Object VMware.Vim.ClusterDasConfigInfo
$spec.dasConfig.vmComponentProtecting = 'disabled'
$spec.dasConfig.enabled = $true
$spec.dasConfig.admissionControlEnabled = $true
$spec.dasConfig.vmMonitoring = 'vmMonitoringDisabled'
$spec.dasConfig.hostMonitoring = 'enabled'
$spec.dasConfig.HBDatastoreCandidatePolicy = 'allFeasibleDsWithUserPreference'
$spec.dasConfig.admissionControlPolicy = New-Object VMware.Vim.ClusterFailoverLevelAdmissionControlPolicy
$spec.dasConfig.admissionControlPolicy.failoverLevel = 1
$spec.dasConfig.defaultVmSettings = New-Object VMware.Vim.ClusterDasVmSettings
$spec.dasConfig.defaultVmSettings.vmComponentProtectionSettings = New-Object VMware.Vim.ClusterVmComponentProtectionSettings
$spec.dasConfig.defaultVmSettings.vmComponentProtectionSettings.vmReactionOnAPDCleared = 'none'
$spec.dasConfig.defaultVmSettings.vmComponentProtectionSettings.enableAPDTimeoutForHosts = $true
$spec.dasConfig.defaultVmSettings.vmComponentProtectionSettings.vmStorageProtectionForAPD = 'disabled'
$spec.dasConfig.defaultVmSettings.vmComponentProtectionSettings.vmTerminateDelayForAPDSec = 180
$spec.dasConfig.defaultVmSettings.vmComponentProtectionSettings.vmStorageProtectionForPDL = 'disabled'
$spec.dasConfig.defaultVmSettings.vmToolsMonitoringSettings = New-Object VMware.Vim.ClusterVmToolsMonitoringSettings
$spec.dasConfig.defaultVmSettings.vmToolsMonitoringSettings.failureInterval = 30
$spec.dasConfig.defaultVmSettings.vmToolsMonitoringSettings.maxFailures = 3
$spec.dasConfig.defaultVmSettings.vmToolsMonitoringSettings.maxFailureWindow = 3600
$spec.dasConfig.defaultVmSettings.vmToolsMonitoringSettings.minUpTime = 120
$spec.dasConfig.defaultVmSettings.restartPriority = 'medium'
$spec.dasConfig.defaultVmSettings.isolationResponse = 'none'
$spec.dasConfig.option = New-Object VMware.Vim.OptionValue[] (0)
$spec.dasConfig.heartbeatDatastore = New-Object VMware.Vim.ManagedObjectReference[] (0)
$spec.dasConfig.hBDatastoreCandidatePolicy = 'allFeasibleDsWithUserPreference'
$modify = $true
$_this = Get-View -Id 'ClusterComputeResource-domain-c22'
$_this.ReconfigureComputeResource_Task($spec, $modify)

This is super cool. I really like the way it’s been implemented and looking forward to further development of this Fling :-)

 

PowerShell Module for the Brickset API

Brickset.com is one of my favourite sites for finding info about Lego sets and keeping up-to-date with Lego news. I noticed recently that they had an API so I thought I would check it out. I posted a while back on how to do some similar stuff with other websites, but some of the functionality on those websites is no longer available.

This module for Brickset data contains functions for finding information about Lego sets and also makes it possible to download instruction manuals which can be pretty helpful if you have lost one of them or buy a 2nd hand set without the manuals.

1) Installation

Download the module from Github, ensure the files are unblocked and copy it to one of your PowerShell module folder paths. For me that is C:\Users\jmedd\Documents\WindowsPowerShell\Modules .

PSLego01

If you’ve done it successfully then you should be able to see details of the module with Get-Module:


Get-Module Brickset -Listavailable

PSLego02

You can take a look at the commands available by importing the module and then using Get-Command:


Import-Module Brickset

Get-Command -Module Brickset


PSLego03

 

2) Get a Brickset API Key

To use the Brickset API you need to first of all register for an API key. Fill out the form here and they will send you one. Currently they are free.

All of the Get-* functions in the module require you to use the API key; you won’t get very far without one.

3) Set a Global Variable for the API Key

Each of the Get-* functions has an APIKey parameter. However, to make things easier to use I’ve also added the Set-BricksetAPIKey function which will create a global variable for the API key that will be valid for the duration of that PowerShell session. If you don’t supply an API key to the Get-* functions then they will look for the global key having been set.

So the best thing to do is run this function first, with your API key, to set the API key variable:


Set-BricksetAPIKey -APIKey 'ed4w-KQA2-1Ps2' -Confirm:$false

PSLego04

 

4) Getting All Lego Sets by Theme

First example of using one of the Get-* functions is Get-BricksetTheme and Get-BricksetSet. Together they can be used to retrieve a list of Brickset Themes and then the sets in a theme. So let’s take a look at the example:

First of all, use Get-BricksetTheme to retrieve all available Themes from the Brickset site (remember you don’t need to specify the API key if it has already been set:


Get-BricksetTheme | Format-Table Theme,SetCount -AutoSize

PSLego05

Now say we want to retrieve all of the sets for the Indiana Jones theme we can use Get-BricksetSet with the Theme parameter:

Tip: You can use the OrderBy parameter to sort by a particular value. This may be more efficient than piping it through to Sort-Object afterwards:

Note: there is a lot more information available for each set than displayed here. I’ve restricted the output to a few key properties.


Get-BricksetSet -Theme 'Indiana Jones' -OrderBy Pieces | Format-Table Name,Number,Theme,SubTheme,Year,Pieces -AutoSize

PSLego06

5) Getting All Lego Sets by Theme and Year

If you want the search to be more specific then you can specify multiple search criteria. For instance one of the largest ranges is the Star Wars theme. Let’s have a look and see what sets have been released this year so far:


Get-BricksetSet -Theme 'Star Wars' -Year 2015 -OrderBy Pieces | Format-Table Name,Number,Theme,SubTheme,Year,Pieces -AutoSize

PSLego07b

 

6) Get a Specific Set by Set Number

All Lego sets are assigned a number by Lego. Use the SetNumber parameter of Get-BricksetSet to retrieve details of a specific set.

Note: the API requires that you supply the set number in the format {number}-{variant}, e.g. 7199-1. If you see the number on the front of the box as say 7199, typically you will need to use 7199-1 for the first variant of that set. However, be careful as this will not always be the case.

PSLego08


Get-BricksetSet -SetNumber '7199-1'

PSLego09

 

7) Download Lego Set Instructions

The function Get-BricksetSetInstructions will return URLs for links to the set’s instructions on the Lego.com website.

Note: the parameter to use is SetId not SetNumber. SetId is Brickset’s own reference number for the set and not the Lego Set Number we used in the previous example. Use Get-BricksetSet to find this info first. I’ve used PowerShell pipeline parameter binding in the functions so that you can do this easily:


Get-BricksetSet -SetNumber '7199-1' | Get-BricksetSetInstructions

PSLego10

Note: this example returned two pdfs, since it is a large set and had two printed manuals in the box.

If you want to open them straight into your web browser of choice you could do this:


Get-BricksetSet -SetNumber 7199-1 | Get-BricksetSetInstructions | Select-Object -ExpandProperty url | Foreach-Object {Invoke-Expression “cmd.exe /C start $_”}

or if you wanted to say download all of the instructions for a particular theme you could do this using the built-in Windows cmdlet Start-BitsTransfer:


Get-BricksetSet -Theme 'Indiana Jones' | Get-BricksetSetInstructions | Select-Object -ExpandProperty url | ForEach-Object {$file = ($_.split('/'))[-1]; Start-BitsTransfer -Source $_ -Destination "C:\Users\jmedd\Documents\$file"}

 

8) Other Module Functions

There are a few other functions in the module for finding information around Images, Set Reviews and Recently Updated Sets.

I hope you have fun with this module :-)

 

PowerShell: Default Value of [Int]$a is 0

I didn’t realise until yesterday that the default value of a variable using the [int] type had a default value of 0, e.g


[Int]$a

Int01

So what’s the big deal? Say you have a function as follows:


function Test-DefaultInt {

Param
 (

[Int]$a,

[Int]$b,

[Int]$c
 )

"a is $a"
 "b is $b"
 "c is $c"
}

and run it like so


Test-DefaultInt -a 5 -b 6 -c 7

Test-DefaultInt -a 5 -b 6

You get the following results:

Int02

If you change the function and take away the [int] from $c:


function Test-DefaultInt {

Param
(

[Int]$a,

[Int]$b,

$c
)

"a is $a"
"b is $b"
"c is $c"
}

and run the same tests you get the following:

Int03

with no value for c. OK, its a contrived example, but I had a reasonably complex situation to deal with. The difference between a variable being the value 0 or not present, inside the workings of the function, made a big difference to the output. Having wasted about an hour last night on it, I hope this saves someone else a headache :-)