In a vSphere environment, there are conditions (such as datastores running out of space) that you want to know about before things run out of control. In the datastores running out of space example, you would want to be warned before the datastore is full, so you can move some disks to another datastore to create extra free space on the datastore that is running out of space.
VMware vSphere provides alarms that trigger warnings and alerts when certain conditions are met. There are a lot of predefined alarms for almost every condition possible in vCenter Server. For example, there is the Datastore usage on disk alarm for datastores that will, by default, give you a warning if a datastore usage is more than 75 %and give you an alert if a datastore usage is more than 85 %. It is also possible to define actions such as Send a notification email that are executed when an alarm is triggered.
In PowerCLI, there are various cmdlets to modify alarm definitions and to create and modify alarm action triggers and alarm actions.
In the following screenshot of vSphere Web Client, you will see the Trigger states notification of the Datastore usage on disk alarm:
You can use the Get-AlarmDefinition cmdlet to retrieve the available alarm definitions. The syntax of this cmdlet is as follows:
Get-AlarmDefinition [-Id <String[]>] [[-Name] <String[]>] [[-Entity]
<VIObject[]>] [-Enabled [<Boolean>]] [-Server <VIServer[]>]
[<CommonParameters>]
The Get-AlarmDefinition cmdlet has no required parameters.
There are three possible ways to retrieve alarm definitions. You can do one of the following:
- Get a list of all of the available alarm definitions
- Filter the alarm definitions by name or entity
- Retrieve only the enabled alarm definitions
In the following example, we will retrieve the Datastore usage on disk alarm:
PowerCLI C:> Get-Alarmdefinition -Name 'Datastore usage on disk'
The output of the preceding command is as follows:
Name Description Enabled ---- ----------- ------- Datastore usage on disk Default alarm to monitor datastore... True
In the following screenshot of vSphere Web Client, you will see the alarm definition for the Datastore usage on disk alarm:
To modify alarm definitions, you can use the Set-AlarmDefinition cmdlet that gives the ability to change the name and description of an alarm definition, specify how often the alarm actions repeat if the alarm is active, and enable or disable the alarm. The Set-AlarmDefinition cmdlet has the following syntax:
Set-AlarmDefinition [-AlarmDefinition] <AlarmDefinition[]>
[-ActionRepeatMinutes <Int32>] [-Description <String>] [-Enabled
[<Boolean>]] [-Name <String>] [-Server <VIServer[]>] [-WhatIf]
[-Confirm] [<CommonParameters>]
The -AlarmDefinition parameter is required to modify an alarm definition.
In the following example, we will disable the Datastore usage on disk alarm:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> Set-AlarmDefinition -Enabled $false
The output of the preceding command is as follows:
Name Description Enabled ---- ----------- ------- Datastore usage on disk Default alarm to monitor datastore... False
If an alarm is triggered, you can send an e-mail notification, generate an SNMP trap, or run a script. These actions can be defined with the New-AlarmAction cmdlet. This cmdlet has the following syntaxes. The first parameter set is required to create alarm actions that send an e-mail:
New-AlarmAction [-AlarmDefinition] <AlarmDefinition> -Email [-Subject
<String>] -To <String[]> [-Cc <String[]>] [-Body <String>] [-Server
<VIServer[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
The second parameter set is to create alarm actions that run a script:
New-AlarmAction [-AlarmDefinition] <AlarmDefinition> -Script
-ScriptPath <String> [-Server <VIServer[]>] [-WhatIf] [-Confirm]
[<CommonParameters>]
The third parameter set is used to create alarm actions that generate an SNMP trap:
New-AlarmAction [-AlarmDefinition] <AlarmDefinition> -Snmp [-Server
<VIServer[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
As you can see, the New-AlarmAction cmdlet has three parameter sets, one for each type of alarm action you can define. The -AlarmDefinition parameter is always required to create an alarm action. To create a Send a notification email alarm action, the -Email and -To parameters are also required. To create a Send a notification trap alarm action, the -Snmp parameter is required. To create a Run a command alarm action, the -Script and -ScriptPath parameters are required.
In the first example, we will create a Send a notification e-mail alarm action for the Datastore usage on disk alarm:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> New-AlarmAction -Email -To [email protected] -Subject 'Datastore usage on disk alarm' -Body 'Datastore {targetName} usage is over its alarm limits'
The output of the preceding command lines is as follows:
ActionType Trigger ---------- ------- SendEmail ...
The {targetName} variable in the preceding example will substitute the name of the datastore in the subject and body of the e-mail. The variables that you can use are shown in the following table. The table is copied from the vSphere 6.5 documentation's Alarm Command-Line Parameters section at
http://pubs.vmware.com/vsphere-65/index.jsp#com.vmware.vsphere.monitoring.doc/GUID-B8DF4E10-89E3-409D-9111-AE405B7E5D2E_copy.html
:
|
Variable |
Description |
|
|
This is the name of the alarm that is triggered. |
|
|
This is a summary of the alarm declaration values. |
|
|
This is the text of the |
|
|
This is the alarm status after the alarm is triggered. |
|
|
This is the alarm status before the alarm is triggered. |
|
|
This is the inventory object on which the alarm is set. |
|
|
This is the name of the entity on which the alarm is triggered. |
|
|
This is a summary of the alarm trigger values. |
In the second example, we will create a Send a notification trap alarm action for the Datastore usage on disk alarm:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> New-AlarmAction -Snmp
The output of the preceding command is as follows:
ActionType Trigger ---------- ------- SendSNMP ...
In the third example, we will create a Run a command alarm action for the Datastore usage on disk alarm. The c:ScriptsDatastoreAlarm.cmd script has to run when the alarm is triggered:
Use the following command to create a Run a command alarm action for the Datastore usage on disk alarm:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> New-AlarmAction -Script -ScriptPath c:ScriptsDatastoreAlarm.cmd
The output of the preceding command is as follows:
ActionType Trigger ---------- ------- ExecuteScript ...
Note
You cannot specify a PowerShell or PowerCLI script as the value of the -ScriptPath parameter. Rather, you have to specify a batch file. Of course, you can call PowerShell from inside the batch file. For example, you can call the script c:scriptsAlarmAction.ps1 from a batch file with the following command:
echo.| powershell -command "&{c:scriptsAlarmAction.ps1}"
You can find more information in the VMware Knowledge Base article Unable to invoke PowerShell scripts as alarm action on vCenter Server 5.0 (2039574) at http://kb.vmware.com/kb/2039574 .
In the following screenshot of vSphere Web Client, you will see the alarm actions that we have created in the preceding examples:
Before you can send an e-mail as an alarm action, you have to specify an SMTP server and the e-mail address that will be used as the sender's address in the e-mails sent by vCenter Server. There are no PowerCLI cmdlets to do this. You have to use the vSphere API.
In the following example, we will configure the vCenter Server with smtpserver.blackmilktea.com as the address of the SMTP server and [email protected] as the sender's e-mail address. The following script uses the VpxSettings UpdateOptions() method to configure the SMTP server and the sender's e-mail address:
$OptionValue = New-Object VMware.Vim.OptionValue[] (2) $OptionValue[0] = New-Object VMware.Vim.OptionValue $OptionValue[0].key = 'mail.smtp.server' $OptionValue[0].value = 'smtpserver.blackmilktea.com' $OptionValue[1] = New-Object VMware.Vim.OptionValue $OptionValue[1].key = 'mail.sender' $OptionValue[1].value = '[email protected]' $VpxSettings = Get-View -Id 'OptionManager-VpxSettings' $VpxSettings.UpdateOptions($OptionValue)
In the following screenshot of the vCenter Server Mail settings (in vSphere Web Client), you will see the defined SMTP server address and sender's e-mail address in the Mail server and Mail sender text fields after executing the preceding PowerCLI script:
The Get-AlarmAction cmdlet will retrieve the alarm actions of the specified alarm definitions. The syntax of the Get-AlarmAction cmdlet is as follows:
Get-AlarmAction [[-AlarmDefinition] <AlarmDefinition[]>]
[-ActionType <ActionType[]>] [-Server <VIServer[]>]
[<CommonParameters>]
The Get-AlarmAction cmdlet has no required parameters.
In the following example, we will retrieve the alarm actions of the Datastore usage on disk alarm definition. Because the default output shows only the ActionType and Trigger properties, the output is piped to the Format-List -property * command to show all of the properties:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> Get-AlarmAction | Format-List -Property *
The output of the preceding command is as follows:
Body : Datastore {targetName} usage is over its alarm limits Cc : {} To : {[email protected]} Subject : Datastore usage on disk alarm ActionType : SendEmail AlarmDefinition : Datastore usage on disk Trigger : {Yellow -> Red (Once)} Uid : /VIServer=vsphere.local [email protected]:443 /Alarm=Alarm-alarm-8/SendEmailAction=-2028157226/ AlarmVersion : 134 Client : ActionType : SendSNMP AlarmDefinition : Datastore usage on disk Trigger : {Yellow -> Red (Once)} Uid : /VIServer=vsphere.local [email protected]:443 /Alarm=Alarm-alarm-8/SendSNMPAction=-1381748622/ AlarmVersion : 134 Client : ScriptFilePath : c:ScriptsDatastoreAlarm.cmd ActionType : ExecuteScript AlarmDefinition : Datastore usage on disk Trigger : {Yellow -> Red (Once)} Uid : /VIServer=vsphere.local [email protected]:443 /Alarm=Alarm-alarm-8/RunScriptAction=307617281/ AlarmVersion : 134 Client :
You can use the Remove-AlarmAction cmdlet to remove an alarm action. The Remove-AlarmAction cmdlet has the following syntax:
Remove-AlarmAction [-AlarmAction] <AlarmAction[]> [-WhatIf]
[-Confirm] [<CommonParameters>]
The -AlarmAction parameter is required to remove an alarm action.
In the following example, we will remove the SendSNMP alarm action from the Datastore usage on disk alarm definition:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> Get-AlarmAction -ActionType SendSNMP | >> Remove-AlarmAction -Confirm:$false
The preceding command does not return any output.
Every new alarm action will be triggered once the alarm state changes from warning (yellow) to alert (red). If you want to create additional alarm action triggers, you can use the New-AlarmActionTrigger cmdlet to create a new action trigger for the specified alarm action. The syntax of this cmdlet is as follows:
New-AlarmActionTrigger [-StartStatus] <InventoryItemStatus>
[-EndStatus] <InventoryItemStatus> -AlarmAction <AlarmAction>
[-Repeat] [-WhatIf] [-Confirm] [<CommonParameters>]
The -StartStatus, -EndStatus, and -AlarmAction parameters are required to create an alarm action trigger.
In the following example, we will create a new alarm action trigger for the SendEmail alarm action of the Datastore usage on disk alarm definition. The trigger is started when the alarm state changes from normal (green) to warning (yellow). The alarm action will be repeated once every hour until the alarm is acknowledged.
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> Get-AlarmAction -ActionType SendEmail | >> New-AlarmActionTrigger -StartStatus 'Green' -EndStatus 'Yellow' -Repeat
The output of the preceding command lines is as follows:
StartStatus EndStatus Repeat ----------- --------- ------ Green Yellow True
Now, use the following command to set the time intervals between the occurrences of the alarms:
PowerCLI C:> Set-AlarmDefinition 'Datastore usage on disk'
-ActionRepeatMinutes 60 -Enabled:$true
The output of the preceding command is as follows:
Name Description Enabled ---- ----------- ------- Datastore usage on disk Default alarm to monitor datastore... True
To retrieve alarm action triggers, you can use the Get-AlarmActionTrigger cmdlet. This cmdlet has the following syntax:
Get-AlarmActionTrigger [[-AlarmAction] <AlarmAction[]>]
[<CommonParameters>]
The Get-AlarmActionTrigger cmdlet has no required parameters.
In the following example, we will retrieve the alarm action triggers of the SendEmail alarm action of the Datastore usage on disk alarm definition:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> Get-AlarmAction -ActionType SendEmail | >> Get-AlarmActionTrigger
The output of the preceding command is as follows:
StartStatus EndStatus Repeat ----------- --------- ------ Yellow Red False Green Yellow True
In the following screenshot of the vSphere Web Client, you will see the Trigger states and Alarm actions notifications for the Datastore usage on disk alarm:
We can remove alarm action triggers using the Remove-AlarmActionTrigger cmdlet. The syntax of the Remove-AlarmActionTrigger cmdlet is as follows:
Remove-AlarmActionTrigger [-AlarmActionTrigger]
<AlarmActionTrigger[]> [-WhatIf] [-Confirm] [<CommonParameters>]
The -AlarmActionTrigger parameter is required to remove an alarm action trigger.
In the following example, the alarm action trigger with the start status Green will be removed from the SendEmail alarm action of the Datastore usage on disk alarm definition:
PowerCLI C:> Get-AlarmDefinition -Name 'Datastore usage on disk' | >> Get-AlarmAction -ActionType SendEmail | >> Get-AlarmActionTrigger | >> Where-Object {$_.StartStatus -eq 'Green'} | >> Remove-AlarmActionTrigger -Confirm:$false
The preceding command does not return any output.
An alarm action must have at least one alarm action trigger. You cannot remove the last one. If you try to remove the last alarm action trigger, you will get the following error message:
You cannot remove this AlarmActionTrigger. The AlarmAction must have at least one AlarmActionTrigger.