Use PowerShell to Refresh CenturyLink Cloud VM Snapshots

Summary: VMs created in the CenturyLink Cloud, can have a snapshot (only 1 per VM), and that snapshot has a maximum life of 10 days. Therefore if it’s necessary to maintain a perpetual snapshot (like for test VMs that have a baseline configuration), VMs need to have their snapshots routinely refreshed. The following PowerShell script leverages the powerful CenturyLink Cloud REST v2 API to automate this process. This script relies on the presence of a ‘bearer token’ for authentication into the CLC API. Details on how to create this ‘bearer token’ can be found in this blog post (as well as details on how to discover your Group ID). The complete reference to CenturyLink’s Cloud REST API can be found here: https://www.ctl.io/api-docs/v2/

This script basically leverages CLC APIs to restore, delete, and create a VM snapshot. After each API is called, the script will wait until the task is complete, by querying the status of the task requested.

Note: This script sample requires PowerShell v4+

Refresh-Snapshot.ps1

#
# Name:: Refresh-Snapshot.ps1
# Version:: 0.1.2 (3/5/2016)
# Script Description:: Refreshes a server's snapshot by restoring the snapshot, deleting it, then creating a new one.
#
# API Documentation:: https://www.ctl.io/api-docs/v2/
#
# Author(s):: Otto Helweg
#

param($s)

# Display help
if (($Args -match "-\?|--\?|-help|--help|/\?|/help") -or !($s)) {
  Write-Host "Usage: Refresh-Snapshot.ps1"
  Write-Host "     -s [server name]       (Required) Server's name according to Centurylink Cloud"
  Write-Host "     -r                     Revert VM to existing snapshot before refreshing"
  Write-Host ""
  Write-Host "EXAMPLES:"
  Write-Host "     Refresh-Snapshot.ps1 -s CA3TESTTEST01 -r"
  Write-Host ""
  exit
}

$goodStatus = @("notStarted","executing","succeeded","resumed")

# PowerShell v4 is required for the REST cmdlets
if (!($psversiontable.PSVersion.Major -ge 4)) {
  Write-Host -ForegroundColor "red" "Requires PowerShell v.4 or greater. Please install the Windows Management Framework 4 or above."
  exit
}

# Check to make sure the Bearer Token is less than 2 weeks old
if (!(Test-Path .\bearerToken.txt)) {
  Write-Host -ForegroundColor Red "Error: Bearer Token file is missing. Run Save-BearerToken.ps1"
  exit
} else {
  $fileInfo = dir .\bearerToken.txt
  if ($fileInfo.LastWriteTime -lt (Get-Date).AddDays(-11)) {
    Write-Host -ForegroundColor Yellow "Warning: Bearer Token file is almost out of date. Run Save-BearerToken.ps1"
  }
  if ($fileInfo.LastWriteTime -lt (Get-Date).AddDays(-13)) {
    Write-Host -ForegroundColor Red "Error: Bearer Token file is out of date. Run Save-BearerToken.ps1"
    exit
  }
}

$bearerTokenInput = Get-Content ".\bearerToken.txt"
$accountAlias = "SXSW"
$bearerToken = " Bearer " + $bearerTokenInput
$header = @{}
$header["Authorization"] = $bearerToken
$serverName = $s

Write-Host -ForegroundColor Green "Getting server properties for $serverName..."
$requestUri = "https://api.ctl.io/v2/servers/$accountAlias/$serverName"
$serverProperties = Invoke-RestMethod -Method GET -Headers $header -Uri $requestUri -ContentType "application/json"

if (!$serverProperties) {
  Write-Host -ForegroundColor Red "Error: $serverName does not appear to exist!"
  exit
}

if (($Args -contains "-r") -and $serverProperties.details.snapshots) {
  Write-Host -ForegroundColor Green "Restoring snapshot for $serverName..."
  $startTime = Get-Date
  $requestUri = "https://api.ctl.io$($serverProperties.details.snapshots.links.href[0])/restore"
  $restoreResult = Invoke-RestMethod -Method POST -Headers $header -Uri $requestUri -ContentType "application/json"
  $statusUri = "https://api.ctl.io/v2/operations/$accountAlias/status/$($restoreResult.id)"
  $continue = $true
  Write-Host "Waiting for snapshot restore to complete..."
  while ($continue) {
    $statusResult = Invoke-RestMethod -Method GET -Headers $header -Uri $statusUri -ContentType "application/json"
    [int]$elapsedSeconds = ($(Get-Date) - $startTime).TotalSeconds
    Write-Host "   [$elapsedSeconds seconds] $($statusResult.status)"
    if ($statusResult.status -eq "succeeded") {
      $continue = $false
    }
    if ($statusResult.status -notin $goodStatus) {
      Write-Host -ForegroundColor Red "Error: Restoring snapshot for $serverName failed!"
      exit
    }
    Sleep 2
  }
}

if ($serverProperties.details.snapshots) {
  Write-Host -ForegroundColor Green "Deleting snapshot for $serverName..."
  $startTime = Get-Date
  $requestUri = "https://api.ctl.io$($serverProperties.details.snapshots.links.href[0])"
  $restoreResult = Invoke-RestMethod -Method DELETE -Headers $header -Uri $requestUri -ContentType "application/json"
  $statusUri = "https://api.ctl.io/v2/operations/$accountAlias/status/$($restoreResult.id)"
  $continue = $true
  Write-Host "Waiting for snapshot delete to complete..."
  while ($continue) {
    $statusResult = Invoke-RestMethod -Method GET -Headers $header -Uri $statusUri -ContentType "application/json"
    [int]$elapsedSeconds = ($(Get-Date) - $startTime).TotalSeconds
    Write-Host "   [$elapsedSeconds seconds] $($statusResult.status)"
    if ($statusResult.status -eq "succeeded") {
      $continue = $false
    }
    if ($statusResult.status -notin $goodStatus) {
      Write-Host -ForegroundColor Red "Error: Deleting snapshot for $serverName failed!"
      exit
    }
    Sleep 2
  }
}

Write-Host -ForegroundColor Green "Creating snapshot for $serverName..."
$startTime = Get-Date
$createBody = "{
  ""snapshotExpirationDays"":""10"",
  ""serverIds"":[
      ""$serverName""
    ]
}"

$requestUri = "https://api.ctl.io/v2/operations/$accountAlias/servers/createSnapshot"
$restoreResult = Invoke-RestMethod -Method POST -Headers $header -Body $createBody -Uri $requestUri -ContentType "application/json"
$statusUri = "https://api.ctl.io/v2/operations/$accountAlias/status/$($restoreResult.links.id)"

$continue = $true
Write-Host "Waiting for snapshot creation to complete..."
while ($continue) {
  $statusResult = Invoke-RestMethod -Method GET -Headers $header -Uri $statusUri -ContentType "application/json"
  [int]$elapsedSeconds = ($(Get-Date) - $startTime).TotalSeconds
  Write-Host "   [$elapsedSeconds seconds] $($statusResult.status)"
  if ($statusResult.status -eq "succeeded") {
    $continue = $false
  }
  if ($statusResult.status -notin $goodStatus) {
    Write-Host -ForegroundColor Red "Error: Creating snapshot for $serverName failed!"
    exit
  }
  Sleep 2
}

 

Enjoy!

Ansible vs. Chef for Managing Windows

ConfigureRemotingForAnsible.ps1Summary: Ansible is a simple and powerful application/DevOps framework for managing Windows configuration and provisioning. Getting off the ground with Ansible was also fairly straightforward and doesn’t require a large time or infrastructure investment.

These are some initial thoughts about using Ansible to manage the Windows platform (specifically compared to Chef). This analysis does not consider the ways in which Chef might be a better choice than Ansible for Windows management (they do exist and might be the subject of another blog post in the future).

The Ansible pilot was setup to be able to mimic some existing Chef recipes in order to determine time investment and infrastructure requirements as well as Ansible capabilities. The pilot consisted of an Ansible server (CentOS 6 – 64bit) and a Windows server (Windows Server 2012 Standard Edition) to be managed. Findings were as follows (in no particular order):

Note: Ansible Module  = Chef Resource, Ansible Playbook = Chef Recipe

  • Agentless: Ansible does not use an agent to manage Windows, but merely uses Windows’ built in Windows Remote Management (WinRM) protocol and framework.
  • WinRM Configuration: The PowerShell script ConfigureRemotingForAnsible.ps1 needs to be run on the managed node in order to enable communication with the Ansible server. The script basically configures a custom HTTPS listener with a special certificate.
  • PowerShell 3.0: PowerShell 3.0 or above is required by Ansible. With PowerShell 3.0, the following Hotfix KB2842230 may also need to be installed. On the other hand, Chef works well with PowerShell 2.0. PowerShell 3.0 can be easily updated on versions of Windows Server (pre 2012 came with PowerShell 2.0) by installing the Windows Management Framework (WMF) 3.0.
  • Predictable Execution: Ansible playbooks have a single execution phase, rather than Chef’s compile then execute phases, which, in some cases, can make Chef recipes less predictable. For example in Chef, modifying an environmental variable several times on a managed node within a single run_list will produce unexpected results.
  • Fewer Facts: Far fewer Ansible Facts are discovered at runtime than Ohai Attributes for a Windows host (this is not so with Linux). Chef’s Ohai discovers the same mountain of properties on both Windows and Linux.
  • Parameters: Parameters can be passed into the Ansible Playbook from the command line which is useful for changing Playbook behavior when it’s executed.
  • PowerShell: Ansible runs pure PowerShell scripts “as is”. Chef requires PowerShell scripts to be slightly modified by escaping certain characters. Ansible also simply manages the transfer of the script to the managed node, script execution, and script removal.
  • External File Transfers: The Ansible URL module nicely transfers big files via a URL. This is convenient when using Artifactory or Pydio to pull down large binaries for installation or processing.
  • Unzipping Files: The Ansible ZIP module is simple to use and nicely expands compressed files on the managed node.
  • Variable Passing: Variables can be easily passed out of a PowerShell script to the Playbook (or other modules) during runtime. This is useful when PowerShell is used to dynamically gather or process needed data at runtime. Although Chef easily allows for the passing of Attributes into PowerShell scripts, pulling data back out of those scripts is tricky.
  • Windows Update Works! The Windows Update module works (no permissions issues, I don’t know how Ansible is accomplishing this because this is a known issue with Chef). The problem lies in Windows not granting access to certain internal methods when accessed remotely, even with Administrator credentials. To see how this can be overcome with Chef, go to this blog post on the topic.
  • Reboot Management: Ansible playbooks can easily manage reboots since the Playbook is being run from the Ansible server and not the Node.
  • User Input: An Ansible Playbook can take user input during runtime. For example getting runtime credentials when joining a Windows node to a domain.

Windows Update Playbook Example:

---
# This playbook installs Windows updates
# Run with the following command:
#   ansible-playbook update-win.yml --ask-pass --u Administrator

- name: Configure Server
  hosts: windows
  gather_facts: true
  tasks:
    - name: Install Windows updates
      win_updates:
        category_names: ['SecurityUpdates','CriticalUpdates','UpdateRollups','Updates']

    - name: Restart machine
      raw: shutdown /r /f /c "Ansible updates triggered"
      async: 0
      poll: 0
      ignore_errors: true

    - name: Waiting for server to come back
      local_action: wait_for
                    host={{ inventory_hostname }}
                    state=started
                    timeout=60
      sudo: false

Windows Domain Join Playbook Example:

---
# This playbook joins Windows to a domain
# Run with the following command:
#   ansible-playbook joindomain-win.yml --ask-pass --u Administrator


- name: Join domain
  hosts: windows
  gather_facts: true
  vars_prompt:
    - name: "user"
      prompt: "Domain Join username"
      private: no
    - name: "password"
      prompt: "Domain Join password"
      private: yes
  tasks:
    - name: Join domain script
      script: "files/join-domain.ps1 -u '{{ user }}' -p '{{ password }}'"
      ignore_errors: true

    - name: Waiting for server to come back
      local_action: wait_for
                    host={{ inventory_hostname }}
                    state=started
                    timeout=60
      sudo: false

Windows Domain Join PowerShell Script Example:

#
# Script:: join-domain.ps1
# Joins a sesrver to a domain
#

param($u,$p)

$securePassword = ConvertTo-SecureString -String $p -AsPlainText -Force
$psCreds = new-object -typename System.Management.Automation.PSCredential -argumentlist $u, $securePassword


$domainCheck = (Get-WmiObject -Class win32_computersystem).Domain
if (!($domainCheck -eq "contoso.com")) {
  Add-Computer -DomainName "contoso.com" -Credential $psCreds -Force -Restart

  eventcreate /t INFORMATION /ID 1 /L APPLICATION /SO "Ansible-Playbook" /D "joindomain-win: Added to the domain 'contoso.com'."
}

Enjoy!

Apply Windows Updates Via a Chef Recipe

Summary

Using Chef (or any other remote management tool for that matter – like Windows Remote Management or PowerShell Remoting) to apply Windows updates to a remote system is difficult because some of the Windows Update methods will not work when executed from a remote connection, even if you’re using Administrator level credentials (this is apparently a feature, not a bug). To get around this, the Chef recipe must launch the update commands via a task in Task Scheduler. This can be done by configuring the Task Scheduler task to call the Chef recipe via the local ‘chef-client’ utility.

In this example I’m creating a task to ‘run once’, but since it’s in the past, this task will never get executed on its own. Then I’m manually launching the newly created task, which just calls the Chef Client to run my InstallWindowsUpdates cookbook (recipe: default.rb).

Create/Execute Task via PowerShell Remoting Example:

Invoke-Command -ComputerName <server name> -Credential <admin credentials> -ScriptBlock { cmd /c "schtasks /Create /RU System /RL HIGHEST /F /TR ""c:\opscode\chef\bin\chef-client.bat -o InstallWindowsUpdates"" /TN ChefInstallUpdates /SC Once /ST 00:00 2>&1" }
Invoke-Command -ComputerName <server name> -Credential <admin credentials> -ScriptBlock { cmd /c "schtasks /run /tn ChefInstallUpdates 2>&1" }

Windows Update Recipe Example (default.rb):

#
# Cookbook Name:: InstallWindowsUpdates
# Recipe:: default
# Author(s):: Otto Helweg
#

# Configures Windows Update automatic updates
powershell_script "install-windows-updates" do
  guard_interpreter :powershell_script
  # Set a 2 hour timeout
  timeout 7200
  code <<-EOH
    Write-Host -ForegroundColor Green "Searching for updates (this may take up to 30 minutes or more)..."

    $updateSession = New-Object -com Microsoft.Update.Session
    $updateSearcher = $updateSession.CreateupdateSearcher()
    try
    {
      $searchResult =  $updateSearcher.Search("Type='Software' and IsHidden=0 and IsInstalled=0").Updates
    }
    catch
    {
      eventcreate /t ERROR /ID 1 /L APPLICATION /SO "Chef-Cookbook" /D "InstallWindowsUpdates: Update attempt failed."
      $updateFailed = $true
    }

    if(!($updateFailed)) {
      foreach ($updateItem in $searchResult) {
        $UpdatesToDownload = New-Object -com Microsoft.Update.UpdateColl
        if (!($updateItem.EulaAccepted)) {
          $updateItem.AcceptEula()
        }
        $UpdatesToDownload.Add($updateItem)
        $Downloader = $UpdateSession.CreateUpdateDownloader()
        $Downloader.Updates = $UpdatesToDownload
        $Downloader.Download()
        $UpdatesToInstall = New-Object -com Microsoft.Update.UpdateColl
        $UpdatesToInstall.Add($updateItem)
        $Title = $updateItem.Title
        Write-host -ForegroundColor Green "  Installing Update: $Title"
        $Installer = $UpdateSession.CreateUpdateInstaller()
        $Installer.Updates = $UpdatesToInstall
        $InstallationResult = $Installer.Install()
        eventcreate /t INFORMATION /ID 1 /L APPLICATION /SO "Chef-Cookbook" /D "InstallWindowsUpdates: Installed update $Title."
      }

      if (!($searchResult.Count)) {
        eventcreate /t INFORMATION /ID 999 /L APPLICATION /SO "Chef-Cookbook" /D "InstallWindowsUpdates: No updates available."
      }
      eventcreate /t INFORMATION /ID 1 /L APPLICATION /SO "Chef-Cookbook" /D "InstallWindowsUpdates: Done Installing Updates."
    }
  EOH
  action :run
end

Enjoy!

Using PowerShell to Pause CenturyLink Cloud Virtual Servers

Summary

The following script will pause all servers in the specified group for the account alias ‘SXSW’. You can discover your Group ID by querying an existing server (see example towards the end of this blog post). Pausing your Virtual Servers in the CenturyLink Cloud merely saves their state (memory and disk) and can easily be resumed by Starting them (unlike shutting them down or turning them off which does not save the state of their memory). Pausing servers is similar to ‘sleep’ mode supported by most computers. This can be useful for reducing your CLC costs when virtual servers are not being used. This script reads the necessary BearerToken credentials from a text file (bearerToken.txt) that is created by the following script (keep in mind that this token has a life of only 2 weeks and will then need to be regenerated):

Note: All of these script samples are using PowerShell v4 (required)

Example: Save-BearerToken.ps1
if (!($psversiontable.PSVersion.Major -ge 4)) {
 Write-Host -ForegroundColor Red "Requires PowerShell v.4 or greater. Please install the Windows Management Framework 4 or above."
 exit
}

$psCreds = Get-Credential -Message "Use CLC Web Portal Credentials"
$creds = @{
 username = $psCreds.username
 password = $psCreds.GetNetworkCredential().Password
}
$creds = $creds | ConvertTo-Json

Write-Host -ForegroundColor "green" "Getting authentication 'bearerToken'..."
$logonUri = "https://api.ctl.io/v2/authentication/login"
$logonResponse = Invoke-RestMethod -Method Post -Uri $logonUri -Body $creds -ContentType "application/json"

Write-Host -ForegroundColor "green" "Account Summary:"
$logonResponse

Write-Host -ForegroundColor "green" "Bearer Token (2 week TTL):"
$logonResponse.bearerToken
$logonResponse.bearerToken | Set-Content "bearerToken.txt"
Example: Pause-Servers.ps1
$bearerTokenInput = Get-Content ".\bearerToken.txt"
$groupId = "7c3a1aee32241223a1aee32241979a28"
$accountAlias = "SXSW"
$bearerToken = " Bearer " + $bearerTokenInput
$header = @{}
$header["Authorization"] = $bearerToken

# Discover all servers in the specified group
$requestUri = "https://api.ctl.io/v2/groups/$accountAlias/$groupId"
$groupOutput = Invoke-RestMethod -Method GET -Headers $header -Uri $requestUri -ContentType "application/json" -SessionVariable "theSession"

$serverArray = @()
$serverPause = @()
foreach ($item in $groupOutput.links) {
  if ($item.rel -eq "server") {
    $serverName = $item.href.split("/")[($item.href.split("/").count - 1)]
    $serverArray = $serverArray + ($serverName)
  }
}

# Gather server status
$serverList = ""
foreach ($serverName in $serverArray) {
  Write-Host -ForegroundColor Green "Getting server properties for $serverName..."
  $requestUri = "https://api.ctl.io/v2/servers/$accountAlias/$serverName"
  $serverProperties = Invoke-RestMethod -Method GET -Headers $header -Uri $requestUri -ContentType "application/json" -SessionVariable "theSession"
  $powerState = $serverProperties.details.powerState
  Write-Host -ForegroundColor Green "  PowerState: $powerState"
  if ($serverProperties.details.powerState -eq "started") {
    Write-Host -ForegroundColor Yellow "  Pausing $serverName"
    $serverPause = $serverPause + ($serverName)
    $serverList = "$serverList, $serverName"
  }
}

$serverList = $serverList.TrimStart(", ")
if ($serverPause.Count -eq 1) {
  $servers = "[ ""$serverPause"" ]"
} else {
  $servers = $serverPause | ConvertTo-Json
}

Write-Host -ForegroundColor Green "Sending Server pause request for $serverList"
Write-Host "servers: $servers"
Write-Host "serverPause: $serverPause"
$requestUri = "https://api.ctl.io/v2/operations/$accountAlias/servers/pause"
$pauseRequest = Invoke-RestMethod -Method POST -Headers $header -Uri $requestUri -Body $servers -ContentType "application/json" -SessionVariable "theSession"

Write-Host "Request Output: $pauseRequest"

Getting Your Group ID From Your Server

The following sample script will retrieve your Group ID from an existing server. You will need to incorporate your specific server name in this script (we use ‘CA3TESTTEST01’).

Example: List-ServerGroup.ps1
if (!($psversiontable.PSVersion.Major -ge 4)) {
  Write-Host -ForegroundColor Red "Requires PowerShell v.4 or greater. Please install the Windows Management Framework 4 or above."
  exit
}
$dataCenter = "CA3"
$serverName = "CA3TESTTEST01"
$psCreds = Get-Credential -Message "Use CLC Web Portal Credentials"
$creds = @{
 username = $psCreds.username
 password = $psCreds.GetNetworkCredential().Password
}
$creds = $creds | ConvertTo-Json

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

Write-Host -ForegroundColor "green" "Getting authentication 'bearerToken'..."
$logonUri = "https://api.ctl.io/v2/authentication/login"
$logonResponse = Invoke-RestMethod -Method Post -Headers $headers -Uri $logonUri -Body $creds -ContentType "application/json" -SessionVariable "theSession"

$bearerToken = " Bearer " + $logonResponse.bearerToken
$accountAlias = $logonResponse.accountAlias

$headers.Add("Authorization",$bearerToken)

Write-Host -ForegroundColor "green" "Getting datacenter capabilities for $dataCenter..."
$RequestUri = "https://api.ctl.io/v2/datacenters/$accountAlias/CA3/deploymentCapabilities"
$deployCapabilities = Invoke-RestMethod -Method GET -Headers $headers -Uri $RequestUri -ContentType "application/json" -SessionVariable "theSession"

Write-Host -ForegroundColor "green" "This datacenter supports the following platform templates:"
$deployCapabilities.templates
Output:

CLC Output 3

Extra: Task Scheduler Rule

The following is a rule that can be imported into Task Scheduler to run the above script on a regular basis.

<?xml version="1.0" encoding="UTF-16"?>
<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
<RegistrationInfo>
<Date>2015-06-19T10:56:50.2629119</Date>
<Author>CA3SXSWTEST01\Administrator</Author>
</RegistrationInfo>
<Triggers>
<CalendarTrigger>
<StartBoundary>2015-06-19T19:00:00</StartBoundary>
<Enabled>true</Enabled>
<ScheduleByDay>
<DaysInterval>1</DaysInterval>
</ScheduleByDay>
</CalendarTrigger>
</Triggers>
<Principals>
<Principal id="Author">
<UserId>CA3SXSWTEST01\Administrator</UserId>
<LogonType>Password</LogonType>
<RunLevel>LeastPrivilege</RunLevel>
</Principal>
</Principals>
<Settings>
<MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
<DisallowStartIfOnBatteries>true</DisallowStartIfOnBatteries>
<StopIfGoingOnBatteries>true</StopIfGoingOnBatteries>
<AllowHardTerminate>true</AllowHardTerminate>
<StartWhenAvailable>false</StartWhenAvailable>
<RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
<IdleSettings>
<StopOnIdleEnd>true</StopOnIdleEnd>
<RestartOnIdle>false</RestartOnIdle>
</IdleSettings>
<AllowStartOnDemand>true</AllowStartOnDemand>
<Enabled>true</Enabled>
<Hidden>false</Hidden>
<RunOnlyIfIdle>false</RunOnlyIfIdle>
<WakeToRun>false</WakeToRun>
<ExecutionTimeLimit>P3D</ExecutionTimeLimit>
<Priority>7</Priority>
</Settings>
<Actions Context="Author">
<Exec>
<Command>powershell.exe</Command>
<Arguments>.\Pause-Servers.ps1</Arguments>
<WorkingDirectory>C:\Users\Administrator\Documents\Scripts</WorkingDirectory>
</Exec>
</Actions>
</Task>

Enjoy!

PowerShell and the CenturyLink Cloud API

Summary

CenturyLink has a powerful REST API for automating the provisioning and management of virtual servers in their environment. And since PowerShell v4 now has cmdlets that support interacting with REST APIs, it is an easy way to work with entities in the CenturyLink Cloud. The following post will cover the steps required (and sample code) to use PowerShell to provision a CenturyLink Cloud virtual server. Plain old Internet connectivity is all that’s required between PowerShell and CenturyLink, since their API is on the open Internet. The complete reference to CenturyLink’s Cloud REST API can be found here: https://www.ctl.io/api-docs/v2/

Steps:

  1. Get a free account for CenturyLink Cloud here: https://www.centurylinkcloud.com/
  2. Get your Account Alias
  3. Get your Group ID (Default Group)
  4. Query for the capabilities of your desired datacenter (you can find a list of datacenters from the CenturyLink Cloud Control Portal here: https://control.ctl.io/)
  5. Create your server!

Note: All of these script samples are using PowerShell v4 (required)

Get Your Account Alias

Once you get your CenturyLink account, you set your account alias to an abbreviation between 2 and 4 characters. You can also get your AccountAlias from the REST API logon response. You also need to get the BearerToken from the logon response to use as your authentication mechanism with communicating with the CenturyLink REST API (a bearer token has a life of 2 weeks, so don’t hard code it into your scripts).

Example: LogonResponse.ps1
if (!($psversiontable.PSVersion.Major -ge 4)) {
  Write-Host -ForegroundColor "red" "Requires PowerShell v.4 or greater. Please install the Windows Management Framework 4 or above."
  exit
}
 
$psCreds = Get-Credential -Message "Use CLC Web Portal Credentials"
$creds = @{
 username = $psCreds.username
 password = $psCreds.GetNetworkCredential().Password
}
$creds = $creds | ConvertTo-Json
 
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
 
Write-Host -ForegroundColor "green" "Getting authentication 'bearerToken'..."
$logonUrl = "https://api.ctl.io/v2/authentication/login"
$logonResponse = Invoke-RestMethod -Method Post -Headers $headers -Uri $logonUrl -Body $creds -ContentType "application/json" -SessionVariable "theSession"
 
Write-Host -ForegroundColor "green" "Account Summary:"
$logonResponse
 
Write-Host -ForegroundColor "green" "Bearer Token (2 week TTL):"
$logonResponse.bearerToken
Output:
PS-CLC Output 1

Find the Default Group for Your Server

This example is going to use your account’s datacenter “Default Group” as the destination for your new server, specifically for the datacenter ‘CA3’ (in Calgary, Canada). Any group can be used, but your account will have a “Default Group” for each datacenter your account can access. This group ID is required in order to identify the destination for your new server.

Example:  GetDefaultDatacenter.ps1
$psCreds = Get-Credential -Message "Use CLC Web Portal Credentials"
$creds = @{
 username = $psCreds.username
 password = $psCreds.GetNetworkCredential().Password
}
$creds = $creds | ConvertTo-Json

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

# Write-Host -ForegroundColor "green" "Getting authentication 'bearerToken'..."
$logonUrl = "https://api.ctl.io/v2/authentication/login"
$logonResponse = Invoke-RestMethod -Method Post -Headers $headers -Uri $logonUrl -Body $creds -ContentType "application/json" -SessionVariable "theSession"

$dataCenter = "CA3"
$bearerToken = " Bearer " + $logonResponse.bearerToken
$accountAlias = $logonResponse.accountAlias

$headers.Add("Authorization",$bearerToken)

Write-Host -ForegroundColor Green "Getting datacenter groups for $dataCenter..."
$requestURL = "https://api.ctl.io/v2/datacenters/$accountAlias/CA3?groupLinks=true"
$datacenterLinks = Invoke-RestMethod -Method GET -Headers $headers -Uri $requestURL -ContentType "application/json" -SessionVariable "theSession"
Write-Host "Available links:"
Write-Host $datacenterLinks.links

foreach ($link in $datacenterLinks.links) {
  if ($link.rel -eq "group") {
    Write-Host -ForegroundColor Green "Getting default datacenter group for group $($link.id)..."
    $requestURL = "https://api.ctl.io/v2/groups/$accountAlias/$($link.id)"
    $datacenterGroups = Invoke-RestMethod -Method GET -Headers $headers -Uri $requestURL -ContentType "application/json" -SessionVariable "theSession"
    foreach ($group in $datacenterGroups.Groups) {
      if ($group.type -eq "default") {
        Write-Host "Found group:"
        Write-Host $group
        Write-Host "`n"
        Write-Host -ForegroundColor Green "Default Group for $($dataCenter): $($group.id)"
      }
    }
  }
}
Output:

PS-CLC Output 2

Query for the Capabilities of Your Desired Datacenter

You can also get a list of available datacenters through the API with the following URI: https://api.ctl.io/v2/datacenters/yourAccountAlias. For this example we’re going to query CA3 (Canada – Toronto). As of this writing, the list includes: CA1, CA2, CA3, DE1, GB1, GB3, IL1, NY1, SG1, UC1, UT1, VA1, WA1. You will want to select the desired platform for your virtual server from the datacenter’s available templates as well as the ID of your destination network. If you don’t have any networks yet, the easiest way to create on is to first deploy a virtual server through the Control Portal web site. This can also be created through the API, but for the sake of brevity, we’ll use a network that already exists.

Partial Example (using the results from logonResponse.ps1): Query the Datacenter
$bearerToken = " Bearer " + $logonResponse.bearerToken
$accountAlias = $logonResponse.accountAlias
 
$headers.Add("Authorization",$bearerToken)
 
Write-Host -ForegroundColor "green" "Getting datacenter capabilities for $dataCenter..."
$RequestURL = "https://api.ctl.io/v2/datacenters/$accountAlias/CA3/deploymentCapabilities"
$deployCapabilities = Invoke-RestMethod -Method GET -Headers $headers -Uri $RequestURL -ContentType "application/json" -SessionVariable "theSession"
 
Write-Host -ForegroundColor "green" "This datacenter supports the following platform templates:"
$deployCapabilities.templates
 
Write-Host -ForegroundColor "green" "This datacenter supports the following networks:"
$deployCapabilities.deployableNetworks
Output

CLC Output 2

Finally, Create Your Server

After gathering the destination group (default group for this example), provisioning template (sourceServerId) and the destination network, you can use the following script to create your virtual server in the CenturyLink Cloud.

Note: There is a character limitation for the ‘name’ field (6 I believe but this example uses a 4 character name).

Example: CreateServer.ps1
$server = @{
  name = "test"
  description = "My test server"
  groupId = "7c39b8a1aee32241979a282241979a28"
  sourceServerId = "WIN2012R2DTC-64"
  isManagedOS = "false"
  networkId = "7J3aCCm0GGF5ev4cmh6U58279b6f056a"
  password = "SomePassword!"
  cpu = 2
  memoryGB = 4
  type = "standard"
  storageType = "standard"
}
$server = $server | ConvertTo-Json
 
$psCreds = Get-Credential -Message "Use CLC Web Portal Credentials"
$creds = @{
 username = $psCreds.username
 password = $psCreds.GetNetworkCredential().Password
}
$creds = $creds | ConvertTo-Json
 
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
 
Write-Host -ForegroundColor "green" "Getting authentication 'bearerToken'..."
$logonUrl = "https://api.ctl.io/v2/authentication/login"
$logonResponse = Invoke-RestMethod -Method Post -Headers $headers -Uri $logonUrl -Body $creds -ContentType "application/json" -SessionVariable "theSession"
 
$bearerToken = " Bearer " + $logonResponse.bearerToken
$accountAlias = $logonResponse.accountAlias
 
$headers.Add("Authorization",$bearerToken)
 
Write-Host -ForegroundColor "green" "Sending Server build request..."
$requestURL = "https://api.ctl.io/v2/servers/$accountAlias"
$buildRequest = Invoke-RestMethod -Method POST -Headers $headers -Uri $requestURL -Body $server -ContentType "application/json" -SessionVariable "theSession"
 
Write-Host -ForegroundColor "green" "Request Output:"
Write-Host -ForegroundColor "green" "Server Name:"
$buildRequest.server
Write-Host -ForegroundColor "green" "Is Queued?"
$buildRequest.isQueued
Write-Host -ForegroundColor "green" "Queue Status Links:"
$buildRequest.links
Output

PS-CLC Output 4

Enjoy!

Chef and PowerShell DSC Overview

Summary

PowerShell DSC is a very valuable extension to Chef Cookbooks for configuring and provisioning Windows Nodes for the following reasons:

  • It can be assumed that DSC Resources will be updated sooner, more stable, and more powerful than the equivalent Windows specific Chef Resources. Primarily because many of the DSC Resources are developed by Microsoft, for Microsoft platforms and applications.
  • Base DSC Resources (e.g. ‘file’, ‘registry’, ‘environment’, ‘script’, ‘feature’) are available by default to Chef Recipes for Nodes that have the Windows Management Framework v.4 (WMF 4) installed.
  • DSC includes a wealth of extension Resources that can simplify and stabilize a Chef recipe when installing or configuring Windows platform components.
  • Chef makes it easier to leverage DSC Resources than a traditional PowerShell DSC infrastructure for the following reasons:
    • No DSC server is required
    • DSC extension Resources don’t require implementation on the server (packaging and checksums need to be manually created for each extension Resource)
    • The Node doesn’t need to be configured for as a DSC Node (WMF v.4+ is still required on the Node)
    • DSC Resources can be executed on the fly by Chef-Client on the Node (rather than waiting for the COM objects to get exercised by the DSC Scheduled Tasks which can lead to inconsistent results when invoked manually)

Considerations:

  • Chef-Client v.12+ is required on the Node
  • WMF v.4+ is required on the Node
  • Using the Chef Resource ‘dsc_resource’ requires WMF v.5+ (this analysis is focusing on the Chef Resource ‘dsc_script’). WMF 5 won’t RTM until Windows 10, but will be available downlevel to Windows Server 2008 and beta versions are currently available down to Windows Server 2008 R2
  • Using DSC extension Resources requires DSC extension Resource management within the cookbook (e.g. by using the Chef Resource ‘remote_diretory’ in order to make sure DSC extension Resources are available on the Node when called by the Chef Recipe) where this is handled automatically be DSC Server infrastructure.

Chef Resource and DSC Resource Comparison

The following comparison is not meant to argue the benefit of using DSC Resources over Chef Resources, rather these examples are meant to demonstrate the difference in code complexity when performing Windows platform actions from Chef vs. the PowerShell DSC server. Considering whether or not to use DSC Resources might also include weighing the decision to develop recipes that are platform dependent since there are no plans for DSC Resources to include platforms other than Windows. In addition, these examples don’t include any Chef Resources other than the ‘powershell_script’ Resource. There are many Windows specific Chef resources that can also simplify Chef Recipes.

The following examples demonstrate enabling remote access via RDP to the Node.

Example: Leveraging the Chef ‘powershell_script’ Resource
# Enables remote desktop access to the server
powershell_script "enable-remote-desktop" do
  guard_interpreter :powershell_script
  code <<-EOH
    Set-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server' -name "fDenyTSConnections" -Value 0
    Enable-NetFirewallRule -DisplayGroup "Remote Desktop"
    Set-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server\\WinStations\\RDP-Tcp' -name "UserAuthentication" -Value 1
    eventcreate /t INFORMATION /ID 2 /L APPLICATION /SO "Chef-Client" /D "Enabled Remote Desktop access"
  EOH
  only_if <<-EOH
    if ((Get-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server').fDenyTSConnections -ne "0") {
      $true
    } elseif ((Get-NetFirewallRule -Name "RemoteDesktop-UserMode-In-TCP").Enabled -ne "True") {
      $true
    } elseif ((Get-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server\\WinStations\\RDP-Tcp').UserAuthentication -ne "1") {
      $true
    } else {
      $false
    }
  EOH
end
Example: PowerShell DSC Script (Recipe) Using a DSC Resource
# Enables remote desktop access to the server via an experimental resource xRemoteDesktopAdmin
xRemoteDesktopAdmin EnableRDP
{
  Ensure = "Present"
  UserAuthentication = "Secure"
}
 
xFirewall AllowRDP
{
    Name = 'DSC - Remote Desktop Admin Connections'
    DisplayGroup = "Remote Desktop"
    Ensure = 'Present'
    State = 'Enabled'
    Access = 'Allow'
    Profile = ("Domain", "Private", "Public")
}
Example: Chef Recipe Using a DSC Resource from ‘dsc_script’
dsc_script "Configure Server" do
  imports 'xRemoteDesktopAdmin'
  imports 'xNetworking'
  code <<-SITESDSC
    # Enables remote desktop access to the server via an experimental resource xRemoteDesktopAdmin
    xRemoteDesktopAdmin EnableRemoteDesktop
    {
      Ensure = "Present"
      UserAuthentication = "Secure"
    }
 
    xFirewall AllowRDP
    {
        Name = 'DSC - Remote Desktop Admin Connections'
        DisplayGroup = "Remote Desktop"
        Ensure = 'Present'
        State = 'Enabled'
        Access = 'Allow'
        Profile = ("Domain", "Private", "Public")
    }
  SITESDSC
end
Example: Adding DSC Resource Extension Management in Chef Recipes

The following Chef Recipe snipit demonstrates how 2 DSC extension Resources are managed on the Node. The ‘remote_directory’ merely insures that the ‘xRemoteDesktopAdmin’ and ‘xNetworking’ resources are installed on the Node so they can be leveraged by the Chef Recipe.

remote_directory "C:\\Program Files\\WindowsPowerShell\\Modules\\xRemoteDesktopAdmin" do
  source "xRemoteDesktopAdmin"
  action :create
end
 
remote_directory "C:\\Program Files\\WindowsPowerShell\\Modules\\xNetworking" do
  source "xNetworking"
  action :create
end
Appendix: Full Chef Recipe ‘dsc_script.rb’

The following recipe performs actions on a Windows Server that fall under the topic of general server configuration.

# Requires Chef-Client v.12+
# Author: Otto Helweg
 
include_recipe 'ws2012r2::lcm_setup_dsc_script'
 
remote_directory "C:\\Program Files\\WindowsPowerShell\\Modules\\xRemoteDesktopAdmin" do
  source "xRemoteDesktopAdmin"
  action :create
end
 
remote_directory "C:\\Program Files\\WindowsPowerShell\\Modules\\xNetworking" do
  source "xNetworking"
  action :create
end
 
dsc_script "Configure Server" do
  imports 'xRemoteDesktopAdmin'
  imports 'xNetworking'
  code <<-SITESDSC
    # Leaves a timestamp indicating the last time this recipe was run on the node (this resource in intentionally not idempotent)
    Environment LeaveTimestamp
    {
      Ensure = "Present"
      Name = "DSCClientRun"
      Value = "Last PowerShell DSC run (UTC): " + (Get-Date).ToUniversalTime().ToString()
    }
 
    # Enables remote desktop access to the server via an experimental resource xRemoteDesktopAdmin
    xRemoteDesktopAdmin EnableRemoteDesktop
    {
      Ensure = "Present"
      UserAuthentication = "Secure"
    }
 
    xFirewall AllowRDP
    {
        Name = 'DSC - Remote Desktop Admin Connections'
        DisplayGroup = "Remote Desktop"
        Ensure = 'Present'
        State = 'Enabled'
        Access = 'Allow'
        Profile = ("Domain", "Private", "Public")
    }
 
    # Disables checking for updates
    Script DisableUpdates
    {
      SetScript = {
        $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
        $WUSettings.NotificationLevel = 1
        $WUSettings.save()
        eventcreate /t INFORMATION /ID 3 /L APPLICATION /SO "DSC-Client" /D "Disabled Checking for Updates"
      }
      TestScript = {
        $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
        if ($WUSettings.NotificationLevel -ne "1") {
          $false
        } else {
          $true
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    # Verifies Windows Remote Management is Configured or Configures it
    Script EnableWinrm
    {
      SetScript = {
        Set-WSManQuickConfig -Force -SkipNetworkProfileCheck
        eventcreate /t INFORMATION /ID 4 /L APPLICATION /SO "DSC-Client" /D "Enabled Windows Remote Management"
      }
      TestScript = {
        try{
          # Use to remove a listener for testing
          # Remove-WSManInstance winrm/config/Listener -selectorset @{Address="*";Transport="http"}
          Get-WsmanInstance winrm/config/listener -selectorset @{Address="*";Transport="http"}
          return $true
        } catch {
          #$wsmanOutput = "WinRM doesn't seem to be configured or enabled."
          return $false
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    # Installs the Applicaiton-Server Role
    Script InstallAppServer-LogEvent
    {
      SetScript = {
        eventcreate /t INFORMATION /ID 6 /L APPLICATION /SO "DSC-Client" /D "Installed Role: Applicaiton-Server"
      }
      TestScript = {
        if ((Get-WindowsFeature -Name Application-Server).Installed) {
          $true
        } else {
          $false
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    WindowsFeature InstallAppServer-Step1
    {
      Name = "Application-Server"
      Ensure = "Present"
      IncludeAllSubFeature = $true
    }
 
    WindowsFeature InstallAppServer-Step2
    {
      Name = "AS-Web-Support"
      Ensure = "Present"
      IncludeAllSubFeature = $true
      DependsOn = "[WindowsFeature]InstallAppServer-Step1"
    }
 
    # Disables Shutdown tracking (asking for a reason for shutting down the server)
    Script DisableShutdownTracking-LogEvent
    {
      SetScript = {
        eventcreate /t INFORMATION /ID 7 /L APPLICATION /SO "DSC-Client" /D "Disabled Shutdown Tracking"
      }
      TestScript = {
        if ((Get-ItemProperty -Path 'HKLM:\\SOFTWARE\\Policies\\Microsoft\\Windows NT\\Reliability').ShutdownReasonOn -ne "0") {
          $false
        } else {
          $true
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    Registry DisableShutdownTracking
    {
      Ensure = "Present"
      Key = "HKEY_LOCAL_MACHINE\\SOFTWARE\\Policies\\Microsoft\\Windows NT\\Reliability"
      ValueName = "ShutdownReasonOn"
      ValueData = "0"
      ValueType = "Dword"
      Force = $true
    }
 
    # Disables automatic maintenance
    Script DisableAutomaticMaintenance
    {
      SetScript = {
        $taskList = @("Idle Maintenance","Maintenance Configurator","Manual Maintenance","Regular Maintenance")
        $schTasks = Get-ScheduledTask
        foreach ($task in $schTasks) {
          if (($task.TaskPath -eq "\\Microsoft\\Windows\\TaskScheduler\\") -and ($taskList.Contains($task.TaskName))) {
            Unregister-ScheduledTask -TaskName $task.TaskName -TaskPath "\\Microsoft\\Windows\\TaskScheduler\\" -Confirm:$false
          }
        }
        eventcreate /t INFORMATION /ID 8 /L APPLICATION /SO "DSC-Client" /D "Disables automatic maintenance"
      }
      TestScript = {
        $taskList = @("Idle Maintenance","Maintenance Configurator","Manual Maintenance","Regular Maintenance")
        $schTasks = Get-ScheduledTask
        foreach ($task in $taskList) {
          if ($schTasks.TaskName.Contains($task)) {
            $found = $true
          }
        }
        if ($found = $true) {
          $false
        } else {
          $true
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
  SITESDSC
end

Enjoy!

PowerShell DSC Script Example – Node Configuration

The following PowerShell DSC script was converted from a Chef recipe for Windows located here. It’s easy to see that there’s a lot of similarity to the logic that PowerShell DSC and Chef use regarding their resources and provisioning or configuring as node (server). PowerShell DSC adds an additional feature in their Script Resource called ‘GetScript’ which handles gathering information from the Node (not used in this example) for use elsewhere in the Script Resource (must be passed back as a hash). In addition, idempotency is managed by ‘TestScipt’ passing back either $true or $false, where $false will cause ‘SetScript’ to execute. Lastly, all variables must be defined within a Script Resource (most commonly a script block) and not outside of the resource, otherwise they will be evaluated and stored at the time of the MOF file generation.

The following script demonstrates some of the server configuration functionality via PowerShell’s new DSC service, and performs the following actions:

  1. Timestamp: A Windows Event is created and an environmental variable is updated to show the last time this recipe was executed on the server.
  2. Enable Remote Desktop: The Remote Desktop (RDP) functionality is enabled.
  3. Disable Windows Updates: Windows automatic updates are disabled (use with caution – unless you have another update process, don’t do this).
  4. Enable Windows Remote Management: The Windows Remote Management functionality is enabled.
  5. Install IIS: The Application Server and Web Server roles are installed and enabled.
  6. Disable Server Reboot Tracking: A minor registry key is added/updated to stop the default practice of asking for a reboot reason on Windows Server.

DSC Publishing Steps:

The following steps are taken to publish a MOF file that’s ready to be consumed by nodes:

  1. PowerShell DSC script is written (below) and executed.
  2. In the current working directory (important!) a MOF file is created, representing the resources called out in the DSC script.
  3. The MOF file is named after the ‘Node’, in a sub-directory named after the ‘Configuration’ call (e.g. in this case it would be named ‘.\ServerConfig\Anybody.mof’)
    The MOF file is copied to the PowerShell DSC server’s hosting directory.
  4. A sister CheckSum file is generated for the newly created MOF file.
  5. Nodes will the download the MOF file via a REST call, specifying a specific MOF file by GUID (a node can only be configured to download a single MOF file). This will be covered in another blog.

DSC Script:

Configuration ServerConfig
{
  Node Anybody
  {
    # Leaves a timestamp indicating the last time this script was run on the node (this resource is intentionally not idempotent)
    Script LeaveTimestamp
    {
      SetScript = {
        $currentTime = Get-Date
        $currentTimeString = $currentTime.ToUniversalTime().ToString()
        [Environment]::SetEnvironmentVariable("DSCClientRun","Last DSC-Client run (UTC): $currentTimeString","Machine")
        eventcreate /t INFORMATION /ID 1 /L APPLICATION /SO "DSC-Client" /D "Last DSC-Client run (UTC): $currentTimeString"
      }
      TestScript = {
        $false
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    # Enables remote desktop access to the server
    Registry EnableRDP-Step1
    {
      Ensure = "Present"
      Key = "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Terminal Server"
      ValueName = "fDenyTSConnections"
      ValueData = "0"
      ValueType = "Dword"
      Force = $true
    }
 
    Registry EnableRDP-Step2
    {
      Ensure = "Present"
      Key = "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Terminal Server\WinStations\RDP-Tcp"
      ValueName = "UserAuthentication"
      ValueData = "1"
      ValueType = "Dword"
      Force = $true
    }
 
    Script EnableRDP
    {
      SetScript = {
        Enable-NetFirewallRule -DisplayGroup "Remote Desktop"
        eventcreate /t INFORMATION /ID 2 /L APPLICATION /SO "DSC-Client" /D "Enabled Remote Desktop access"
      }
      TestScript = {
        if ((Get-NetFirewallRule -Name "RemoteDesktop-UserMode-In-TCP").Enabled -ne "True") {
          $false
        } else {
          $true
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    # Disables checking for updates
    Script DisableUpdates
    {
      SetScript = {
        $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
        $WUSettings.NotificationLevel = 1
        $WUSettings.save()
        eventcreate /t INFORMATION /ID 3 /L APPLICATION /SO "DSC-Client" /D "Disabled Checking for Updates"
      }
      TestScript = {
        $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
        if ($WUSettings.NotificationLevel -ne "1") {
          $true
        } else {
          $false
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    # Verifies Windows Remote Management is Configured or Configures it
    Script EnableWinrm
    {
      SetScript = {
        Set-WSManQuickConfig -Force -SkipNetworkProfileCheck
        eventcreate /t INFORMATION /ID 4 /L APPLICATION /SO "DSC-Client" /D "Enabled Windows Remote Management"
      }
      TestScript = {
        try{
          # Use to remove a listener for testing
          # Remove-WSManInstance winrm/config/Listener -selectorset @{Address="*";Transport="http"}
          Get-WsmanInstance winrm/config/listener -selectorset @{Address="*";Transport="http"}
          return $true
        } catch {
          #$wsmanOutput = "WinRM doesn't seem to be configured or enabled."
          return $false
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    # Installs the Applicaiton-Server Role
    Script InstallAppServer-LogEvent
    {
      SetScript = {
        eventcreate /t INFORMATION /ID 6 /L APPLICATION /SO "DSC-Client" /D "Installed Role: Applicaiton-Server"
      }
      TestScript = {
        if ((Get-WindowsFeature -Name Application-Server).Installed) {
          $true
        } else {
          $false
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    WindowsFeature InstallAppServer-Step1
    {
      Name = "Application-Server"
      Ensure = "Present"
      IncludeAllSubFeature = $true
    }
 
    WindowsFeature InstallAppServer-Step2
    {
      Name = "AS-Web-Support"
      Ensure = "Present"
      IncludeAllSubFeature = $true
      DependsOn = "[WindowsFeature]InstallAppServer-Step1"
    }
 
    # Disables Shutdown tracking (asking for a reason for shutting down the server)
    Script DisableShutdownTracking-LogEvent
    {
      SetScript = {
        eventcreate /t INFORMATION /ID 7 /L APPLICATION /SO "DSC-Client" /D "Disabled Shutdown Tracking"
      }
      TestScript = {
        if ((Get-ItemProperty -Path 'HKLM:\\SOFTWARE\Policies\Microsoft\Windows NT\Reliability').ShutdownReasonOn -ne "0") {
          $false
        } else {
          $true
        }
      }
      GetScript = {
        # Do Nothing
      }
    }
 
    Registry DisableShutdownTracking
    {
      Ensure = "Present"
      Key = "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Reliability"
      ValueName = "ShutdownReasonOn"
      ValueData = "0"
      ValueType = "Dword"
      Force = $true
    }
  }
}
 
# The MOF filename must be a GUID. It can be any unique GUID and can be generated by the following PowerShell command ([guid]::NewGuid()).
$guid = "45b51dc8-132c-4052-8e3b-479c73d4c9cc"
 
# Create the MOF file from the above PowerShell DSC script
ServerConfig
 
# Used to copy the newly generated MOF file in the Pull Server's publishing location
$mofFile = "c:\dscscripts\ServerConfig\Anybody.mof"
$mofPath = "C:\Program Files\WindowsPowerShell\DscService\Configuration"
$DSCMofFile = $mofPath + "\" + $guid + ".mof"
 
Copy-Item $mofFile -Destination $DSCMofFile
# Generate a CheckSum sister file for the MOF file

 New-DSCCheckSum $DSCMofFile -Force
After the DSC script is executed on the node, New Windows Events should be logged to the configured node (server):

DSC-Example-1

And the following web page should be viewable on the node (server):

DSC-Example-2

The following practices are leveraged in this recipe:
  • A time stamp is logged on the server in order to track every time the script is executed via both a Windows Event and a Machine Environmental Variable (the environmental variable doesn’t refresh until you log out and log back in – is CMD getting cached somewhere?). This might be helpful for troubleshooting issues by correlating with the recipe execution timestamp.
  • A Windows Event is logged every time a resource is executed on the node (server). Event IDs are unique to the resource function.
  • All resources (except the timestamp resource) are idempotent. In other words, logic is in place to insure the resource is not executed if it doesn’t need to be. For example, if IIS has already been installed, then there should be no attempt to install it again. This is a ‘best practice’ for writing DSC scripts.
The following PowerShell functionality is exercised by this recipe:
  • An Environmental Variable is created/updated
  • Events are created with the ‘eventcreate’ command. The PowerShell ‘New-Event’ is not used because for Windows Server (not client) you need to register your custom event source with the server, so ‘eventcreate’ is simpler.
  • A Registry Key is added/updated
  • The Enable-FirewallRule cmdlet is used
  • A COM object is accessed and/or updated
  • The Set-WsmanQuickConfig cmdlet is used
  • The Get-WsmanInstance cmdlet is used
  • The Add-WindowsFeature cmdlet is used

Idempotency:

Notice that the Script Resource implements PowerShell script logic (via ‘TestScript’) in order to make the resource follow idempotent best practices (most of the other resources manage this for you). The logic implemented in the Script Resource is a reasonable attempt to determine if action is necessary, while not covering every possible permutation that might exist for a misconfigured server. Also notice how either $true or $false is passed back to the resource from the test logic. And finally, the ‘SetScript’ block is not executed unless ‘$false’ is returned by the ‘TestScript’ logic.

Enjoy!