en-us/about_Puppet.Dsc.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
TOPIC
    about puppet.dsc
 
SHORT DESCRIPTION
    This module provides a means of converting PowerShell DSC Resources into
    Puppet types and providers.
 
LONG DESCRIPTION
    This module provides a means of converting a PowerShell module containing
    DSC Resources into a Puppet module which vendors those DSC Resources as
    Puppet types and providers.
    In general, this module:
    1. Scaffolds out a new Puppet module 1. Downloads a copy of the specified
    PowerShell DSC Resource module and vendors it (and all of its dependencies)
    into the Puppet module 1. Updates the Puppet module based on the PowerShell
    module's metadata 1. Converts each DSC Resource into a Puppet Resource API
    type 1. Generates the appropriate Puppet types and providers files in the
    Puppet module 1.Generates the reference documentation in the Puppet module
 
Scaffolding the Puppet module
    This module uses the [Puppet Development Kit (PDK)][pdk] to initialize a
    Puppet module, ensuring that the puppetized PowerShell module is a valid and
    standardized Puppet module.
    This means that the Puppet module can include all of the normal metadata and
    documentation as any other Puppet module you might find on the [Puppet
    Forge][forge].
 
Vendoring the PowerShell module
    A puppetized PowerShell DSC module vendors that PowerShell module and any
    dependencies it has into the new Puppet module. This means you are not
    responsible for shipping any external code to your managed nodes - as with
    other Puppet modules, everything you need is "in the box," either in the
    generated module or the [Puppet pwshlib module][pwshlib] on which it depends.
    This also means that you don't have to manage any additional versions or
    worry about cross-version contamination: Puppet is only and always going to
    use the vendored resources, not whatever else may or may not be on the
    target node!
 
Updating the Puppet module
    This module takes care of updating the Puppet module with information from
    the PowerShell module:
    - It writes a README for the Puppet module which stipulates information,
    dependencies, and points both to this PowerShell module and the one it has vendored.
    - It updates the Puppet module fixtures, ensuring that if all you have is
    the PDK and this PowerShell module, you can set up and functionally test the
    Puppetized module.
    - It updates the Puppet module's metadata, pinning the version of the Puppet
    module to match the PowerShell module and inserting some useful metadata for troubleshooting.
     It also sets the issues and project URLs
    not
    to Puppet-owned links, but to the upstream PowerShell module's settings.
 
Converting the DSC Resources to Puppet types
    The heavy lifting for this module happens in the
    `ConvertTo-PuppetResourceApi` function, which introspects on DSC Resources,
    parses them, and creates a Puppetized representation of those resources.
    The architecture of this process is described more in depth in
    [about_Puppetization][about_Puppetization].
 
Writing the types and providers
    The module uses a few small functions which include here-strings to to write
    the appropriate files. `Get-TypeContent` takes the information parsed in the
    `ConvertTo-PuppetResourceApi` function and uses it to write the Puppet
    Resource API type file, which includes all of the appropriate metadata,
    parameters, and documentation. The `Get-ProviderContent` function fills out
    a very small provider file; this is because all of the actual provider
    functionality lives in the
    `dsc_base_provider`
    module. The provider written in the Puppetized module is merely an inheritor
    of that base provider with the appropriate name.
 
Writing the reference documentation
    Next, the module uses the PDK to fill out all of the appropriate reference
    documentation based on the type files from the prior step. This ensures that
    the reference docs show up on the forge and in a single markdown document
    that you can review if you download the Puppetized module.
 
Finally
    With all of these actions completed, you have vendored and converted a
    PowerShell module with DSC Resources into a Puppet module, including all of
    the appropriate documents and metadata for troubleshooting and use. From
    that point, you can use the `Publish-PuppetModule` function to push your new
    module to the public forge or your own repository!
    [pdk]: https://puppet.com/try-puppet/puppet-development-kit/ [forge]:
    https://forge.puppet.com [about_puppetization]:
    https://github.com/puppetlabs/PuppetDscBuilder/blob/master/docs/about_Puppetization.md
    [base_provider]:
    https://github.com/puppetlabs/ruby-pwsh/blob/master/lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb
    [pwshlib]: https://forge.puppet.com/puppetlabs/pwshlib