New CloudReady PowerShell Management API

October 17, 2016
Jason Lieblich
Blog Posts

Exoprise recently released a new CloudReady PowerShell management API for configuring and maintaining a CloudReady environment alongside Office 365 environments.

As our customers expand their use of CloudReady across different services and locations, they sometimes find a need to automate the configuration and deployment. While CloudReady makes it easy and wizard driven to deploy sites and sensors, once you have more then 50 or 100 sensors it can be easier to automate the deployment with an Application Programming Interface (API). The DevOps culture & best-practices have become pervasive across all parts of modern enterprise IT-ops organizations and having the ability to repeatedly stand up your end-to-end monitoring solutions has become mission critical.

Other customers and partners we have are using our new Management API to quickly deploy and re-deploy sets of sensors for Office 365 network assessment and load-testing in different scenarios. Being able to rapidly spin-up, move and automate different network sensors such as SharePoint Online, Exchange Online, WGET and WebLogin sensors enables organizations to pre-determine how their network will perform before adopting different cloud and SaaS applications.

Some REST For The Weary

When the engineering team set out to fulfill the customer requests of creating an API for CloudReady configuration, we knew we would build the back-end to support web-service based REST-ful queries (REpresentation State Transfer). Still, we weren’t sure what to first wrap the web service actions in. Often, that’s how APIs are built – you build the back-end interfaces and then supply a library or local API for administrators to use.

Internally, we had lots of choices and fluency in many different languages. Our Exoprise CloudReady service is built-up off of Ruby-on-Rails with lots of Javascript/JQuery/Angular. Our on-premises pieces are built in various languages and environments: C/C++, .NET, HTML and more Javascript. But we abandoned what we were comfortable with and looked to our customers to choose something THEY were comfortable with: PowerShell.

The Power of PowerShell

PowerShell is the latest language for managing all things Windows and Office 365 these days. You can see some of the capabilities and ways of using PowerShell with Office 365 at these various Microsoft articles:

In polling our customers, PowerShell was clearly the preferred interface and an obvious win-win.

Exoprise Management API 1.0

With this first release of our Management API customers can now add, edit and update all of their CloudReady sensors for their entire deployment. We’ll be adding additional support for altering Alarm workflows, alarm recipient groups and other features within the next few months.

The Management API combined with our existing bulk-deployment and get-a-site methods enable customers to fully automate their entire CloudReady installation. Let’s take a look.

Getting Started

To get started with the Management API, you’ll need to sign into CloudReady and allocate an API key. The API key is tied to a personal account within the Organization. At this point, the Management API is only for paying customers – not for trial accounts. Trial accounts are limited to 3 sensors anyway so not a lot to automate.

Once you’ve allocated an API key, download the PowerShell module from the same API Settings page. You need to setup a few things to enable the PowerShell module to be securely loaded within your environment. More information can be found on our help page for the Management API.

Here’s a couple of PowerShell script simple snippets to get you started:

All CloudReady PowerShell interactions require setting an API key like this. This snippet shows getting a list of all of the sensors that the user that created the API key has access to:

#set the API key
Set-ExoApiKey "SOMEKEYa09aeb5c967406b3eb5c96"
#get all the sensors you have access to
Get-ExoSensor

To get a list of the sensors for a specific named site, try this:

Set-ExoApiKey "SOMEKEYa09aeb5c967406b3eb5c96"
#get the sensors for a specific site
Get-ExoSensor -Site "PODUNK"

To create a simple WGET sensor with the API, use the Add-ExoSensor command.

Set-ExoApiKey "SOMEKEYa09aeb5c967406b3eb5c96"
#create a new WGET sensor
Add-ExoSensor @{
     type = 'WGetSensor'
     interval = 1
     nickname = 'api3'
     sites = @{location = @('LOCATION_NAME')}
     config = @{
        targets = @(
        @{target = 'http://www.example.org/'}
     )}}

Finally, here’s an example of connecting Office 365 PowerShell with CloudReady PowerShell in the same script to synchronize passwords between accounts.

Set-ExoApiKey "SOMEKEYa09aeb5c967406b3eb5c96"

# set the password for the O365 test account the sensor will be using
$TEST_ACCOUNT = 'account@used_by_the_sensor'
$TEST_ACCOUNT_PASSWORD = 'test_account_password'

# prompt for O365 admin credentials
$credentials = Get-Credential

# authenticate and connect to the O365 admin service via PowerShell
Connect-MsolService -Credential $credentials

# set the password without requiring a password change on next login
Set-MsolUserPassword -UserPrincipalName $TEST_ACCOUNT -NewPassword $TEST_ACCOUNT_PASSWORD -ForceChangePassword $false

# create a CloudReady SharePointSensor
Add-ExoSensor @{
  type = 'SharePointSensor'
  interval = 5
  sites = @{location = @('YOUR_SITE_LOCATION_NAME')}
  config = @{
    email = $TEST_ACCOUNT
    password = $TEST_ACCOUNT_PASSWORD
    url = 'https://your_sharepoint_site.sharepoint.com'
  }
}

That’s it. It looks pretty simple but there’s lots of parameter validation and security going on under the hood within our backend services.

What’s Next

Exoprise will continue to expose more configuration and management of the CloudReady platform via PowerShell as well as possibly other languages in the near future. We have a prioritized list of pieces that we’ll be creating APIs for such as Alarm Recipient Groups, Alarms, Alert Status, Teams and other Organization configuration. If there’s something you’d like to see added ASAP then contact us at support@exoprise.com and let us know.