Integrate Jenkins, Hashicorp Vault, and PowerShell

Summary: Passwords, Secrets, and Credentials, stored in a Hashicorp Vault server, can easily be leveraged by Jenkins Projects (including projects that leverage PowerShell for the automation – or pure Microsoft shops). There is a common tension between automation and security and this example will show how they can co-exist.

The following steps are used to enable this automation:

  • Save a Vault access token as a Jenkins Credential
  • Bind the Jenkins Credential to a Jenkins Project
  • Access the Jenkins Secret as an environment variable from PowerShell
  • Run a Jenkins Project (PowerShell) that loads all of the Vault Secrets for the project

When a credential is stored in Jenkins, it is encrypted and the credential secret value cannot be viewed after the fact, outside of a Jenkins project. When the credential is bound to a Jenkins project, it is loaded as an Environment Variable when the project is executed and can be accessed by the automation (PowerShell) in the manner. If the credential or secret is exposed in the StdOut of the automation, Jenkins will mask the credential value when it logs the output (see below).

Step 1: Add the Credential (Vault Secret)

From the Jenkins home, select Credentials, hover over the down arrow next to the domain “(global)”, and select “Add credentials”.

Jenkins-Add-Creds

Step 2: Add the Credential (Vault Secret)

Add the credential as a “Secret text” item.

Jenkins-Add-Creds-2

Step 3: Bind the Credential to the Project

Bind the credential (Vault Secret) to the Jenkins Project.

Jenkns-Bind-Secret

Step 4: Reference the Credential in PowerShell

Reference the Jenkins Secret via an environmental variable within the PowerShell automation.

 

Jenkins-PowerShell

The following PowerShell script is an example which will download and list all Vault Secrets within a particular path. Of course displaying secrets used during automation is not advisable, but serve as an example and launching point for using them in code.

Pull-Vault.ps1 (example):

# Version:: 0.1.5 (3/16/2017)
# Script Description:: Pulls Vault secrets into environmental variables.
#
# Author(s):: Otto Helweg
#
param($token,$vaultSvr,$path)

# Display help
if ($Args -match "-\?|--\?|-help|--help|/\?|/help") {
  Write-Host "Usage: Pull-Vault.ps1"
  Write-Host "     -path [path to credentials]             Path the list of credentials."
  Write-Host "     -token [Vault auth token]               Authentication token for accesing the Vault server."
  Write-Host "     -vaultSvr [Vault server name or IP]     Vault server name or IP address."
  Write-Host ""
  Write-Host "Examples:"
  Write-Host "     Pull-Vault.ps1 -token '770da5b6-eff1-6fd6-f074-1e2604987340'"
  Write-Host "     Pull-Vault.ps1 -token '770da5b6-eff1-6fd6-f074-1e2604987340' -vaultSvr '10.102.76.4'"
  Write-Host ""
  exit
}

if (!($env:VAULT_TOKEN) -or !($env:VAULT_ADDR)) {
  if (!($token)) {
    $token = Read-Host -Prompt "Enter Token for Vault authentication" -AsSecureString
    $token = (New-Object PSCredential "token",$token).GetNetworkCredential().Password
  }

  if (!($vaultSvr)) {
    $vaultSvr = Read-Host -Prompt "Enter Vault Server"
  }

  $env:VAULT_ADDR = "http://$($vaultSvr):8200"
  $env:VAULT_TOKEN = $token
}

if (!($path)) {
  $path = Read-Host -Prompt "Enter Secrets Path"
}

$keys = vault list -format=json $path | ConvertFrom-Json

foreach ($key in $keys) {
  $vaultKey = "TF_VAR_$key"
  $value = vault read -format=json "$($path)/$($key)" | ConvertFrom-Json
  if ($Args -contains "-debug") {
    Write-Host "  $($path)/$($key) : $($value.data.value)"
  }
  Write-Host "Loading env var: $vaultKey"
  Set-Item -path "env:$vaultKey" -value "$($value.data.value)"
}

Note: The output from the Jenkins Project will mask out any output that matches the Jenkins Secret.

...
VAULT_ADDR http://10.10.10.10:8200 
VAULT_ROOT_TOKEN **** 
VAULT_TOKEN **** 
windir C:\Windows 
WINSW_EXECUTABLE C:\Program Files (x86)
...

Enjoy!

Advertisements

Server QA Testing With Pester

Summary: Pester is a PowerShell spin on unit testing (much like ServerSpec) on and for Windows. This example will demonstrate using Pester to test a remote Windows server where the scenario is verifying the quality of a freshly provisioned Windows server. Pester is used to check various settings on this new server that generally verify that the provisioning automation did the right thing.

More information and source code is available at the Pester Git repository here: https://github.com/pester/Pester

The following steps are performed when testing a server:

  1. Pester PowerShell module is downloaded to the remote server and loaded
  2. Pester tests are uploaded to the remote server
  3. PowerShell Pester test functions are uploaded to the remote server
  4. Pester test suite is executed on the remote server and the results are displayed
  5. All Pester tests and modules are removed from the remote server

The following files are used for this automation:

  1. PowerShell control script that automates the tests on a remote server and manages downloading/uploading the necessary files: Test-Server.ps1
  2. Pester test suite that contains a list of the tests to be performed: Azure.tests.ps1
  3. PowerShell functions that perform the Pester tests: Pester-TestFunctions.ps1

Note: The test script specifically breaks out the Windows Update test since it can take a while to perform. PowerShell logic is used in order to determine whether or not this test is performed.

Test-Server.ps1

# Version:: 0.1.5 (12/19/2016)
# Script Description:: Configures a server for a specific customer.
#
# Author(s):: Otto Helweg
#

param($serverName)

# Display help
if (($Args -match "-\?|--\?|-help|--help|/\?|/help") -or (!($serverName))) {
  Write-Host "Usage: Test-Server.ps1"
  Write-Host "     -serverName [server name or ip]    (required) Specify a specific server"
  Write-Host "     -u                                 Also test for no updates available"
  Write-Host ""
  Write-Host "Examples:"
  Write-Host "     Test-Server.ps1 -serverName server01 -u"
  Write-Host ""
  exit
}

# Create PowerShell Remoting access creds
$username = "someUser"
$password = "somePassword"

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

if ($limit -eq "none") {
  $limit = $false
} elseif ($limit) {
  $limit = $limit.Split(",")
}

Write-Host "Working on $serverName"
if ($Args -contains "-u"){
  $tests = "updates,"
} else {
  $tests = ""
}

$output = Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { Test-Path "c:\PESTER" }

if (!($output)) {
  $output = Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { New-Item -Type Directory "c:\PESTER" -Force }
}

# Set execution policy to allow for running scripts
$execPolicy = Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { Get-ExecutionPolicy }
if ($execPolicy -ne "Unrestricted") {
  Write-Host "Temporarily modifying script execution policy"
  Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { Set-ExecutionPolicy Unrestricted -Force }
  $policyChanged = $true
}

Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock {
  New-Item -Type Directory 'C:\PESTER\' -Force
  $Destination = 'C:\PESTER\Pester-master.zip'
  $Source = 'https://github.com/pester/Pester/archive/master.zip'
  $client = new-object System.Net.WebClient
  $client.DownloadFile($Source, $Destination)

  $shell = new-object -com shell.application
  $zip = $shell.NameSpace('C:\PESTER\Pester-master.zip')
  foreach($item in $zip.items()) {
    $shell.Namespace('C:\PESTER').copyhere($item)
  }
}

$filesToTransfer = @("azure.Tests.ps1","Pester-TestFunctions.ps1")
foreach ($file in $filesToTransfer) {
  if (Test-Path ".\$file") {
    Write-Host "Transferring file $file"
    $fileContent = Get-Content ".\$file"
    Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { param($content,$fileName); $content | Set-Content -Path "c:\PESTER\$fileName" -Force } -ArgumentList $fileContent,$file
  }
}

Write-Host "Performing the following additional tests: $tests"
$output = Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { param($tests); Set-Location 'C:\PESTER\'; .\azure.Tests.ps1 -tests $tests } -ArgumentList $tests

$output = Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { Remove-Item 'C:\PESTER\' -Recurse -Force }
# Reset the script execution policy
if ($policyChanged) {
  Invoke-Command -ComputerName $serverName -Credential $psCreds -ScriptBlock { Set-ExecutionPolicy $Args -Force } -ArgumentList $execPolicy
}

Azure.test.ps1

param($tests)
########## BEGIN SCRIPT HEADER ##########
$TITLE = "DATAPIPE OLDCASTLE PESTER TESTS"
#Authors: Otto Helweg
$Global:Version = "1.0.5"
$Date = "12/10/2016"
##########  END SCRIPT HEADER  ##########

<#
.SYNOPSIS
========================================================================================
AUTOMATION
========================================================================================
These are a set of tests to verify the proper configuration of a Windows Server
#>

Import-Module .\Pester-master\Pester.psm1
. ".\Pester-TestFunctions.ps1"

$extraTests = $tests.Split(",")

if (!($blockSize)) {
  $blockSize = "65536"
}

Describe "$TITLE" {
  It "BigFix should be installed" {
    Test-InstallBES | Should Be "IBM Endpoint Manager Client"
  }

  if ($extraTests -contains "updates") {
    It "No Windows updates should be available" {
      Test-InstallWindowsUpdates | Should Be 0
    }
  }

  It "Firewall should be disabled" {
    Test-DisableWindowsFW | Should Be "Disabled"
  }

  It "RDP session count should be 0" {
    Test-EnableMultipleRDP | Should Be 0
  }

  It "Windows Update check should be disabled" {
    Test-DisableWindowsUpdateCheck | Should Be 1
  }

 It "Volume notification should be disabled" {
   Test-DisableVolumeNotification | Should Be 1
 }

 It "IEESC should be disabled" {
   Test-DisableIEESC | Should Be "Disabled"
 }

  It "UAC should be disabled" {
    Test-DisableUAC | Should Be 0
  }

  It "Should be domain joined" {
    Test-DomainJoin | Should Be 1
  }

  if ($extraTests -like "*drive*") {
    foreach ($test in $extraTests) {
      if ($test -like "*drive*") {
        $driveLetter = $test.Substring(($test.Length - 1),1)
        if ($driveLetter) {
          It "$($driveLetter): volume should exist" {
            Test-DriveLetter $driveLetter | Should Be 1
          }

          It "$($driveLetter): volume should have $blockSize byte blocks" {
            Test-DriveBlockSize $driveLetter $blockSize | Should Be 1
          }
        }
      }
    }
  }

  It ".Net 3.5 should be installed" {
    Test-DotNet35 | Should Be 1
  }

  if ($extraTests -contains "sql") {
    It "SQL should be installed and running" {
      Test-SQLRunning | Should Be 1
    }
    It "SQL remote backup storage should be configured" {
      Test-SQLBackupStorage | Should Be 1
    }
    It "SQL should be configured" {
      Test-SQLConfig | Should Be 1
    }
  }
}

Pester-TestFunctions.ps1

Note: Notice that these test functions are written in PowerShell and executed locally on the remote server. They are examples of the various ways PowerShell can be used to check the state of a server (e.g. Registry check, WMI query, etc.)

########## BEGIN SCRIPT HEADER ##########
$TITLE = "PESTER TEST FUNCTIONS"
#Authors: Otto Helweg
$Global:Version = "1.0.5"
$Date = "12/10/2016"
##########  END SCRIPT HEADER  ##########

<#
.SYNOPSIS
========================================================================================
AUTOMATION
========================================================================================
This is a suite of test functions called by Pester in order to verify the configuration of a Windows Sever
by using Pester tests. These can also be called directly by 'dot sourcing' this file by incluiding this command:
  . ".\WindowsPSM-TestFunctions.ps1"

These functions are named to mimic their sister functions defined in the 'WindowsPSM.psm1' PowerShell Module

#>


function Test-InstallBES {
  $wmiOutput = Get-WmiObject -Query "select * from Win32_Product where Name = 'IBM Enoint Manager Client'"
  $($wmiOutput.Name)
}

function Test-InstallWindowsUpdates {
  $UpdateSession = New-Object -com Microsoft.Update.Session
  $UpdateSearcher = $UpdateSession.CreateupdateSearcher()
  $SearchResult =  $UpdateSearcher.Search("IsAssigned=1 and IsHidden=0 and IsInstalled=0")
  $UpdateLowNumber = 0
  $UpdateHighNumber = 2
  $searchResult.Updates.Count
}

function Test-DisableWindowsFW {
  $firewallState = "Disabled"
  foreach ($profile in $fwProfile) {
    $netshOutput = netsh advfirewall show $profile state
    foreach ($item in $netshOutput) {
      if (($item -like "State*") -and (!($item -like "*OFF"))) {
        $firewallState = "Enabled"
      }
    }
  }
  $firewallState
}

function Test-EnableMultipleRDP {
  $sessionCount = 1
  $sessionCount = (Get-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Control\Terminal Server").fSingleSessionPerUser
  $sessionCount
}

function Test-DisableWindowsUpdateCheck {
  $updateCheck = (Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\WindowsUpdate\Auto Update\").AUOptions
  $updateCheck
}

function Test-DisableVolumeNotification {
  $volumeNotification = (Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\Explorer").HideSCAVolume
  $volumeNotification
}

function Test-DisableIEESC {
  if ((((Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Active Setup\Installed Components\{A509B1A7-37EF-4b3f-8CFC-4F3A74704073}").IsInstalled) -eq '0') -and ((((Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Active Setup\Installed Components\{A509B1A8-37EF-4b3f-8CFC-4F3A74704073}").IsInstalled -eq 0)))) {
    $ieescState = "Disabled"
  }
  $ieescState
}

function Test-DisableUAC {
  $uacState = 1
  $uacState = (Get-ItemProperty "HKLM:\Software\Microsoft\Windows\CurrentVersion\policies\system").EnableLUA
  $uacState
}

function Test-DomainJoin {
  $domainCheck = (Get-WmiObject -Class win32_computersystem).Domain
  if ($domainCheck) {
    $true
  }
}

function Test-DriveLetter($driveLetter) {
  $volOutput = Get-Volume $driveLetter -erroraction silentlycontinue
  if ($volOutput) {
    $true
  }
}

function Test-DriveBlockSize($driveLetter,$blockSize) {
  $wql = "SELECT Label, Blocksize, Name FROM Win32_Volume WHERE FileSystem='NTFS' AND Name='$($driveLetter):\\'"
  $diskInfo = Get-WmiObject -Query $wql -ComputerName '.' | Select-Object Label, Blocksize, Name
  if ($diskInfo.BlockSize -eq "$blockSize") {
    $true
  }
}

function Test-DotNet35 {
  if (Get-WindowsFeature -Name "NET-Framework-Core") {
    $true
  }
}

function Test-SQLRunning {
  $output = Get-Service -Name "MSSQLSERVER" -ErrorAction SilentlyContinue
  if ($output.Status -eq "Running") {
    $true
  }
}

Output will look something like:

PS C:\pester> .\Test-Server.ps1 -servername server01 -u
Working on server01
Temporarily modifying script execution policy
    Directory: C:\
Mode                LastWriteTime         Length Name                                PSComputerName
----                -------------         ------ ----                                --------------
d----          1/9/2017   3:55 PM                PESTER                              10.10.10.10
Transferring file Azure.tests.ps1
Transferring file Pester-TestFunctions.ps1
Performing the following additional tests: updates,driveu,drivel,sql,
Describing PESTER TEST FUNCTIONS
 [+] No Windows updates should be available 6.98s
 [+] Firewall should be disabled 179ms
 [+] RDP session count should be 0 16ms
 [+] Windows Update check should be disabled 12ms
 [+] UAC should be disabled 12ms
 [+] Should be domain joined 41ms
 [+] u: volume should exist 3.58s
 [+] u: volume should have 65536 byte blocks 100ms
 [+] l: volume should exist 184ms
 [+] l: volume should have 65536 byte blocks 15ms
 [+] .Net 3.5 should be installed 325ms
 [+] SQL should be installed and running 16ms
 [+] SQL remote backup storage should be configured 92ms
 [+] SQL should be configured 22ms

Enjoy!

Atomic Terraform with PowerShell

Summary: In this case, ‘Atomic’ refers to small components rather than nuclear power. This post will discuss the strategy of using many small Terraform plans to build an environment, rather than one large plan. Although this creates a Terraform plan management burden, its primary goal is to reduce Terraform’s blast radius (the amount of damage Terraform can do if its actions are unexpected – granted due typically to user error). In order to try to maintain the same level of automation, we will use PowerShell to automate Terraform provisioning.

When Terraform runs, it assumes that it knows the desired state of an environment and will make any changes necessary to get to this known state. This can be problematic when an environment is changed outside of Terraform, or Terraform’s own state files are not up to date, or changed outside of Terraform (e.g. misconfigured remote state).

We will use PowerShell to perform the following functions:

  • Run multiple Terraform plans with a single command.
  • Run multiple Terraform plans in parallel using PowerShell Jobs.
  • Verify most recent modules are referenced for the Terraform plan.
  • Verify Terraform remote state is properly configured before taking action.
  • Verify Terraform will not ‘change’ or ‘destroy’ anything when provisioning a new instance (unless overridden).

Our environment will contain a single Terraform plan in a sub-directory that represents a single instance. Therefore if an environment has 5 servers and 1 network, there will be 6 sub-directories containing 6 plans.

Note: A future blog post will show how to use PowerShell to programmatically generate all Terraform plans for an environment in order to further reduce the plan management burden for an Atomic Terraform implementation.

Example 1 – Automate Multiple Terraform ‘Applys’: See the above list of actions that PowerShell will take before executing a Terraform Apply.

# Version:: 0.1.5 (10/21/16)
# Script Description:: This script is a wrapper for running multiple terraform commands in the background using PowerShell jobs.
#
# Author(s):: Otto Helweg
#

param($limit)

# Display help
if (($Args -match "-\?|--\?|-help|--help|/\?|/help") -or (!($limit))) {
  Write-Host "Usage: Terraform-Apply-All.ps1"
  Write-Host "     -limit [instance(s)/none]   (required) Specify a specific instance (e.g. VM), or 'none' to run against all servers"
  Write-Host "     -force                      Force the Apply even if elements will be changed or destoryed"
  Write-Host ""
  Write-Host "Examples:"
  Write-Host "     Terraform-Apply-All.ps1 -limit network01,server01 -force"
  Write-Host "     Terraform-Apply-All.ps1 -limit none"
  Write-Host ""
  exit
}

if ($limit -eq "none") {
  $limit = $false
} elseif ($limit) {
  $limit = $limit.Split(",")
}

$instances = (Get-ChildItem -Directory -Exclude "modules").Name
$currentDir = (Get-Item -Path ".\" -Verbose).FullName

$startTime = Get-Date
$jobIds = @{}
foreach ($instance in $instances) {
  $planChecked = $false
  $remoteChecked = $false
  if (($limit -and ($instance  -in $limit)) -or (!($limit))) {
    Write-Host "Working in Terraform directory $instance"
    if (Test-Path $instance) {
      # Check to make sure remote state file is configured
      Set-Location "$instance"
      terraform get
      $remoteOutput = terraform remote pull 2>&1
      Set-Location "..\"
      if ($remoteOutput -notlike "*not enabled*") {
        $remoteChecked = $true
      } else {
        Write-Host -ForegroundColor RED "Error: Remote state file pointer is not configured."
      }

      # Check to make sure nothing will be changed or destroyed (unless forced)
      if ($remoteChecked) {
        Set-Location "$instance"
        $planOutput = terraform plan
        Set-Location "..\"
        if (($planOutput -like "* 0 to change*") -and ($planOutput -like "* 0 to destroy*")) {
          $planChecked = $true
        } else {
          if ($Args -contains "-force") {
            $planChecked = $true
            Write-Host -ForegroundColor YELLOW "Warning: Terraform Apply will change or destroy existing elements. Force detected."
          } else {
            Write-Host -ForegroundColor YELLOW "Warning: Terraform Apply will change or destroy existing elements. Skipping $instance"
          }
        }
      }
      if ($planChecked -and $remoteChecked) {
        $jobInfo = Start-Job -ScriptBlock { Set-Location "$Args"; terraform apply -no-color } -ArgumentList "$currentDir\$instance"
        $jobIds["$instance"] = $jobInfo.Id
        Write-Host "  Creating job $($jobInfo.Id)"
      }
    } else {
      Write-Host -ForegroundColor RED "Error: $instance plan does not appear to exist, consider running 'Build-TerraformEnv.ps1' in ..\setup."
    }
  }
}

$waiting = $true
while ($waiting) {
  $elapsedTime = (Get-Date) - $startTime
  $allJobsDone = $true
  foreach ($instanceKey in $jobIds.Keys) {
    $jobState = (Get-Job -Id $jobIds[$instanceKey]).State
    Write-Host "($($elapsedTime.TotalSeconds) sec) Job $serverKey - $($jobIds[$instanceKey]) status: $jobState"
    if ($jobState -eq "Running") {
      $allJobsDone = $false
    }
  }
  if ($allJobsDone) {
    $waiting = $false
  } else {
    Sleep 10
  }
}

$jobState = @{}
foreach ($instanceKey in $jobIds.Keys) {
  $jobOutput = Receive-Job -Id $jobIds[$instanceKey]
  if ($jobOutput -like "*Apply complete!*") {
    Write-Host -ForegroundColor GREEN "Job $serverKey - $($jobIds[$instanceKey]) output:"
    $jobState[$instanceKey] = "Succeeded"
  } else {
    Write-Host -ForegroundColor RED "Error: Job $serverKey - $($jobIds[$instanceKey]) failed. Output:"
    $jobState[$instanceKey] = "Failed"
  }
  Write-Output $jobOutput
}

Write-Host -ForegroundColor GREEN "Job status summary:"
foreach ($instanceKey in $jobState.Keys) {
  Write-Host "$instanceKey - $($jobState[$instanceKey])"
}
Example 2 – Automate Multiple Terraform Destroys: This is very similar to the above script, but requires less ‘checks’. Merely replace the remote configuration check code with (we don’t need to check the plan since we want Terraform to just delete the instances):
    if ($remoteOutput -notlike "*not enabled*") {
      $jobInfo = Start-Job -ScriptBlock { Set-Location "$Args"; terraform destroy -force -no-color } -ArgumentList "$currentDir\$instance"
      $jobIds["$instance"] = $jobInfo.Id
      Write-Host "  Creating job $($jobInfo.Id)"
    } else {
      Write-Host -ForegroundColor RED "Error: Remote state file pointer is not configured."
    }

And replace the success check with:

  if ($jobOutput -like "*Destroy complete!*") {
    Write-Host -ForegroundColor GREEN "Job $instanceKey - $($jobIds[$instanceKey]) output:"
    $jobState[$instanceKey] = "Succeeded"
  } else {
    Write-Host -ForegroundColor RED "Error: Job $instanceKey - $($jobIds[$instanceKey]) failed. Output:"
    $jobState[$instanceKey] = "Failed"
  }

Enjoy!

Using AWS SSM With Windows Instances

Summary: Late 2015, AWS introduced a new feature called SSM (Simple System Manager) which lets you remotely execute commands on Windows (and Linux) server instances within AWS EC2. Unlike Windows Remote Management, SSM leverages the EC2 infrastructure to directly interact with the server instance, bypassing the need for WinRM ports to be opened up. In addition, SSM commands are interacting with the EC2Config service running on the server instance.

SSM supports several methods on the remote instance including running PowerShell commands as well as a very powerful Windows Update method (which also manages rebooting the server instance). Here’s a list of the available Windows methods in SSM:

  • AWS-JoinDirectoryServiceDomain: join an AWS Directory
  • AWS-RunPowerShellScript: run PowerShell commands or scripts
  • AWS-UpdateEC2Config: update the EC2Config service
  • AWS-ConfigureWindowsUpdate: configure Windows Update settings
  • AWS-InstallApplication: install, repair, or uninstall software using an MSI package
  • AWS-InstallPowerShellModule: install PowerShell modules
  • AWS-ConfigureCloudWatch: configure Amazon CloudWatch Logs to monitor applications and systems
  • AWS-ListWindowsInventory: collect information about an EC2 instance running in Windows
  • AWS-FindWindowsUpdates: scan an instance and determines which updates are missing
  • AWS-InstallMissingWindowsUpdates: install missing updates on your EC2 instance
  • AWS-InstallSpecificWindowsUpdates: install one or more specific updates

Note: SSM commands are run from the Local System account on the EC2 server instance, meaning they are run as Administrator.

The following examples show how to leverage SSM via the AWS CLI utility. AWS CLI must first be installed and configured with the proper credentials for these examples to work. These commands can be run from either a CMD or PowerShell prompt.

Example 1 – Run a PowerShell command with SSM: This demonstrates using PowerShell to modify a firewall rule using SSM on an EC2 instance. Where using User-Data can be used to run PowerShell commands when EC2 creates instances, SSM can be run anytime after the instance is running.

aws ssm send-command --instance-ids "i-12345d8d" --document-name "AWS-RunPowerShellScript" --comment "Update Firewall Rule" --parameters commands="Set-NetFirewallRule -Name WINRM-HTTP-In-TCP-PUBLIC -RemoteAddress Any"

Example 2 – Install all missing updates: This is a very powerful method in SSM where all missing updates can be applied to an EC2 instance with a single command. This method also manages rebooting the instance after the updates are installed, if necessary.

aws ssm send-command --instance-ids "i-12345a86" --document-name "AWS-InstallMissingWindowsUpdates" --comment "Install Windows Upates" --parameters UpdateLevel="All"

Note: All SSM PowerShell commands that are run on an instance are saved in ‘C:\programdata\Amazon\Ec2Config\Downloads\aws_psModule’. This can be useful for troubleshooting commands or should be considered if sensitive information is used within SSM PowerShell commands.

Once an SSM command is executed, the job details are passed back in JSON to allow for monitoring the job state. This allows for automation to query the job status and apply logic for further action.

For example, the job details can be assigned to a PowerShell variable as follows (PowerShell v.4+ is required when using the ConvertFrom-Json cmdlet):

$ssmJob = (aws ssm send-command --instance-ids "i-12345d8d" --document-name "AWS-RunPowerShellScript" --comment "Update Firewall Rule" --parameters commands="Set-NetFirewallRule -Name WINRM-HTTP-In-TCP-PUBLIC -RemoteAddress Any") | ConvertFrom-JSON

The details of the job can be viewed by inspecting the $ssmJob object as follows:

$ssmJob.Command

You can query for the status of an SSM job using the following example:

$ssmJobStatus = (aws ssm list-command-invocations --command-id $ssmJob.Command.CommandId) | ConvertFrom-Json
$ssmJobStatus.CommandInvocations.Status

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!

Configuring Windows with Chef and the PowerShell Resource

The PowerShell Resource in Chef is very powerful and versatile for configuring Windows. It essentially exposes all of the power of PowerShell to Chef. And since in PowerShell v.4, most Server Manager functionality is exposed via PowerShell cmdlets, there isn’t a lot you can’t configure in Windows with PowerShell.

The following recipe demonstrates some of the server configuration functionality via Chef’s PowerShell resource by performing 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.

Chef Recipe:

# Leaves a timestamp indicating the last time this recipe was run on the node (this resource in intentionally not idempotent)
powershell_script "leave-timestamp" do
  code <<-EOH
    $currentTime = Get-Date
    $currentTimeString = $currentTime.ToUniversalTime().ToString()
    [Environment]::SetEnvironmentVariable("ChefClientRun","Last Chef-Client run (UTC): $currentTimeString","Machine")
    eventcreate /t INFORMATION /ID 1 /L APPLICATION /SO "Chef-Client" /D "Last Chef-Client run (UTC): $currentTimeString"
  EOH
end
 
# 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
 
# Disables checking for updates
powershell_script "disable-update-checking" do
  guard_interpreter :powershell_script
  code <<-EOH
    $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
    $WUSettings.NotificationLevel = 1
    $WUSettings.save()
    eventcreate /t INFORMATION /ID 3 /L APPLICATION /SO "Chef-Client" /D "Disabled Checking for Updates"
  EOH
  only_if <<-EOH
    $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
    if ($WUSettings.NotificationLevel -ne "1") {
      $true
    } else {
      $false
    }
  EOH
end
 
# Verifies Windows Remote Management is Configured or Configures it
powershell_script "check-winrm" do
  guard_interpreter :powershell_script
  code <<-EOH
    Set-WSManQuickConfig -Force -SkipNetworkProfileCheck
    eventcreate /t INFORMATION /ID 4 /L APPLICATION /SO "Chef-Client" /D "Enabled Windows Remote Management"
  EOH
  not_if <<-EOH
    # $wsmanOutput isn't used here, just a placeholder for possible use in the future
    try {
      # Use to remove a listener for testing
      # Remove-WSManInstance winrm/config/Listener -selectorset @{Address="*";Transport="http"
      $wsmanOutput = Get-WsmanInstance winrm/config/listener -selectorset @{Address="*";Transport="http"}
      $true
    } catch {
      $wsmanOutput = "WinRM doesn't seem to be configured or enabled."
      $false
    }
  EOH
end
 
# Installs the Application-Server Role
powershell_script "install-application-server" do
  guard_interpreter :powershell_script
  code <<-EOH
    $installResult = Add-WindowsFeature Application-Server,AS-Web-Support
    foreach ($result in $installResult) {
      if ($result.RestartNeeded -eq "Yes") {
        eventcreate /t INFORMATION /ID 5 /L APPLICATION /SO "Chef-Client" /D "Restart is required."
      }
    }
    eventcreate /t INFORMATION /ID 6 /L APPLICATION /SO "Chef-Client" /D "Installed Role: Applicaiton-Server"
  EOH
  not_if <<-EOH
    if ((Get-WindowsFeature -Name Application-Server).Installed) {
      $true
    } else {
      $false
    }
  EOH
 end
Your output should look something like this (although I ran this with Test-Kitchen rather than ‘chef-client’ directly):

Note: The check-winrm script did not execute because it was already configured on the node (server).

Chef-PowerShell-1

New Windows Events should be logged to the configured node (server):

Chef-PowerShell-2

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

Chef-PowerShell-3

The following practices are leveraged in this recipe:

  • A time stamp is logged on the server in order to track every time the recipe is executed. 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 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 recipes.

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 nearly all the resources implement PowerShell script logic in order to make their resources follow idempotent best practices. The logic implemented 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. Both conditions need to be addressed by the Guard. Also notice where ‘not_if’ and ‘only_if’ are used.

Enjoy!