Public/vm-tags.ps1
|
function New-CSVMTag { <# .SYNOPSIS Adds a resource tag to a virtual machine. .DESCRIPTION Wraps createTags for the UserVm resource type, attaching one key/value tag to a VM. Accepts -VM (a name or a piped VM object) or -VirtualMachineId. Tags are created asynchronously. .PARAMETER VirtualMachineId The ID of the VM to tag .PARAMETER VM A VM name or VM object. Binds from the pipeline. .PARAMETER Key The tag key .PARAMETER Value The tag value .PARAMETER Customer Optional customer identifier stored with the tag .EXAMPLE New-CSVMTag -VM 'web-01' -Key 'environment' -Value 'production' Tags web-01 with environment=production. .EXAMPLE Get-CSVM -Keyword 'web-' | New-CSVMTag -Key 'tier' -Value 'frontend' Tags every web VM with tier=frontend. #> [CmdletBinding()] param( [Parameter(Mandatory=$false)][string]$VirtualMachineId, [Parameter(Mandatory=$false, Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Alias('Name')][object]$VM, [Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()][string]$Key, [Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()][string]$Value, [Parameter(Mandatory=$false)][string]$Customer ) process { $resolvedId = Resolve-CSVMTagId -VirtualMachineId $VirtualMachineId -VM $VM $apiParams = @{ resourceids = $resolvedId resourcetype = 'UserVm' 'tags[0].key' = $Key 'tags[0].value' = $Value } if ($PSBoundParameters.ContainsKey('Customer')) { $apiParams['customer'] = $Customer } $response = Invoke-CSApiRequest -Command 'createTags' -Parameters $apiParams if ($response.createtagsresponse.jobid) { Write-Verbose "Tags created. Job ID: $($response.createtagsresponse.jobid)" } } } function Remove-CSVMTag { <# .SYNOPSIS Removes a resource tag from a virtual machine. .DESCRIPTION Wraps deleteTags for the UserVm resource type, removing the tag identified by -Key and -Value from a VM. Accepts -VM (a name or a piped VM object) or -VirtualMachineId. Uses ShouldProcess, so -WhatIf and -Confirm are supported. .PARAMETER VirtualMachineId The ID of the VM to untag .PARAMETER VM A VM name or VM object. Binds from the pipeline. .PARAMETER Key The key of the tag to remove .PARAMETER Value The value of the tag to remove .EXAMPLE Remove-CSVMTag -VM 'web-01' -Key 'environment' -Value 'production' Removes the environment=production tag from web-01. .EXAMPLE Get-CSVM -Keyword 'web-' | Remove-CSVMTag -Key 'tier' -Value 'frontend' -Confirm:$false Removes a tag from every web VM without prompting. #> [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='Medium')] param( [Parameter(Mandatory=$false)][string]$VirtualMachineId, [Parameter(Mandatory=$false, Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Alias('Name')][object]$VM, [Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()][string]$Key, [Parameter(Mandatory=$true)][ValidateNotNullOrEmpty()][string]$Value ) process { $resolvedId = Resolve-CSVMTagId -VirtualMachineId $VirtualMachineId -VM $VM if ($PSCmdlet.ShouldProcess("VM $resolvedId", "Remove tag '$Key=$Value'")) { $apiParams = @{ resourceids = $resolvedId resourcetype = 'UserVm' 'tags[0].key' = $Key 'tags[0].value' = $Value } [void](Invoke-CSApiRequest -Command 'deleteTags' -Parameters $apiParams) } } } function Get-CSVMTag { <# .SYNOPSIS Lists the resource tags on virtual machines. .DESCRIPTION Wraps listTags for the UserVm resource type. With -VM or -VirtualMachineId it lists one VM's tags; otherwise it lists VM tags across the account. Filter by -Key/-Value. Accepts -VM (a name or a piped VM object) or -VirtualMachineId. .PARAMETER VirtualMachineId List tags for the VM with this ID .PARAMETER VM A VM name or VM object. Binds from the pipeline. .PARAMETER Key Only tags with this key .PARAMETER Value Only tags with this value .PARAMETER Customer Only tags with this customer identifier .PARAMETER ListAll List VM tags across every account the caller can see .PARAMETER Page Page number of results to return .PARAMETER PageSize Number of results per page .EXAMPLE Get-CSVMTag -VM 'web-01' Lists every tag on web-01. .EXAMPLE Get-CSVMTag -Key 'environment' -Value 'production' -ListAll Finds every VM tagged environment=production. #> [CmdletBinding()] param( [Parameter(Mandatory=$false)][string]$VirtualMachineId, [Parameter(Mandatory=$false, Position=0, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)] [Alias('Name')][object]$VM, [Parameter(Mandatory=$false)][string]$Key, [Parameter(Mandatory=$false)][string]$Value, [Parameter(Mandatory=$false)][string]$Customer, [Parameter(Mandatory=$false)][switch]$ListAll, [Parameter(Mandatory=$false)][ValidateRange(1, [int]::MaxValue)][int]$Page, [Parameter(Mandatory=$false)][ValidateRange(1, [int]::MaxValue)][int]$PageSize ) process { $resolvedId = $VirtualMachineId if ($null -ne $VM) { $resolvedId = Resolve-CSVMTagId -VirtualMachineId $VirtualMachineId -VM $VM } $apiParams = @{ resourcetype = 'UserVm' } if ($null -ne $resolvedId -and $resolvedId -ne '') { $apiParams['resourceid'] = $resolvedId } if ($PSBoundParameters.ContainsKey('Key')) { $apiParams['key'] = $Key } if ($PSBoundParameters.ContainsKey('Value')) { $apiParams['value'] = $Value } if ($PSBoundParameters.ContainsKey('Customer')) { $apiParams['customer'] = $Customer } if ($ListAll) { $apiParams['listall'] = 'true' } if ($PSBoundParameters.ContainsKey('Page')) { $apiParams['page'] = $Page } if ($PSBoundParameters.ContainsKey('PageSize')) { $apiParams['pagesize'] = $PageSize } $response = Invoke-CSApiRequest -Command 'listTags' -Parameters $apiParams if ($null -ne $response.listtagsresponse.tag) { return @($response.listtagsresponse.tag) } } } |