A Hitchhikers Guide to SRS 1.0.0

Sometimes announcements tend to disappear in the cracks of time. When the Script Runtime Service for vSphere (SRS) 1.0.0 was announced, I had the feeling just that happened.

When version 1.0.0 of this open-sourced (!) product was released, I had expected much more buzz on social media from VMware PowerCLI users. 

This appliance does in fact bring an answer to a wish that many PowerShell/PowerCLI users have had for years: a “Scripting Host“!

This Hitchhikers Guide to SRS 1.0.0 post will show how I build my own customised SRS appliance, and how I use it to run PowerShell/PowerCLI scripts.

Introduction

When you visit the Script Runtime Service for vSphere (SRS) repository, you’ll notice that this open-sourced project comes with extensive documentation.

Always a great characteristic for an open-sourced project!

The installation as a VM  (from the downloadable OVF files) or in a Kubernetes cluster is well documented.

The available documentation in the SRS repo contains instructions on how to build, and customise, your own SRS appliance under the Build and Run page.

This blog post documents how I did exactly that.

I wanted to have a fully automated, self-documenting, and repeatable method, think CI, to roll out my own SRS station.

  1. Roll out the Builder station and install the prerequisites.
  2. Start the Build of the SRS Appliance on the Builder station
  3. Retrieve the OVF/OVA files, created from the SRS Appliance, that came out of the build
  4. Use the OVF/OVA to deploy your SRS station

Creating the SRS Builder

The Prerequisites

To create an SRS OVA/OVF yourself you need a “builder” station. And on that station there need to be a number of packages installed. 

I included the installation of these packages in the “build” I describe in the next section.

The buildappliance.sh script, which you will need to run on the builder station, will use the packages to setup and configure an SRS appliance (VMware Photon based), and as the last step will generate an OVA file from the appliance.

That OVA file can then be used to deploy your SRS VM.

This is also the place where you can install extra applications and extra PowerShell modules that will be included in your DIY SRS OVA.

Create the Builder station

Preparation

I used an Ubuntu 18.04 LTS station as the Builder station. As the download of the ISO is also automated, I use the Daily Build.

I also check if the DNS A and PTR records for the Builder station are present in DNS. The Builder station I used has an FQDN of srsbuilder.local.lab with an IP address of 192.168.10.88.

Deploy the Builder

For the rollout of this Builder station, I used the Cloud-Init method I described in Cloud-Init – Part 2 – Advanced Ubuntu. I had to make some small changes to the Install-CloudInitVM function from that post, so I was able to specify the memory size and the disk size. The default sizes were insufficient to run the SRS Appliance build.

The updated function now has MemoryGB and DiskGB parameters.

I also had to add a snippet to handle the issue with the $PSScriptRoot parameter when running the code from the Visual Studio Code editor.

The call to the Install-CloudInitVM functions is rather straightforward.

Notice how I used the VICredentialStore to store and retrieve the credentials for the Builder station. When you run this from a PowerShell version greater than 5.1, you will have to replace that part with calls to the secrets manager of your choice.

The real strength of using this Cloud-Init method is that one can use a YAML file to specify how the target station, the Builder station, in this case, needs to be configured. And also specify which packages shall be installed on the target station as part of the deployment.

The following extract of my YAML file shows the packages that are required. It also includes pulling down the SRS appliance.

Verify the Builder

Once the Builder station is deployed, it is useful to check that everything the creation of the SRS Appliance needs, is present.

A word of warning, the following code includes all versions as hard-coded. This is not ideal, and especially for products that have a daily build, this will require updating the code each time. Since this was, at the time of writing this post, not my top priority, I postponed looking for a more portable solution to a later date.

Run the Build

When the Builder station is deployed, and we verified that all prerequisites are in place, we can start the deployment of the SRS Applicance. From which, if all goes well, the OVA file will be generated.

During my experimenting with building the SRS Appliance, I stumbled on two what I suspect are issues.

As a bypass I build the SRS Appliance for now with Photon V3 Rev 2.

I did not succeed in building the SRS Appliance with Photon V3 Rev 3 image. I opened an Issue for that, and I’m curious to know if the issue is a Photon issue or something in my environment.

Another issue, which seems to be a real, known issue, is that you apparently can not use a Distributed Switch Portgroup to build the SRS Appliance. The underlying issue seems to stem from the Packer application, more specifically the VMware-Iso builder. This builder uses VNC to ‘talk’ with the ESXi node on which the SRS Appliance is created.

There are two issues here:

  • VNC is not included anymore in ESXi since 6.7
  • With the ESXi API you can not interact with a VDS

The VNC issue is resolved by changing some Packer settings. But for the VDS issue, there is no solution besides switching to the vSphere-Iso builder in the Packer step, so I had to build the SRS Appliance on a VSS Portgroup.

I packaged the preparation steps and the start of the SRS Appliance build in a function, named Invoke-SRSBuild.

The call to the Invoke-SRSBuilder function is again straight-forward.

The OVA

When the call to the build.sh script completes successfully, there will be OVA/OVF files created on the Builder station.

Since the Builder station is, in my setup, a temporary station, I need to download those files to a more permanent location. The following snippet uses the Get-ScpFile cmdlet from the Posh-Ssh module to do that.

Deploy SRS

Once we have the OVA available, it is a piece of cake to deploy our SRS VM with the Get-OvfConfiguration and Import-VApp cmdlets.

Note that deploying the SRS OVA to a Distributed Switch Portgroup is perfectly possible. The VDS issue mentioned earlier only comes into play when Packer with the VMware-Iso builder is involved. 

Your first test to see if the deployment went ok, is to try and access the swagger page on your SRS VM. The URI is https://<your-SRS-FQDN>/swagger. When all goes well, you will see a page like this.

Using SRS

Now we can start using the SRS server to run our scripts. The way to do that is quite simple. The complete process is described in the Run Scripts section in the SRS repository.

A Simple Sample

My test installation of SRS is done on a VM that is named SRS1.

A basic REST API call to verify that everything is working, is to call the api/about method.

You notice that I created a function Invoke-SRSMethod instead of just calling the Invoke-WebRequest cmdlet directly. The reason for creating that function is that I needed to be able to bypass invalid certificates.

With PSv6 that has become easy, since the Invoke-WebRequest cmdlet now has the SkipCertificateCheck switch. 

But I wanted to have a function that would also work in a PSV5.1 environment, hence the function and the logic in there.

When all goes well, that snippet should return the following.

A PowerCLI example

The full sequence for running code on the SRS station is perfectly explained in the Run Scripts section on the SRS repository.

A full, scripted example, excluding the earlier Invoke-SRSMethod function, could look like this.

A Function

That turned out to be a whole lot of code to just run a simple Get-VM.

But since we will be using most of the time the same logic, we can easily turn that into a function. That will make submitting code to run on the SRS a lot simpler.

And while we are at it, let’s include an option to run the code from an existing .ps1 file.

This Invoke-SRSScript function can be used in two variations (parametersets). With the Code parameter, you pass a ScriptBlock.

With the Path parameter, you point to a .ps1 file.

Some Administration

The SRS comes with a number of preset values, see the Initial Configuration documentation. In some situations, you might want to change one or more of these settings.

The obvious solution is to rebuild your SRS OVA with the desired settings, and re-deploy your SRS VM. 

But you can also change these settings on the fly on an existing and running SRS. The following snippet is just an example where I change the script-runtime-service setting from the default 10 minutes to 20 minutes.

Note that such a change will not be applied immediately, it might take some time (we are talking minutes).

Epilogue

This concludes, for now, my somewhat lengthy Hitchhikers Guide to SRS 1.0.0, which resulted from my playing/testing/exploring the Script Runtime Service for vSphere (SRS) 1.0.0.

Is this something to should have gotten more attention when it was released?

Definitely!

I will surely be doing some more experimenting with the new and shining tool.

Enjoy!

6 Comments

    Testing Script Runtime Service for vSphere – part 2 – ConfigMgr.nl

    […] again I refer to @LucD’s blog if you want to see more advanced code on how to run your PowerShell code on […]

    Jeroen Buren

    Hi Luc, I agree with you that there wasn’t much noise about this initiative. But personally, I don’t see the added value. At least, not yet. Yes, you can run a script remotely but you would still need a central location for your scripts. And a shared Windows server with PowerCLI gives me the same functionality. Or am I missing something?

      LucD

      Hi Jeroen,
      I agree that there are many ways to run your PowerCLI scripts.

      Personally, I do see the value of the SRS solution especially in long(er)-running, scheduled scripts.
      Instead of having a dedicated server, be it Windows or Linux, you can now run those scripts from a pipeline.
      The advantages (in my opinion)
      – the entire process can easily be implemented in a pipeline (deploy VM – run script – remove VM)
      – always a fresh (no tattooing risk) server to run the scripts
      – that server is only there when you actually need it (not another of those permanent <5% CPU VMs)
      - vCenter connectivity and running multiple instances is integrated
      - makes it very easy to run against different versions of PowerShell and PowerCLI
      - the central script location (should be some kind of repository by now, think source control) can easily be 'pulled' in the pipeline I mentioned earlier

      It all depends of course on your specific environment and needs, but I definitely see advantages in the SRS solution.

      Also, the SRS solution is a basic framework, and I'm pretty sure VMware themselves will use it as the basis for future other solutions.
      Think PowerActions or an LCM proxy for the VMware DSC Resources.

        Jeroen Buren

        Hi Luc, I can see your point. I have to treat my script host more as cattle and not as a pet 😉 And start to think more as a developer.
        Thanks!

    Testing Script Runtime Service for vSphere – part 1 – ConfigMgr.nl

    […] Now that the SRS is installed successfully, it is time to use it! Luc Dekens wrote an excellent article about building your own SRS and how to use it: https://www.lucd.info/2020/12/23/a-hitchhikers-guide-to-srs-1-0-0/ […]

    A Hitchhikers Guide to SRS 1.0.0

    […] View Reddit by Arkiteck – View Source […]

Leave a Reply

Your email address will not be published. Required fields are marked *

*
*

This site uses Akismet to reduce spam. Learn how your comment data is processed.