Category Archives: vCAC

PowervRA – Now available on OS X and Linux via PowerShell Core!

Back Story

For a while Craig and I have had a number of requests regarding offering OS X and Linux support to PowervRA, particularly since in case you weren’t aware PowerShell is now available on those OSs and 3rd party modules such as PowerCLI are heading towards supporting that. We first looked at offering this support for PowervRA when the first Alpha release of PowerShell Core was shipped, however we were blocked by a couple of issues, particularly this one regarding certificate checking.

However, back in December I read about how the guys who maintain PowerNSX had been able to offer PowerShell Core support and they had also been blocked by that same issue which has now been resolved. So we updated to PowerShell Core Alpha 14 and started testing again – it seemed that another blocking issue around JSON responses had also been resolved, so things were looking good.

As it turned out, there weren’t a significantly large amount of changes which actually needed to be made on our side – some changes to the Connect-vRAServer and Invoke-vRARestMethod functions to do different things depending on whether PowerShell Core is being used. The scale of community feedback to the alpha releases of PowerShell Core and the efforts of the PowerShell team at Microsoft look like they have had a great impact and covered off a lot of the issues we might have had and the feedback has been quickly taken into subsequent alpha releases.

We benefited from the fact that we have previously invested quality time in producing integration tests for PowervRA, consequently we were able to run the same tests using a PowerShell Core client and only ended up with a couple of bugs that we are currently unable to resolve (here and here) , but looks like at least one of them is scheduled to be fixed for us via a milestone of PowerShell Core beta.

So in release 2.0.0 of PowervRA we are very pleased to bring you support for PowerShell Core!

Requirements

You will need:

PowerShell Core Alpha 14 + ….instructions on getting it installed for different OS flavours can be found here.

PowervRA 2.0.0 + . Get a copy of PowervRA onto the Linux  or OS X machine you want to run it from. Use the following to download it  from the PowerShell Gallery:

or manually copy the module yourself to one of the locations listed in $env:PSModulePath, for example:

In Action

OS X

Here’s PowervRA on my Macbook:

Connect to vRA

Retrieve Blueprint Details

Update a Reservation Policy

Ubuntu 16.04

Here’s PowervRA on Ubuntu 16.04:

Connect to vRA

Retrieve Business Group Details

Update a Network Profile

 

Docker

Craig has done some cool work to make PowervRA available via Docker. Check out his blog post for more details.

Also, many thanks to Alan Renouf for suggesting PowervRA now be made available hosted in the PowerCLI Core Docker Hub too.

Side Note

In PowervRA 2.0.0 we have also made some under the hood changes that it is worth being aware of (check the changelog for more details):

  • Module Restructure Part 1: we changed the functions from being their own individual nested modules in *.psm1 files to more simply being in *.ps1 files and made part of the module in a different way. This was a way I had historically put my modules together, but now have spent some time improving on it to a better way.
  • Module Restructure Part 2:  a number of functions had been marked in recent releases as deprecated, they have now been removed.
  • Module Restructure Part 3: we had previously started moving the functions into folders based on their API endpoint, this is now complete across all of the functions:

Issues

We believe we have covered off most issues with using PowervRA on PowerShell Core via our testing process, but if you do experience anything we have missed then please let us know here.

We are aware of one issue with running PowervRA on CentOS, which appears to be something not just relevant for us and should get fixed upstream in .Net Core.

Summary

We’re really pleased to be able to bring this support to PowervRA and much kudos to the PowerShell team and the wider community for making it both possible and relatively straightforward. We hope you find it useful given we know a significant part of our potentially user base are OS X users.

Also stay tuned because we are not stopping there. There is other planned new PowervRA functionality on the horizon ……

Create Blueprints in vRA7 with PowervRA

Update 29/09/2016:

The API documentation for importing a vRA Content Package contains a warning:

At this point, we don’t support any form of rollback strategies. A failed import may potentially leave the system in an inconsistent state. Hence, its highly recommend to run a precheck/dry-run before the import to validate the package. See HTTP POST /api/packages/validate for more details. This will help catch most of the errors upfront.

face-screaming-in-fearmonkey

Consequently, in release 1.3.1 we have added a new function Test-vRAContentPackage and included it by default in Import-vRAContentPackage. This should mitigate any issues with Importing a badly crafted Content Package, but you should of course test this before using in Production……

———————————————————————————————————————

A while back I wrote a post “Create Blueprints in vRA 7 via REST and via vRO” , with some details around automating vRA 7 Blueprint creation. Since that time Craig and I have published PowervRA, but in the initial releases I had some difficulty with providing the same functionality for PowerShell as I had in the previous post with REST and vRO.

However, thanks to some Ninja skills from Craig in our other project PowervRO, I was able to take the work we did over there around importing vRO Packages / Workflows etc via PowerShell and re-use it in PowervRA for a new function Import-vRAContentPackage, which is available in the latest release of PowervRA 1.3.0. Previous releases contained: New, Get, Remove and Export-vRAContentPackage, we just did not have the last piece of the puzzle: Import.

Example:

So here’s an example of how it works. In the previous article I showed how vRA Blueprints are bundled up into Content Packages and then exported to a zip file containing YAML files which each describe the Blueprints. We need to do the same when automating this process with PowerShell and PowervRA, so first of all we need to know the IDs of any Blueprints to add to the Content Package:

Now we create a Content Package containing the Id of the centos Blueprint that we wish to export:

and then export that Content Package to a zip file:

Take a look at the contents of the zip file and you will see that it contains a metadata.yaml file and a yaml file per Blueprint in a folder composite-blueprint:

powervra01

powervra02

Take a look at the contents of the centos.yaml file to see how a Blueprint is described:

Now we can either modify that file and import back into the same system if we want to change the existing Blueprint or we can take it further if we want to create more Blueprints. Let’s say we want to add a second, similar Blueprint. All we need to do is copy the existing centos.yaml file, make changes in it (I’ve just given larger CPU and memory values), then update the metadata.yaml file to reference the extra file. So they would end up like this:

centosb.yaml:

metadata.yaml:

Now create a new zip file containing the updated metadata.yaml file and the two blueprint yaml files:

powervra04

We can then import that zip file into a vRA Tenant. I’m going to use the Tenant that currently contains no Blueprints:

powervra03

Import the content package:

and we have two Blueprints 🙂

powervra05

centosb has those higher resource settings of 2CPUs and 2048MB memory which we changed in the yaml file:

powervra06

PowervRA 1.2.2 with Tested Support for vRA 6.2.4

One of the things we did for the 1.2.2 release of PowervRA was to test all of the functions against a vRA 6.2.4 deployment. Now that we have created Pester tests for all of the functions, it is quite straightforward for us to test against different vRA versions.

While we had initially targeted vRA 7+ because of the better API support, we know that currently the majority of installations out there are 6.x.x. So we are happy to confirm that 58 of the functions work fine with 6.2.4, which was a slightly higher figure than I was expecting.

All of the functions which will not work pre v7 have been updated to include an API version check and will exit the function with a message to reflect that if you try to use  them with 6.x.x, e.g.

Get-vRAContentPackage is not supported with vRA API version 6.2

v6Support01

 

Using Pester to Automate the Testing of PowervRA

Learning Pester has been on my list to get done this year and while working on PowervRA I finally had a real project that could make significant use of it. Being able to automate the testing of each PowerShell function means that we can quickly test the impact of any changes to a function. Also, it means that we can test the whole module full of functions against new (and potentially old) versions of vRA.

There is a very useful introduction to Pester on the Hey Scripting Guy site and that is what I used to get started with it.

So after we released the first version of PowervRA I set about creating a test for each function in the module – and here is where I learned my first mistake, although to be fair I knew I was making this mistake during the initial development of PowervRA. With 70+ functions in the module at that time, I needed to write a test for each of them. So after the initial interest in learning how Pester works, I then had the boring task of writing all of the tests.

What (I knew) we should have done, was write a Pester test for each function during (or before) the development of that function. Consequently, it would not seem like such a laborious task to make them. So going forward that’s what we are doing each time we create a new function.

So what does a test look like? Well here is one for Reservation Policies:

You should see that each set of tests is grouped in a Describe section. Each test starts with the It keyword, then typically we do something and check a property of the object returned afterwards. The Should keyword enables us to specify something to check the result against. As you can see Pester has been made so that the tests should be quite nicely readable.

We then follow a pattern of New-xxx, Get-xxx, Set-xxx, Remove-xxx, which all being well leaves us with a clean environment after the tests.

For these tests, we want to check each function against a real life instance of vRA, consequently we need some values. I’m not sure if this is the best way to do it, but for the time being we’ve abstracted the data out of the test files and into a JSON file of variables. This means if we want to run the same tests against a different instance of vRA, we just need to change some of the values in that file. (There is a way to carry out Unit testing in Pester using Mocking which we may visit at some point)

An example of how we can use them is as follows. We can fire the tests against a vRA 7.0 instance and get the following results:

Pester02

By changing some of the variables in the JSON file, we can then fire the same tests against a vRA 7.0.1 instance:

Pester03

and so we can tell with a good degree of confidence that nothing is broken for PowervRA between the two versions. As you can see we can run 81 tests in 60 – 75 seconds, which is pretty cool 🙂

Craig and I have discussed that we are only really scratching the surface with the tests so far and we could probably take someone onto the project who is solely dedicated to the testing (If you are interested, let me know 🙂  ). For example, for the time being we are only checking one property per New-vRAxxxx thing which gets created, ideally we should really test every property. For now though, what we have got so far is a big step forward and I’m looking forward to learning more about Pester.

If you want to check out what we have done with the tests you can find them here.

vRO requestCatalogItem from vRA Action – Available Properties

The vRO Action requestCatalogItem in the com.vmware.library.vcaccafe.request folder can be used to programmatically request an item from a vRA Catalog.

RequestCatalogItem01

One of the inputs is a properties object which permits you to dynamically make changes to settings configured within the Catalog Item you are deploying from. So say for instance the Catalog Item maps to a Blueprint configured with 1 vCPU, you could change this at request time to be 2 vCPU – which for instance might lead you to needing to maintain fewer Catalog Items.

It’s possible that it exists already, but I haven’t been able to find where the entire list of available properties that you can use are documented. Many of those starting VirtualMachine. or VMware. can be found in the vRA Custom Properties guide, so I’m not going to list them all here. However, not every available property in those ranges actually appear to be in that guide.

So I have decided to maintain a list here garnered from various sources, including a few common ones from the Custom Properties guide. If you know of any others not in the Custom Properties guide, then please leave a comment and I’ll add them:
provider-blueprintId: vRA Blueprint
provider-ProvisioningGroupId: Business Group

provider-VirtualMachine.CPU.Count:
provider-VirtualMachine.Memory.Size:
provider-VirtualMachine.NetworkX.NetworkProfileName: Network profile for NIC 0
provider-VirtualMachine.NetworkX.Name: Network Name (portgroup) for NIC 0

provider-VirtualMachine.DiskX.IsClone:
provider-VirtualMachine.DiskX.Size:

provider-VirtualMachine.DiskX.StorageReservationPolicy: vRA Storage Reservation Policy
provider-VirtualMachine.DiskX.StoragePolicy.FriendlyName: vCenter Storage Policy
provider-VirtualMachine.DiskX.StoragePolicy.vCenterStoragePolicy: vCenter Storage Policy

provider-VirtualMachine.LeaseDays

provider-VMware.VirtualCenter.Folder: Virtual Center folder
provider-Cafe.Shim.VirtualMachine.TotalStorageSize:
provider-Cafe.Shim.VirtualMachine.Description: Description
provider-Cafe.Shim.VirtualMachine.AssignToUser: vRA Machine owner
provider-Cafe.Shim.VirtualMachine.NumberofInstances: Number of VMs to deploy
provider-CustomPrefix
provider-__reservationPolicyID: vRA Reservation Policy

 

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

————————————————————————————————————————-

Update: 15/03/2017

Instead of the below long code section to search vRO for a workflow ID, you can use the Get-vROWorkflow function from the sister tool PowervRO.

————————————————————————————————————————-

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.

 

Troubleshooting the vSphere Initial Setup vRO Workflow in vRA 7

Part of the wizard to setup vRA 7 includes a step towards the end to create a vRO workflow that will create initial content within a vRA Tenant. To run the workflow, login to the default vRA tenant as the configurationadmin account created as part of the initial setup:

InitialConfig01

There are various inputs required depending on such things as if you wish to use the default Tenant or create an additional one:

InitialConfig02

What to do though if the workflow fails for some reason? Particularly if you are using the vRO server which is included as part of the vRA appliance, where do you go to look at what went wrong?

You can firstly look at the request in vRA:

InitialConfig03

 

InitialConfig04

If you are using the built-in vRO rather than an external one, you may not know the details to get into it. To access the vRO server that ships as part of the vRA appliance, point your vRO client at the vRA appliance and note a couple of things:

  • The Host name requires port 443 specified
  • The default User name is [email protected]

InitialConfig05

Note: If you don’t have the version 7 client installed, you can run it from the vRA appliance webpage https://vraappliance.fqdn:

InitialConfig06

Once in the vRO client, navigate to Library / vRealize Automation / InitContent / vSphere Initial Setup and you can examine further what went wrong:

InitialConfig07

 

vRA “Internal error: Error allocating network on machine. Attempted to divide by zero”

vRA 6.2.2: while attempting to deploy a VM from blueprint we received the following error:

Internal error: Error allocating network on machine. Attempted to divide by zero

Pretty helpful error message as usual for this version of the product 😉

The Network Profile and Path appeared to be set correctly when requesting the VM. We eventually tracked it down to the Network Profile IP Range having run out of unallocated IPs. The solution of course is to free up some IPs. Head to the Network Profile, IP Ranges to  check out which ones might be suitable to free up:

NetworkProfile01

Once you have removed a VM the IP will go into the Destroyed state for a while (I believe it is 30 mins, couldn’t find a document to confirm)

NetworkProfile02

To speed things up you can hit the Reclaim button:

NetworkProfile03

and the IP should got to the Unallocated state:

NetworkProfile04

Fire up the provision VM task again and things should be better now.