Modules

POSHOrigin modules are a way to define a set of resource configurations as a single unit. Modules can be used to create reusable packages of resources and also allow logic to be included in the module to produce resources based on provided inputs. They are also useful for resource organization.

A POSHOrigin module is essentially just a folder with one or more files containing POSHOrigin resource definitions. It's possible to organize a module in many different ways.

Simple Module Example

To create a new module, create a folder with one or more POSHOrigin resources in .ps1 files. In this example, we will create a module called MyModule that will include resources to create folders and/or files.

• MyModule\
  • folders.ps1
  • files.ps1

folders.ps1

resource 'poshorigin:poshfolder' 'folder01' @{
    description = 'this is an example folder'
    ensure = 'present'
    path = 'c:\'
}

files.ps1

resource 'poshorigin:poshfile' 'file1' @{
    name = 'file1.txt'
    description = 'this is an example file'
    ensure = 'present'
    path = 'c:\folder01'
    contents = 'this is some content'
    dependson = '[poshfolder]folder01'
}

resource 'poshorigin:poshfile' 'file2' @{
    name = 'file2.txt'
    description = 'this is another example file'
    ensure = 'present'
    path = 'c:\folder01'
    contents = 'this is some more content'
    dependson = '[poshfolder]folder01'
}

To use this module, create your main POSHOrigin file outside the module directory and include this code:

MyResources.ps1

module 'MyModule' @{
    source = '.\MyModule'
}

When you read in the configuration from MyResources.ps1. POSHOrigin will load all the files included in the module as well.

$resources = Get-POSHOriginConfig -Path .\MyResources.ps1 -Verbose

Source

The only required properties when calling a module are an arbitrary name to give the module definition, and the source property which tells POSHOrigin where to find the module. The source property can be a folder/file path that is accessible by the user (this can be a local or remote SMB path) or can be a URL to a git repository. In the case of a git URL, git.exe must be installed on the system and be included in $env:path.

Module Properties

It's also possible to include logic in modules as well. Based on parameters passed to the module, different sets of resources can be executed or values for resource properties can change. Advanced logic can be included in modules to produce many types of configured based on provided inputs.

Example Module with logic

Create a new module called AdvModule with the following configuration:

• AdvModule\
  • AdvModule.ps1
  • resource.ps1

AdvModule.ps1

param(
    [parameter(mandatory)]
    [string]$Prefix,

    [string]$Path,

    [parameter(mandatory)]
    [int]$Count
)

(1..$Count) | % {
    . .\resources.ps1 @PSBoundParameters
}

resource.ps1

param(
    [string]$Prefix,

    [string]$Path
)

resource 'poshorigin:poshfolder' "$($prefix)Folder" {
    path = (if ($PSBoundParameters.ContainsKey('Path')) { $Path } else { 'c:\' }
}

Now to use this module, create your main POSHOrigin file outside of this module directory and include the following code:

MyAdvModule.ps1

module 'AdvModule' @{
    source = './AdvModule'
    prefix = 'Adv'
    count = 5
}

module 'AdvModule2' @{
    source = './AdvModule'
    prefix = 'asdf'
    count = 2
}