Quickstart

The steps below will get you up and running with POSHOrigin.

1. Setup

   Run through the setup / initialization of POSHOrigin by following this guide.

2. Create a configuration

   We're going to create a simple configuration using the example DSC resources included in the POSHOrigin module. These resources (poshorigin:poshfolder and poshorigin:poshfile) create or delete files and folders. I know what you're thinking, "Big deal, I can do that with DSC already." In your head, just replace poshfolder or poshfile with virtual machine or DNS record and you'll get the idea.

   The real power comes when you use custom DSC resources to provision REAL infrastructure.

   Create the file called example.ps1 under *$env:userprofile\.poshorigin\configs* with the following contents:

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

3. Load a configuration

   Now lets read in this configuration by running the following commands:

   cd $env:userprofile\.poshorigin\configs
   $config = Get-POSHOriginConfig -Path '.\example.ps1' -Verbose

4. Exploring the configuration

   Get-POSHOriginConfig returned an object called $config. Take a look at that variable to see what we have.

5. Test a configuration

   Now let's test that are "infrastructure" (really just a folder in this case) is compliant with our configuration.

   $config | Invoke-POSHOrigin -Verbose -WhatIf

6. Execute a configuration

   Based on the test above, our "infrastructure" is not compliant. Let's make it so!

   $config | Invoke-POSHOrigin -Verbose

   We should see that POSHOrigin compiled a DSC configuration and applied it to our machine. The POSHOrigin example resource 'poshorigin:poshfolder' was executed and created a folder called 'c:\folder01'.

7. Use a defaults file

   Create a new file called folder_defaults.psd1 in *$env:userprofile\.poshorigin\configs* with the following contents:

   @{
       description = 'this is an example folder'
       ensure = 'absent'
       path = 'c:\'
   }

   Now modify example.ps1 to look like the following:

   resource 'poshorigin:poshfolder' 'folder01' @{
       defaults = '.\folder_defaults.psd1'
   }

   Notice the following line in folder_defaults.psd1. We're telling the poshorigin:poshfolder DSC resource that the folder should NOT exist.

   ensure = 'absent'

   Now read and execute the configuration again:

   $config = Get-POSHOriginConfig -Path '.\example.ps1' -Verbose
   $config | Invoke-POSHOrigin -Verbose

   Notice that the folder was deleted. Imagine that instead of working with a folder or file, we were actually deleting a VM or load balancer resource.

8. Use a configuration snippet

   Create a new folder called common inside your POSHOrigin repository:

   New-Item -Type Directory -Path "$env:UserProfile\.poshorigin\configs\common"

   Create a file called folder_options.psd1 inside the common directory we just created with the following contents:

   @(
      'someproperty'
      'someotherproperty'
      'yetanotherproperty'
   )

   Modify your folder_default.psd1 file to ensure the folder is present again.

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

   Now edit your example.ps1 file to look like the following:

   resource 'poshorigin:poshfolder' 'folder01' @{
       defaults = '.\folder_defaults.psd1'
       options = Get-POSHDefault 'folder_options'
   }

   Read and execute the configuration again:

   $config = Get-POSHOriginConfig -Path '.\example.ps1' -Verbose
   $config | Invoke-POSHOrigin -Verbose

   Notice that the folder is created again.

   What did the options we added to the poshorigin:poshfolder resource do? Well, nothing :) The poshorigin:poshfolder resource doesn't know what to do with an options parameter so it just ignores it. But if the resource you're working on has a parameter that accepts a hashtable or array, Using configuration snippets is a good way to standardize your configurations and helps with sharing your desired configuration across resources.

---

That's it for the quickstart. Happy provisioning!