Skip to content

Edits to grammar, markdown, and format to match current styleguide. #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 16, 2015
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 65 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
1. [Overview](#overview)
2. [Module Description - What the module does and why it is useful](#module-description)
3. [Setup - The basics of getting started with powershell](#setup)
* [Setup requirements](#setup-requirements)
* [Beginning with powershell](#beginning-with-powershell)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
Expand All @@ -17,95 +18,116 @@ This module adds a new exec provider capable of executing PowerShell commands.

##Module Description

Puppet provides a built-in `exec` type that is capable of executing commands. This module adds a `powershell` provider to the `exec` type, which enables all of the `exec` parameters, such as `creates`, `onlyif`, `unless`, etc. This module is particularly helpful if you need to run PowerShell commands but don't know the details about how PowerShell is executed, since you can technically run PowerShell commands in Puppet without the module.
Puppet provides a built-in `exec` type that is capable of executing commands. This module adds a `powershell` provider to the `exec` type, which enables `exec` parameters, listed below. This module is particularly helpful if you need to run PowerShell commands but don't know the details about how PowerShell is executed, since you can technically run PowerShell commands in Puppet without the module.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we link to the parameters section in the listed below?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's already a link in the ToC to the reference, so a link is not necessary here. We're trying to avoid excessive linking in the readmes. The "listed below" was added in conjunction with the removal of the link to exec's documentation to help clarify we're specifically listing relevant parameters in the readme.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


##Setup

###Setup Requirements
This module requires PowerShell to be installed and the `powershell.exe` to be available in the system PATH.

###Beginning with powershell

The powershell module adapts the Puppet
[exec](http://docs.puppetlabs.com/references/stable/type.html#exec)
resource to run PowerShell commands. To get started with the module, simply install it and declare 'powershell' in `provider` with the applicable command.
The powershell module adapts the Puppet [exec](http://docs.puppetlabs.com/references/stable/type.html#exec) resource to run PowerShell commands. To get started, simply install the module and declare 'powershell' in `provider` with the applicable command.

```
~~~
exec { 'RESOURCENAME':
command => '$(SOMECOMMAND)',
provider => powershell,
}
```
~~~

##Usage

When using `exec` resources with the `powershell` provider, the `command` parameter must be single-quoted to prevent Puppet from interpolating `$(..)`.

For instance, if you wanted to rename the Guest account
For instance, if you wanted to rename the Guest account:

```
~~~
exec { 'rename-guest':
command => '$(Get-WMIObject Win32_UserAccount -Filter "Name=\'guest\'").Rename("new-guest")',
unless => 'if (Get-WmiObject Win32_UserAccount -Filter "Name=\'guest\'") { exit 1 }',
provider => powershell,
}
```
~~~

Note that the example uses the `unless` parameter to make the resource idempotent. The `command` is only executed if the Guest account does not exist, as indicated by
`unless` returning 0.
Note that the example uses the `unless` parameter to make the resource idempotent. The `command` is only executed if the Guest account does not exist, as indicated by `unless` returning 0.

**Note:** PowerShell variables, e.g. `$_`, must be escaped in puppet manifests either using backslashes or single quotes.
**Note:** PowerShell variables (e.g. `$_`), must be escaped in Puppet manifests either using backslashes or single quotes.

Alternatively, you can put the PowerShell code for the `command`, `onlyif`, and `unless` parameters into separate templates and then invoke the template function in the resource.

```
~~~
exec { 'rename-guest':
command => template('guest/rename-guest.ps1'),
onlyif => template('guest/guest-exists.ps1'),
provider => powershell,
logoutput => true,
}
```
Each template is a PowerShell script,
~~~

Each template is a PowerShell script.

```
~~~
$obj = $(Get-WMIObject Win32_UserAccount -Filter "Name='Guest'")
$obj.Rename("OtherGuest")
```
~~~

This has the added benefit of not requiring escaping '$' in the PowerShell code.

##Reference
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this wording go away or get moved somewhere else?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's helpful to have the link. Not necessary though.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually because we are removing a bunch of parameters from below, it would be most helpful to have this link re-added. And then parameters should state it builds upon the existing parameters/properties already available in the exec resource.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing parameters:

  • creates
  • cwd
  • group
  • unmask

If those don't apply to this provider, perhaps we should mention that somewhere so there is not confusing in trying to use them. Thoughts?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There were previously 3 mentions of this module using exec's params in the readme, so to cut down on cruft, it was removed here. Our readme style guide also tries to avoid links as much as possible, as many of our users are reading this readme in vim or offline and markdown links make the document harder to read. The parameters that were removed from the readme were deemed not relevant to the powershell module, as previously the list of params was just copied from exec's documentation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its hard to say if there is value in keeping them for the reasons you just mentioned - in vim or no internet. I would default to keeping them - they are valid parameters. Thoughts? Cc @joshcooper

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @jtappa, creates is important, because it can be used (like onlyif and unless) to make the powershell resource idempotent. The cwd is somewhat important, depending on the use case. I agree group and umask are not (they're meaningless for this provider).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll re-add creates and cwd. What are the defaults for these parameters, if any?


Since the powershell module is a provider for `exec` it enables the same parameters as [`exec`](http://docs.puppetlabs.com/references/stable/type.html#exec) for PowerShell.

###Provider: powershell
####Provider
* powershell - Adapts the Puppet `exec` resource to run PowerShell commands.

####Parameters
All parameters are optional.

* **command** - The actual PowerShell command to execute. Must either be fully qualified or a search path for the command must be provided.
* **creates** - The file to look for before running the command. The command will only run if the file doesn’t exist. *Note:* This parameter will not create a file, it will simply look for one.
* **cwd** - The directory from which to run the command.
* **environment** - Additional environment variables to set for a command. Multiple entries should be in an array.
* **group** - The group to run the command as.
* **logoutput** - Whether to log command output in addition to logging the exit code. Valid values are 'true', 'false', and 'on_failure'. Defaults to 'on_failure, which only logs the output when the command has an exit code that does not match any value specified by the returns attribute.
* **onlyif** - Only run the exec if the command returns 0.
* **path** - The search path used for command execution.
* **refresh** - How to refresh the command.
* **refreshonly** - Used with `subscribe` and `notify` [metaparameters](http://docs.puppetlabs.com/references/latest/metaparameter.html) to refresh the command only when a dependent object is changed. Valid values are 'true' and 'false'.
* **returns** - The expected return code(s). An error will be returned if the executed command returns something else. Defaults to 0. Can be specified as an array of acceptable return codes or a single value.
* **timeout** - The maximum time the command should take.
* **tries** - The number of times execution of the command should be tried. Defaults to '1'.
* **try_sleep** - The time to sleep in seconds between `tries`.
* **umask** - The umask to be used while executing the command.
* **unless** - The `exec` will run unless the command returns 0.
#####`creates`
Specifies the file to look for before running the command. The command will only run if the file doesn't exist. **Note: This parameter will not create a file, it will simpy look for one.** Valid options: A string of the path to the file. Default: Undefined.

##Limitations
#####`cwd`
Sets the directory from which to run the command. Valid options: A string of the directory path. Default: Undefined.

* This module requires PowerShell to be installed and the `powershell.exe` to be available in the system PATH.
* Only supported on Windows Server 2003 and above, and Windows 7 and 8
#####`command`
Specifies the actual PowerShell command to execute. Must either be fully qualified or a search path for the command must be provided. Valid options: String. Default: Undefined.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

String is confusing to me.


##Development
#####`environment`
Sets additional environment variables to set for a command. Valid options: String, or an array of multiple options. Default: Undefined.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

String is weird. The wording is telling me a type I can use, but nearly everything is a string in puppet 3 and below.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would you suggest instead of string?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have a great suggestion yet. Just that string is a type and not a value. But I get that you changed that to valid "options", not values.


#####`logoutput`
Defines whether to log command output in addition to logging the exit code. If you specify 'on_failure', it only logs the output when the command has an exit code that does not match any value specified by the `returns` attribute. Valid options: 'true', 'false', and 'on_failure'. Default: 'on_failure'.

#####`onlyif`
Runs the exec only if the command returns 0. Valid options: String. Default: Undefined.

#####`path`
Specifies the search path used for command execution. Valid options: String of the path, an array, or a semicolon-separated list. Default: Undefined.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

#####`refresh`
Refreshes the command. Valid options: String. Default: Undefined.

Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
#####`refreshonly`
Refreshes the command only when a dependent object is changed. Used with `subscribe` and `notify` [metaparameters](http://docs.puppetlabs.com/references/latest/metaparameter.html). Valid options: 'true', 'false'. Default: 'false'.

We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
#####`returns`
Lists the expected return code(s). An error will be returned if the executed command returns something else. Valid options: An array of acceptable return codes or a single value. Default: 0.

#####`timeout`
Sets the maximum time in seconds that the command should take. Valid options: Number or string representation of a number. Default: 300.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 on getting the default specified


#####`tries`
Determines the number of times execution of the command should be attempted. Valid options: Number or a string representation of a number. Default: '1'.

#####`try_sleep`
Specifies the time to sleep in seconds between `tries`. Valid options: Number or a string representation of a number. Default: Undefined.

#####`unless`
Runs the `exec`, unless the command returns 0. Valid options: String. Default: Undefined.

##Limitations

* Only supported on Windows Server 2003 and above, and Windows 7 and above.

##Development

You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html)