Version information
This version is compatible with:
- Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
- Puppet >= 6.0.0 < 8.0.0
Start using this module
Add this module to your Puppetfile:
mod 'dsc-xhyper_v', '3.5.0-0-1'
Learn more about managing modules with a PuppetfileDocumentation
Table of Contents
Description
This is an auto-generated module, using the Puppet DSC Builder to vendor and expose the PowerShell module's DSC resources as Puppet resources. The functionality of this module comes entirely from the vendored PowerShell resources, which are pinned at v3.5.0.0. The PowerShell module describes itself like this:
Module with DSC Resources for Hyper-V area
For information on troubleshooting to determine whether any encountered problems are with the Puppet wrapper or the DSC resource, see the troubleshooting section below.
Requirements
This module, like all auto-generated Puppetized DSC modules, relies on two important technologies in the Puppet stack: the Puppet Resource API and the puppetlabs/pwshlib Puppet module.
The Resource API provides a simplified option for writing types and providers and is responsible for how this module is structured. The Resource API ships inside of Puppet starting with version 6. While it is technically possible to add the Resource API functionality to Puppet 5.5.x, the DSC functionality has not been tested in this setup. For more information on the Resource API, review the documentation.
The module also depends on the pwshlib module. This Puppet module includes two important things: the ruby-pwsh library for running PowerShell code from ruby and the base provider for DSC resources, which this module leverages.
All of the actual work being done to call the DSC resources vendored with this module is in this file from the pwshlib module. This is important for troubleshooting and bug reporting, but doesn't impact your use of the module except that the end result will be that nothing works, as the dependency is not installed alongside this module!
Usage
You can specify any of the DSC resources from this module like a normal Puppet resource in your manifests. The examples below use DSC resources from from the PowerShellGet repository, regardless of what module you're looking at here; the syntax, not the specifics, is what's important.
For reference documentation about the DSC resources exposed in this module, see the Reference Forge tab, or the REFERENCE.md file.
# Include a meaningful title for your resource declaration
dsc_psrepository { 'Add team module repo':
dsc_name => 'foo',
dsc_ensure => present,
# This location is nonsense, can be any valid folder on your
# machine or in a share, any location the SourceLocation param
# for the DSC resource will accept.
dsc_sourcelocation => 'C:\Program Files',
# You must always pass an enum fully lower-cased;
# Puppet is case sensitive even when PowerShell isn't
dsc_installationpolicy => untrusted,
}
dsc_psrepository { 'Trust public gallery':
dsc_name => 'PSGallery',
dsc_ensure => present,
dsc_installationpolicy => trusted,
}
dsc_psmodule { 'Make Ruby manageable via uru':
dsc_name => 'RubyInstaller',
dsc_ensure => present,
}
For more information about using a built module, check out our narrative documentation.
Properties
Note that the only properties specified in a resource declaration which are passed to Invoke-Dsc are all prepended with dsc.
If a property does _not start with dsc_ it is used to control how Puppet interacts with DSC/other Puppet resources - for example,
specifying a unique name for the resource for Puppet to distinguish between declarations or Puppet metaparameters (notifies,
before, etc).
Troubleshooting
In general, there are three broad categories of problems:
- Problems with the way the underlying DSC resource works.
- Problems with the type definition, where you can't specify a valid set of properties for the DSC resource
- Problems with calling the underlying DSC resource - the parameters aren't being passed correctly or the resource can't be found
Unfortunately, problems with the way the underlying DSC resource works are something we can't help directly with. You'll need to file an issue with the upstream maintainers for the PowerShell module.
Problems with the type definition are when a value that should be valid according to the DSC resource's documentation and code is not accepted by the Puppet wrapper. If and when you run across one of these, please file an issue with the Puppet DSC Builder; this is where the conversion happens and once we know of a problem we can fix it and regenerate the Puppet modules. To help us identify the issue, please specify the DSC module, version, resource, property and values that are giving you issues. Once a fix is available we will regenerate and release updated versions of this Puppet wrapper.
Problems with calling the underlying DSC resource become apparent by comparing <value passed in in puppet>
with <value received by DSC>
.
In this case, please file an issue with the puppetlabs/pwshlib module, which is where the DSC base provider actually lives.
We'll investigate and prioritize a fix and update the puppetlabs/pwshlib module.
Updating to the pwshlib version with the fix will immediately take advantage of the improved functionality without waiting for this module to be reconverted and published.
For specific information on troubleshooting a generated module, check the troubleshooting guide for the puppet.dsc module.
Known Limitations
Currently, because of the way Puppet caches files on agents, use of the legacy puppetlabs-dsc
module is not compatible with this or any auto-generated DSC module.
Inclusion of both will lead to pluginsync conflicts.
Reference
Table of Contents
Resource types
dsc_xvhd
: The DSC xVHD resource type. Automatically generated from version 3.5.0.0dsc_xvhdfile
: The DSC xVhdFile resource type. Automatically generated from version 3.5.0.0dsc_xvmhyperv
: The DSC xVMHyperV resource type. Automatically generated from version 3.5.0.0dsc_xvmswitch
: The DSC xVMSwitch resource type. Automatically generated from version 3.5.0.0
Resource types
dsc_xvhd
The DSC xVHD resource type. Automatically generated from version 3.5.0.0
Properties
The following properties are available in the dsc_xvhd
type.
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
Should the VHD be created or deleted
dsc_filesizebytes
Data type: Optional[Integer[0, 18446744073709551615]]
Current size of the VHD
dsc_generation
Data type: Optional[Enum['Vhd', 'Vhdx']]
Virtual disk format - Vhd or Vhdx
dsc_id
Data type: Optional[String]
Virtual Disk Identifier
dsc_isattached
Data type: Optional[Boolean]
Is the VHD attached to a VM or not
dsc_maximumsizebytes
Data type: Optional[Integer[0, 18446744073709551615]]
Maximum size of Vhd to be created
dsc_parentpath
Data type: Optional[String]
Parent VHD file path, for differencing disk
dsc_type
Data type: Optional[String]
Type of Vhd - Dynamic, Fixed, Differencing
Parameters
The following parameters are available in the dsc_xvhd
type.
dsc_name
namevar
Data type: String
Name of the VHD File
dsc_path
namevar
Data type: String
Folder where the VHD will be created
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xvhdfile
The DSC xVhdFile resource type. Automatically generated from version 3.5.0.0
Properties
The following properties are available in the dsc_xvhdfile
type.
dsc_checksum
Data type: Optional[Enum['ModifiedDate', 'SHA-1', 'SHA-256', 'SHA-512']]
dsc_filedirectory
Data type: Array[Struct[{ type => Optional[Enum['File', 'Directory']], ensure => Optional[Enum['Present', 'Absent']], content => Optional[String], destinationpath => String, force => Optional[Boolean], sourcepath => Optional[String], attributes => Optional[Array[Enum['ReadOnly', 'Hidden', 'System', 'Archive']]], recurse => Optional[Boolean] }]]
The FileDirectory objects to copy to the VHD
Parameters
The following parameters are available in the dsc_xvhdfile
type.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_vhdpath
namevar
Data type: String
Path to the VHD
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xvmhyperv
The DSC xVMHyperV resource type. Automatically generated from version 3.5.0.0
Properties
The following properties are available in the dsc_xvmhyperv
type.
dsc_cpuusage
Data type: Optional[Integer[0, 4294967295]]
CPU Usage of the VM
dsc_creationtime
Data type: Optional[Timestamp]
Creation time of the VM
dsc_enableguestservice
Data type: Optional[Boolean]
Enable Guest Service Interface for the VM.
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
Should the VM be created or deleted
dsc_generation
Data type: Optional[Integer[0, 4294967295]]
Virtual machine generation
dsc_hasdynamicmemory
Data type: Optional[Boolean]
Does VM has dynamic memory enabled
dsc_id
Data type: Optional[String]
VM unique ID
dsc_macaddress
Data type: Optional[Array[String]]
MAC address(es) of the VM NICs.
dsc_maximummemory
Data type: Optional[Integer[0, 18446744073709551615]]
Maximum RAM for the VM. This enable dynamic memory.
dsc_memoryassigned
Data type: Optional[Integer[0, 18446744073709551615]]
Memory assigned to the VM
dsc_minimummemory
Data type: Optional[Integer[0, 18446744073709551615]]
Minimum RAM for the VM. This enables dynamic memory.
dsc_networkadapters
Data type: Optional[Array[String]]
Network adapters' IP addresses of the VM
dsc_notes
Data type: Optional[String]
Notes about the VM.
dsc_path
Data type: Optional[String]
Folder where the VM data will be stored
dsc_processorcount
Data type: Optional[Integer[0, 4294967295]]
Processor count for the VM
dsc_restartifneeded
Data type: Optional[Boolean]
If specified, shutdowns and restarts the VM as needed for property changes
dsc_secureboot
Data type: Optional[Boolean]
Enable secure boot for Generation 2 VMs.
dsc_startupmemory
Data type: Optional[Integer[0, 18446744073709551615]]
Startup RAM for the VM.
dsc_state
Data type: Optional[Enum['Running', 'Paused', 'Off']]
State of the VM.
dsc_status
Data type: Optional[String]
Status of the VM
dsc_switchname
Data type: Optional[Array[String]]
Virtual switch(es) associated with the VM
dsc_uptime
Data type: Optional[String]
Uptime of the VM
dsc_vhdpath
Data type: String
VHD associated with the VM
dsc_waitforip
Data type: Optional[Boolean]
Waits for VM to get valid IP address.
Parameters
The following parameters are available in the dsc_xvmhyperv
type.
dsc_name
namevar
Data type: String
Name of the VM
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xvmswitch
The DSC xVMSwitch resource type. Automatically generated from version 3.5.0.0
Properties
The following properties are available in the dsc_xvmswitch
type.
dsc_allowmanagementos
Data type: Optional[Boolean]
Specify if the VM host has access to the physical NIC
dsc_bandwidthreservationmode
Data type: Optional[Enum['Default', 'Weight', 'Absolute', 'None', 'NA']]
Type of Bandwidth Reservation Mode to use for the switch
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
Whether switch should be present or absent
dsc_id
Data type: Optional[String]
Unique ID for the switch
dsc_netadapterinterfacedescription
Data type: Optional[String]
Description of the network interface
dsc_netadaptername
Data type: Optional[String]
Network adapter name for external switch type
Parameters
The following parameters are available in the dsc_xvmswitch
type.
dsc_name
namevar
Data type: String
Name of the VM Switch
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_type
namevar
Data type: Enum['External', 'Internal', 'Private']
Type of switch
name
namevar
Data type: String
Description of the purpose for this resource declaration.
-
Converted appveyor.yml to install Pester from PSGallery instead of from Chocolatey.
-
MSFT_xVMHyperV: Fixed bug in Test-TargetResource throwing when a Vhd"s ParentPath property was null.
Dependencies
- puppetlabs/pwshlib (>= 0.7.0 < 2.0.0)