128 lines
5.6 KiB
Markdown
128 lines
5.6 KiB
Markdown
# Requirements
|
|
Requirements is a PowerShell Gallery module for declaratively describing a system as a set of "requirements", then idempotently setting each requirement to its desired state.
|
|
|
|
## Usage
|
|
|
|
We use the term `Test` to refer to the condition that describes whether the Requirement is in its desired state. We use the term `Set` to refer to the command that a `Requirement` uses to put itself in its desired state if it is known to not be in its desired state.
|
|
|
|
### Declaring requirements
|
|
The easiest way to declare a requirement is to define it as a hashtable and let PowerShell's implicit casting handle the rest.
|
|
|
|
```powershell
|
|
$requirements = @(
|
|
@{
|
|
Name = "Resource 1"
|
|
Describe = "Resource 1 is present in the system"
|
|
Test = { $mySystem -contains 1 }
|
|
Set = { $mySystem.Add(1) | Out-Null; Start-Sleep 1 }
|
|
},
|
|
@{
|
|
Name = "Resource 2"
|
|
Describe = "Resource 2 is present in the system"
|
|
Test = { $mySystem -contains 2 }
|
|
Set = { $mySystem.Add(2) | Out-Null; Start-Sleep 1 }
|
|
},
|
|
@{
|
|
Name = "Resource 3"
|
|
Describe = "Resource 3 is present in the system"
|
|
Test = { $mySystem -contains 3 }
|
|
Set = { $mySystem.Add(3) | Out-Null; Start-Sleep 1 }
|
|
},
|
|
@{
|
|
Name = "Resource 4"
|
|
Describe = "Resource 4 is present in the system"
|
|
Test = { $mySystem -contains 4 }
|
|
Set = { $mySystem.Add(4) | Out-Null; Start-Sleep 1 }
|
|
},
|
|
@{
|
|
Name = "Resource 5"
|
|
Describe = "Resource 5 is present in the system"
|
|
Test = { $mySystem -contains 5 }
|
|
Set = { $mySystem.Add(5) | Out-Null; Start-Sleep 1 }
|
|
}
|
|
)
|
|
```
|
|
|
|
### Idempotently Setting requirements
|
|
Simply pipe an array of `Requirement`s to `Invoke-Requirement`
|
|
|
|
```powershell
|
|
$requirements | Invoke-Requirement
|
|
```
|
|
|
|
### Formatting the logs
|
|
`Invoke-Requirement` will output logging events for each step in a `Requirement`'s execution lifecycle. You can capture these logs with `Format-Table` or `Format-List`, or
|
|
|
|
```powershell
|
|
$requirements | Invoke-Requirement | Format-Table
|
|
```
|
|
|
|
#### `Format-Table`
|
|
These logs were using `-Autosize` parameter, which better formats the columns, but does not support outputting as a stream.
|
|
```
|
|
Method Lifecycle Name Date
|
|
------ --------- ---- ----
|
|
Test Start Resource 1 6/12/2019 12:00:25 PM
|
|
Test Stop Resource 1 6/12/2019 12:00:25 PM
|
|
Set Start Resource 1 6/12/2019 12:00:25 PM
|
|
Set Stop Resource 1 6/12/2019 12:00:26 PM
|
|
Validate Start Resource 1 6/12/2019 12:00:26 PM
|
|
Validate Stop Resource 1 6/12/2019 12:00:26 PM
|
|
Test Start Resource 2 6/12/2019 12:00:26 PM
|
|
Test Stop Resource 2 6/12/2019 12:00:26 PM
|
|
Set Start Resource 2 6/12/2019 12:00:26 PM
|
|
...
|
|
```
|
|
|
|
#### `Format-Checklist`
|
|
`Format-Checklist` will present a live-updating checklist to the user.
|
|
|
|
![Format-Checklist output](https://raw.githubusercontent.com/microsoft/requirements/master/imgs/checklist.png)
|
|
|
|
#### `Format-Callstack`
|
|
Unlike `Format-Checklist`, `Format-Callstack` prints all log events and includes metadata. For complex use cases, you can define nested `Requirement`s (`Requirement`s that contain more `Requirement`s in their `Set` block). `Format-Callstack` will print the stack of `Requirement` names of each `Requirement` as its processed.
|
|
|
|
![Format-Callstack output](https://raw.githubusercontent.com/microsoft/requirements/master/imgs/callstack.png)
|
|
|
|
### Defining DSC Resources
|
|
If you're using Windows and PowerShell 5, you can use DSC resources with Requirements.
|
|
|
|
```PowerShell
|
|
$requirement = @{
|
|
Describe = "My Dsc Requirement"
|
|
ResourceName = "File"
|
|
ModuleName = "PSDesiredStateConfiguration"
|
|
Property = @{
|
|
Contents = "Hello World"
|
|
DestinationPath = "C:\myFile.txt"
|
|
Force = $true
|
|
}
|
|
}
|
|
New-Requirement @requirement | Invoke-Requirement | Format-Checklist
|
|
```
|
|
|
|
## Comparison to DSC
|
|
Desired State Configurations allow you to declaratively describe a configuration then let the configuration manager handle with setting the configuration to its desired state. This pattern from the outside may seem similar to Requirements, but there are crucial differences.
|
|
|
|
DSC is optimized for handling *many* configurations *asynchronously*. For example, applying a configuration in parallel to multiple nodes. In contrast, Requirements applies a *single* configuration *synchronously*. This enables usage in different scenarios, including:
|
|
* CI/CD scripts
|
|
* CLIs
|
|
* Dockerfiles
|
|
* Linux
|
|
|
|
While Requirements supports DSC resources, it does not have a hard dependency on DSC's configuration manager, so if your Requirements do not include DSC resources they will work on any platform that PowerShell Core supports.
|
|
|
|
# Contributing
|
|
|
|
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
|
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
|
the rights to use your contribution. For details, visit https://cla.microsoft.com.
|
|
|
|
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
|
|
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
|
|
provided by the bot. You will only need to do this once across all repos using our CLA.
|
|
|
|
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
|
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
|
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|