Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mefellows/vagrant-dsc
DSC Provisioner for Vagrant
https://github.com/mefellows/vagrant-dsc
Last synced: about 2 months ago
JSON representation
DSC Provisioner for Vagrant
- Host: GitHub
- URL: https://github.com/mefellows/vagrant-dsc
- Owner: mefellows
- License: mit
- Created: 2014-10-10T13:06:03.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2018-05-05T01:34:25.000Z (over 6 years ago)
- Last Synced: 2024-10-11T22:55:16.105Z (2 months ago)
- Language: Ruby
- Size: 110 KB
- Stars: 45
- Watchers: 7
- Forks: 15
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Vagrant DSC Plugin
[](https://travis-ci.org/mefellows/vagrant-dsc)
[](https://coveralls.io/r/mefellows/vagrant-dsc?branch=master)
[](http://badge.fury.io/rb/vagrant-dsc)
[Desired State Configuration](https://msdn.microsoft.com/en-us/powershell/dsc/overview) provisioning plugin for Vagrant, enabling you to quickly configure & bootstrap a Windows Virtual Machine in a repeatable, reliable fashion - the Vagrant way.
.NET Devs - no more excuses...
> But it works on my machine!?
...is a thing of the past
## Features
1. Automated provisioning using [PowerShell DSC](https://msdn.microsoft.com/en-us/powershell/dsc/overview)
2. Install modules from the [Powershell Gallery](https://www.powershellgallery.com/)
with PowerShellGet / PowerShell5
3. Windows development machine from zero to dev-ready < 5 minutes!
## Installation
```vagrant plugin install vagrant-dsc```
## Usage
In your Vagrantfile, add the following plugin and configure to your needs:
```ruby
config.vm.provision "dsc" do |dsc|
# The path relative to `dsc.manifests_path` pointing to the Configuration file
dsc.configuration_file = "MyWebsite.ps1"
# The Configuration Command to run. Assumed to be the same as the `dsc.configuration_file`
# (sans extension) if not provided.
dsc.configuration_name = "MyWebsite"
# Commandline arguments to the Configuration run
# Set of Parameters to pass to the DSC Configuration.
#
# To pass in flags, simply set the value to `nil`
dsc.configuration_params = {"-MachineName" => "localhost", "-EnableDebug" => nil}
# A path relative to the Vagrantfile pointing to a Configuration Data file.
#
# See https://technet.microsoft.com/en-us/library/dn249925.aspx for details
# on how to parameterise your Configuration files.
dsc.configuration_data_file = "manifests/MyConfig.psd1"
# Relative path to a folder containing a pre-generated MOF file.
#
# Path is relative to the folder containing the Vagrantfile.
# When set, `configuration_name`, `configuration_data_file_path`,
# `configuration_file_path`, `configuration_data_file` and
# `manifests_path` are ignored.
dsc.mof_path = "mof_output"
# Relative path to the folder containing the root Configuration manifest file.
# Defaults to 'manifests'.
#
# Path is relative to the folder containing the Vagrantfile.
dsc.manifests_path = "manifests"
# Set of module paths relative to the Vagrantfile dir.
#
# These paths are added to the DSC Configuration running
# environment to enable local modules to be addressed.
dsc.module_path = ["manifests", "modules"]
# Set of modules to install from the PowerShell Gallery
# (https://www.powershellgallery.com/).
#
# Requires PowerShell 5 or PowerShellGet installed on guest machine.
#
# These modules are downloaded and installed when provisioning,
# if a module is already installed it is a no-op.
dsc.module_install = ["xNetworking", "xComputerManagement"]
# The type of synced folders to use when sharing the data
# required for the provisioner to work properly.
#
# By default this will use the default synced folder type.
# For example, you can set this to "nfs" to use NFS synced folders.
dsc.synced_folder_type = "nfs"
# Whether to abort the vagrant run if DSC fails.
#
# By default, this is false.
dsc.abort_on_dsc_failure = true
# Temporary working directory on the guest machine.
dsc.temp_dir = "/tmp/vagrant-dsc"
end
```
### Specifying a MOF file
If `mof_path` is set then `configuration_name`, `configuration_data_file_path`, `configuration_file_path`, `configuration_data_file` and `manifests_path` are all not required, and will be ignored. Once you have a MOF file, you have everything you need (except possibly any paths to modules i.e. `module_paths`) to execute DSC
If you don't know what a MOF file is, you probably don't need it and can safely ignore this setting.
Vagrant DSC will create and manage it for you automatically.
## Example
There is a [sample](https://github.com/mefellows/vagrant-dsc/tree/master/development/web)
Vagrant setup used for development of this plugin. This is a great real-life example
to get you on your way.
## Creating Windows Vagrant boxes
Look at some example Packer templates [here](https://github.com/mefellows/packer-windows-templates/).
## Roadmap
* Support DSC Pull Server provisioning
* Test (dry-run) a DSC Configuration Run with 'vagrant vagrant-dsc test'
* Support for non-Windows environments
### Supported Environments
Currently the plugin only supports modern Windows environments with DSC installed (Windows 8.1+, Windows Server 2012 R2+ are safe bets).
The plugin works on older platforms that have a later version of .NET (4.5) and the WMF 4.0 installed.
As a general guide, configuring your Windows Server
From the [DSC Book](https://www.penflip.com/powershellorg/the-dsc-book):
> **DSC Overview and Requirements**
> Desired State Configuration (DSC) was first introduced as part of Windows Management Framework (WMF) 4.0, which is preinstalled in Windows 8.1 and Windows Server 2012 R2, and is available for Windows 7, Windows Server 2008 R2, and Windows Server 2012. Because Windows 8.1 is a free upgrade to Windows 8, WMF 4 is not available for Windows 8.
> You must have WMF 4.0 on a computer if you plan to author configurations there. You must also have WMF 4.0 on any computer you plan to manage via DSC. Every computer involved in the entire DSC conversation must have WMF 4.0 installed. Period. Check $PSVersionTable in PowerShell if you’re not sure what version is installed on a computer.
> On Windows 8.1 and Windows Server 2012 R2, make certain that KB2883200 is installed or DSC will not work. On Windows Server 2008 R2, Windows 7, and Windows Server 2008, be sure to install the full Microsoft .NET Framework 4.5 package prior to installing WMF 4.0 or DSC may not work correctly.
We may consider automatically installing and configuring DSC in a future release of the plugin.
## Uninstallation
```vagrant plugin uninstall vagrant-dsc```
## Development
Before getting started, read the Vagrant plugin [development basics](https://docs.vagrantup.com/v2/plugins/development-basics.html) and [packaging](https://docs.vagrantup.com/v2/plugins/packaging.html) documentation.
You will need Ruby 2.1.5 and Bundler v1.12.5 installed before proceeding.
_NOTE_: it _must_ be bundler v1.12.5 due to a hard dependency in Vagrant at this time.
```
git clone [email protected]:mefellows/vagrant-dsc.git
cd vagrant-dsc
bundle install
```
Run tests:
```
bundle exec rake spec
```
Run Vagrant in context of current vagrant-dsc plugin:
```
cd
bundle exec vagrant up
```
There is a test Vagrant DSC setup in `./development` that is a good example of a simple acceptance test.
### Multiple Bundlers?
If you have multiple Bundler versions, you can still use 1.12.5 with the following:
```
bundle _1.12.5_
```
e.g. `bundle _1.12.5_ exec rake spec`
### Visual Studio Code
You can run the test from Visual Studio Code. This needs the binstubs from bundler. Run
```
bundler install --binstubs
```
to get them.
After this you can run the tests with F5.
## Contributing
1. Fork it ( https://github.com/[my-github-username]/vagrant-dsc/fork )
1. Create your feature branch (`git checkout -b my-new-feature`)
1. Commit your changes, including relevant tests (`git commit -am 'Add some feature'`)
1. Squash commits & push to the branch (`git push origin my-new-feature`)
1. Create a new Pull Request