Public/guest-os.ps1
|
function New-CSGuestOs { <# .SYNOPSIS Adds a guest operating system type to CloudStack. .DESCRIPTION Wraps the addGuestOs API. Creates a new guest OS type under an OS category so it can be assigned to templates, ISOs, and instances. Optionally attach extra key/value details. .PARAMETER OsCategoryId ID of the OS category the new guest OS belongs to (see Get-CSOsCategory) .PARAMETER OsDisplayName Display name for the guest OS, for example 'Ubuntu 24.04' .PARAMETER Name Internal name for the guest OS .PARAMETER Details Extra key/value details as a hashtable .PARAMETER ForDisplay Whether the guest OS is shown to end users .EXAMPLE New-CSGuestOs -OsCategoryId 'category-uuid' -OsDisplayName 'Ubuntu 24.04' Adds a new guest OS type under the given category. .EXAMPLE New-CSGuestOs -OsCategoryId $catId -OsDisplayName 'Rocky Linux 10' -Name 'Rocky Linux 10' -ForDisplay Adds a named guest OS type and makes it visible to end users. #> [CmdletBinding()] param([Parameter(Mandatory=$true)][string]$OsCategoryId, [Parameter(Mandatory=$true)][string]$OsDisplayName, [string]$Name, [hashtable]$Details, [switch]$ForDisplay) $apiParams = @{ oscategoryid = $OsCategoryId; osdisplayname = $OsDisplayName } foreach ($key in @('Name','Details')) { if ($PSBoundParameters.ContainsKey($key)) { $apiParams[$key.ToLowerInvariant()] = (Get-Variable -Name $key -ValueOnly) } } if ($ForDisplay) { $apiParams['fordisplay'] = 'true' } Invoke-CSApiRequest -Command 'addGuestOs' -Parameters $apiParams } function New-CSGuestOsMapping { <# .SYNOPSIS Adds a hypervisor guest OS mapping. .DESCRIPTION Wraps the addGuestOsMapping API. Maps a CloudStack guest OS to the OS name a specific hypervisor version expects, so instances are created with the correct hypervisor guest OS setting. Identify the CloudStack guest OS by either -OsDisplayName or -OsTypeId. .PARAMETER Hypervisor The hypervisor the mapping is for: XenServer, KVM, or VMware .PARAMETER HypervisorVersion The hypervisor version the mapping applies to, for example '8.2.0' .PARAMETER OsNameForHypervisor The guest OS name as the hypervisor knows it, for example 'Ubuntu 24.04 LTS' .PARAMETER OsDisplayName The CloudStack guest OS display name to map. Use this or -OsTypeId. .PARAMETER OsTypeId The CloudStack guest OS type ID to map. Use this or -OsDisplayName. .PARAMETER Forced Overwrite an existing mapping for the same hypervisor/version .PARAMETER OsMappingCheckEnabled Validate the mapping against the hypervisor before saving it .EXAMPLE New-CSGuestOsMapping -Hypervisor KVM -HypervisorVersion '8.2.0' -OsNameForHypervisor 'Ubuntu 24.04 LTS' -OsDisplayName 'Ubuntu 24.04' Maps a CloudStack guest OS to a KVM guest OS name. .EXAMPLE New-CSGuestOsMapping -Hypervisor VMware -HypervisorVersion '8.0' -OsNameForHypervisor 'ubuntu64Guest' -OsTypeId $osTypeId -Forced Maps by OS type ID for VMware, overwriting any existing mapping. #> [CmdletBinding()] param([Parameter(Mandatory=$true)][ValidateSet('XenServer','KVM','VMware')][string]$Hypervisor, [Parameter(Mandatory=$true)][string]$HypervisorVersion, [Parameter(Mandatory=$true)][string]$OsNameForHypervisor, [string]$OsDisplayName, [string]$OsTypeId, [switch]$Forced, [switch]$OsMappingCheckEnabled) if (-not $PSBoundParameters.ContainsKey('OsDisplayName') -and -not $PSBoundParameters.ContainsKey('OsTypeId')) { throw 'Specify OsDisplayName or OsTypeId.' } $apiParams = @{ hypervisor = $Hypervisor; hypervisorversion = $HypervisorVersion; osnameforhypervisor = $OsNameForHypervisor } foreach ($key in @('OsDisplayName','OsTypeId')) { if ($PSBoundParameters.ContainsKey($key)) { $apiParams[$key.ToLowerInvariant()] = (Get-Variable -Name $key -ValueOnly) } } if ($Forced) { $apiParams['forced'] = 'true' }; if ($OsMappingCheckEnabled) { $apiParams['osmappingcheckenabled'] = 'true' } Invoke-CSApiRequest -Command 'addGuestOsMapping' -Parameters $apiParams } function Get-CSGuestOsMapping { <# .SYNOPSIS Lists guest OS mappings. .DESCRIPTION Wraps the listGuestOsMapping API, returning the mappings between CloudStack guest OS types and hypervisor-specific guest OS names. Filter by hypervisor, version, or the OS it maps. -HypervisorVersion requires -Hypervisor. .PARAMETER Hypervisor Filter by hypervisor: XenServer, KVM, or VMware .PARAMETER HypervisorVersion Filter by hypervisor version (requires -Hypervisor) .PARAMETER Id Filter by mapping ID .PARAMETER Keyword Filter by keyword .PARAMETER OsDisplayName Filter by the CloudStack guest OS display name .PARAMETER OsNameForHypervisor Filter by the hypervisor-specific guest OS name .PARAMETER OsTypeId Filter by the CloudStack guest OS type ID .PARAMETER Page Page number of results to return .PARAMETER PageSize Number of results per page .EXAMPLE Get-CSGuestOsMapping -Hypervisor KVM -HypervisorVersion '8.2.0' Lists the guest OS mappings for a specific KVM version. .EXAMPLE Get-CSGuestOsMapping -OsTypeId $osTypeId Lists every hypervisor mapping for one CloudStack guest OS type. #> [CmdletBinding()] param([ValidateSet('XenServer','KVM','VMware')][string]$Hypervisor, [string]$HypervisorVersion, [string]$Id, [string]$Keyword, [string]$OsDisplayName, [string]$OsNameForHypervisor, [string]$OsTypeId, [int]$Page, [int]$PageSize) if ($PSBoundParameters.ContainsKey('HypervisorVersion') -and -not $PSBoundParameters.ContainsKey('Hypervisor')) { throw 'HypervisorVersion requires Hypervisor.' } $apiParams = @{} foreach ($key in @('Hypervisor','HypervisorVersion','Id','Keyword','OsDisplayName','OsNameForHypervisor','OsTypeId','Page','PageSize')) { if ($PSBoundParameters.ContainsKey($key)) { $apiParams[$key.ToLowerInvariant()] = (Get-Variable -Name $key -ValueOnly) } } $response = Invoke-CSApiRequest -Command 'listGuestOsMapping' -Parameters $apiParams if ($response.listguestosmappingresponse.guestosmapping) { return $response.listguestosmappingresponse.guestosmapping } } function Get-CSOsCategory { <# .SYNOPSIS Lists guest OS categories. .DESCRIPTION Wraps the listOsCategories API. OS categories (Linux, Windows, and so on) group the guest OS types returned by Get-CSOsType. .PARAMETER Id Filter by OS category ID .PARAMETER Keyword Filter by keyword .PARAMETER Name Filter by category name .PARAMETER Page Page number of results to return .PARAMETER PageSize Number of results per page .EXAMPLE Get-CSOsCategory Lists every guest OS category. .EXAMPLE Get-CSOsCategory -Keyword 'Linux' Finds OS categories matching a keyword. #> [CmdletBinding()] param([string]$Id, [string]$Keyword, [string]$Name, [int]$Page, [int]$PageSize) $apiParams = @{}; foreach ($key in @('Id','Keyword','Name','Page','PageSize')) { if ($PSBoundParameters.ContainsKey($key)) { $apiParams[$key.ToLowerInvariant()] = (Get-Variable -Name $key -ValueOnly) } } $response = Invoke-CSApiRequest -Command 'listOsCategories' -Parameters $apiParams if ($response.listoscategoriesresponse.oscategory) { return $response.listoscategoriesresponse.oscategory } } function Get-CSOsType { <# .SYNOPSIS Lists guest OS types. .DESCRIPTION Wraps the listOsTypes API. Guest OS types are the OS values assigned to templates, ISOs, and instances; the returned id is what parameters such as -OsTypeId on the template and ISO commands expect. Filter by category, description, or ID. .PARAMETER Description Filter by OS description .PARAMETER ForDisplay Only OS types marked for display .PARAMETER Id Filter by OS type ID .PARAMETER Keyword Filter by keyword .PARAMETER OsCategoryId Filter by OS category ID (see Get-CSOsCategory) .PARAMETER Page Page number of results to return .PARAMETER PageSize Number of results per page .EXAMPLE Get-CSOsType -OsCategoryId 'category-uuid' Lists the guest OS types in one category. .EXAMPLE Get-CSOsType -Keyword 'Ubuntu 24' | Select-Object id, description Finds the OS type ID for a specific OS. #> [CmdletBinding()] param([string]$Description, [bool]$ForDisplay, [string]$Id, [string]$Keyword, [string]$OsCategoryId, [int]$Page, [int]$PageSize) $apiParams = @{}; foreach ($key in @('Description','ForDisplay','Id','Keyword','OsCategoryId','Page','PageSize')) { if ($PSBoundParameters.ContainsKey($key)) { $value = Get-Variable -Name $key -ValueOnly; if ($value -is [bool]) { $value = $value.ToString().ToLowerInvariant() }; $apiParams[$key.ToLowerInvariant()] = $value } } $response = Invoke-CSApiRequest -Command 'listOsTypes' -Parameters $apiParams if ($response.listostypesresponse.ostype) { return $response.listostypesresponse.ostype } } function Get-CSHypervisorGuestOsName { <# .SYNOPSIS Lists guest OS names supported by a hypervisor version. .DESCRIPTION Wraps the getHypervisorGuestOsNames API, returning the guest OS names a given hypervisor version recognizes. Useful for picking a valid -OsNameForHypervisor when creating a guest OS mapping. .PARAMETER Hypervisor The hypervisor to query: VMware or XenServer .PARAMETER HypervisorVersion The hypervisor version to query, for example '8.0' .PARAMETER Keyword Filter the returned names by keyword .EXAMPLE Get-CSHypervisorGuestOsName -Hypervisor VMware -HypervisorVersion '8.0' Lists the guest OS names a VMware version supports. .EXAMPLE Get-CSHypervisorGuestOsName -Hypervisor VMware -HypervisorVersion '8.0' -Keyword ubuntu Filters the supported guest OS names to those matching a keyword. #> [CmdletBinding()] param([Parameter(Mandatory=$true)][ValidateSet('VMware','XenServer')][string]$Hypervisor, [Parameter(Mandatory=$true)][string]$HypervisorVersion, [string]$Keyword) $apiParams = @{ hypervisor = $Hypervisor; hypervisorversion = $HypervisorVersion }; if ($PSBoundParameters.ContainsKey('Keyword')) { $apiParams['keyword'] = $Keyword } $response = Invoke-CSApiRequest -Command 'getHypervisorGuestOsNames' -Parameters $apiParams if ($response.gethypervisorguestosnamesresponse.guestoslist) { return $response.gethypervisorguestosnamesresponse.guestoslist } } function Remove-CSGuestOs { <# .SYNOPSIS Removes a guest OS type. .DESCRIPTION Wraps the removeGuestOs API. Deletes a guest OS type by ID. Accepts guest OS objects on the pipeline. .PARAMETER Id The guest OS type to remove. Binds from a piped object's id. .EXAMPLE Remove-CSGuestOs -Id 'os-type-uuid' Removes a guest OS type after confirmation. .EXAMPLE Get-CSOsType -Keyword 'Obsolete OS' | Remove-CSGuestOs Removes a guest OS type located by keyword. #> [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='High')] param([Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)][string]$Id) process { if ($PSCmdlet.ShouldProcess("guest OS $Id",'Remove')) { Invoke-CSApiRequest -Command 'removeGuestOs' -Parameters @{ id = $Id } } } } function Remove-CSGuestOsMapping { <# .SYNOPSIS Removes a hypervisor guest OS mapping. .DESCRIPTION Wraps the removeGuestOsMapping API. Deletes a guest OS mapping by ID. Accepts mapping objects on the pipeline. .PARAMETER Id The guest OS mapping to remove. Binds from a piped object's id. .EXAMPLE Remove-CSGuestOsMapping -Id 'mapping-uuid' Removes a guest OS mapping after confirmation. .EXAMPLE Get-CSGuestOsMapping -Hypervisor KVM -HypervisorVersion '8.2.0' | Remove-CSGuestOsMapping Removes the KVM mappings for a specific version. #> [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='High')] param([Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)][string]$Id) process { if ($PSCmdlet.ShouldProcess("guest OS mapping $Id",'Remove')) { Invoke-CSApiRequest -Command 'removeGuestOsMapping' -Parameters @{ id = $Id } } } } function Set-CSGuestOs { <# .SYNOPSIS Updates a guest OS type. .DESCRIPTION Wraps the updateGuestOs API. Changes a guest OS type's display name and optional details. Accepts guest OS objects on the pipeline. .PARAMETER Id The guest OS type to update. Binds from a piped object's id. .PARAMETER OsDisplayName New display name for the guest OS .PARAMETER Details Replacement key/value details as a hashtable .PARAMETER ForDisplay Whether the guest OS is shown to end users .EXAMPLE Set-CSGuestOs -Id 'os-type-uuid' -OsDisplayName 'Ubuntu 24.04 LTS' Renames a guest OS type. .EXAMPLE Get-CSOsType -Keyword 'Ubuntu 24' | Set-CSGuestOs -OsDisplayName 'Ubuntu 24.04 LTS' -ForDisplay $true Renames a guest OS located by keyword and makes it visible. #> [CmdletBinding()] param([Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)][string]$Id, [Parameter(Mandatory=$true)][string]$OsDisplayName, [hashtable]$Details, [bool]$ForDisplay) process { $apiParams = @{ id = $Id; osdisplayname = $OsDisplayName }; foreach ($key in @('Details','ForDisplay')) { if ($PSBoundParameters.ContainsKey($key)) { $value = Get-Variable -Name $key -ValueOnly; if ($value -is [bool]) { $value = $value.ToString().ToLowerInvariant() }; $apiParams[$key.ToLowerInvariant()] = $value } } Invoke-CSApiRequest -Command 'updateGuestOs' -Parameters $apiParams } } function Set-CSGuestOsMapping { <# .SYNOPSIS Updates a hypervisor guest OS mapping. .DESCRIPTION Wraps the updateGuestOsMapping API. Changes the hypervisor-specific guest OS name a mapping points to. Accepts mapping objects on the pipeline. .PARAMETER Id The guest OS mapping to update. Binds from a piped object's id. .PARAMETER OsNameForHypervisor New hypervisor-specific guest OS name .PARAMETER OsMappingCheckEnabled Validate the new name against the hypervisor before saving .EXAMPLE Set-CSGuestOsMapping -Id 'mapping-uuid' -OsNameForHypervisor 'Ubuntu 24.04 LTS' Updates the hypervisor guest OS name a mapping uses. .EXAMPLE Get-CSGuestOsMapping -OsTypeId $osTypeId | Set-CSGuestOsMapping -OsNameForHypervisor 'ubuntu64Guest' -OsMappingCheckEnabled $true Updates a mapping located by OS type and validates it against the hypervisor. #> [CmdletBinding()] param([Parameter(Mandatory=$true, ValueFromPipelineByPropertyName=$true)][string]$Id, [Parameter(Mandatory=$true)][string]$OsNameForHypervisor, [bool]$OsMappingCheckEnabled) process { $apiParams = @{ id = $Id; osnameforhypervisor = $OsNameForHypervisor }; if ($PSBoundParameters.ContainsKey('OsMappingCheckEnabled')) { $apiParams['osmappingcheckenabled'] = $OsMappingCheckEnabled.ToString().ToLowerInvariant() } Invoke-CSApiRequest -Command 'updateGuestOsMapping' -Parameters $apiParams } } |