vmware / dscr-for-vmware Goto Github PK
View Code? Open in Web Editor NEWThe Repository contains Microsoft PowerShell Desired State Configuration (DSC) Resources for managing VC and ESXi settings.
License: Other
The Repository contains Microsoft PowerShell Desired State Configuration (DSC) Resources for managing VC and ESXi settings.
License: Other
It is not entirely clear to me what type of code goes in the member functions (besides Test, Set and Get) of a DSC class, and what goes into the VMware.vSphereDSC.Helper module.
I see PowerCLI cmdlets and vSphere API methods/objects being used in both.
And I see resource specific functions in the VMware.vSphereDSC.Helper module as well.
In the Unit Helper Modules we also define vSphere objects.
It would be handy to have the names of these classes correspond with the name of the corresponding object in the API Reference.
For example, the VMHost ExtensionData property should be a HostSystem object.
There are many builds of vSphere (ESXi and VCSA) out there that are still supported.
What would be the approach for running Integration Tests?
against the latest builds
against the oldest builds
against all supported builds
against all possible combinations of builds (including mixed environments)
We don't, at least most of us don't, have the test environments available that I would assume the PowerCLI Dev Team has.
Would creating and verifying correctness of said Integration Tests once, be sufficient for submitters of PRs?
And would the PowerCLI Dev Team run the same Integration Tests than against their battery of available/possible environments for final validation?
That sounds costly, more so since we are dealing with Open Source code.
It is a bit confusing when the master and the dev branch have different version of documentation intended for contributors.
I'm especially thinking of .md files in the repo root.
Can you please add a git-template to the project?
In the template I would like to have the line
Signed-off-by: Your Name [email protected]
Then with a one-time command, contributors can make sure that each commit is automatically signed.
The command
git config commit.template ~/dscr-for-vmware/git-template
It is considered good practice to provide WhatIf support on resources.
Create DatastoreInventoryBaseDSC class that resolves the path to a folder in the Datastore folder of a Datacenter.
Many vSphere components can be accessed via multiple paths.
For example a VM has a path in HostandCluster but also in VM.
The combination of these paths provide the unique location for an object.
How do we specify these different paths?
Shall these paths be keys, but perhaps not mandatory?
Do these paths belong in the BaseDsc class?
Please clarify before users start contributing, and each come up with their own solution.
I would like to contribute the host power policy setting.
I hadn't noticed this till now, but the Ensure DSCProperty only seems to be defined in the VMHostSatpClaimRule resource.
Isn't this a property that all DSC resources should have?
And hence belongs on the BaseDSC class?
A common best practice for Pester tests seems to be to encapsulate Pester tests in a Try-Finally construct.
Since a Finally block is always run, this allows for a cleanup of the environment, independent of the Try block outcome.
As a reference, have a look at the Pester Unit and Integration test templates that MSFT provides in their DSCResources repo.
The general layout:
function Invoke-TestSetup
{
# Init code
}
function Invoke-TestCleanup
{
# Cleanup code
}
Try
{
Invoke-TestSetup
# Tests
}
Finally
{
Invoke-TestCleanup
}
How shall we integrate enums in the Integration tests?
In the current setup/layout, the enums created for the DSC resources, are not known in the integration test environment.
As an example, the VMHostService resource uses the [ServicePolicy] enum.
How can we use these enum values in the integration tests?
When we have resources depending on other resources being present:
This commit added .vscode into the project directory to provide a settings.json file. While I understand the reason would be to help ensure consistency with linting, the .vscode directory is typically considered to be locally specific.
I can see issues with getting PRs which include changes to .vscode requiring changes etc and overall increasing overhead.
VSCode settings are already included in the formatting guidelines document.
When we start to tackle more complex resources in a vSphere environment, there will be more and more separate resources that logically belong together.
This proposal suggests to organise these resources in separate subfolders under the DSCResources folder. These subfolders will help in visualising the relations between resources.
As an example, the standard Virtual Switch (VSS) would consist of the following separate, but related, resources:
Under this proposal the files for these resources could be organised something like this.
The build script only needs a minor change to support this afaik.
The same concept could eventually be adopted for other folders in the repository (Documentation, Configurations...)
While the repo is growing it might become difficult for contributors to discover what was added, removed or changed at what point in time.
To be able to easily see such changes, I propose to create a CHANGELOG document in the repo.
A PR should contain a standardised description of the changes, additions... it contains.
The build pipeline can insert that text into the CHANGELOG when the PR is merged.
The alternative is that the repo admins maintain the CHANGELOG document manually.
Or a mix of both.
Create separate resource for configuring PowerCLI Settings on the LCM. Expose all PowerCLI Settings properties in the resource.
Create base resource for inventory objects. It should provide key properties to uniquely identify inventory objects.
We have a large environment (300+ clusters) and a large number of engineers that can make changes (30+) but who may not be fully aware of the requirements for every cluster. We would like to do some enforcement of the settings on the cluster objects. These often get changed (whether inadvertently or on purpose but then not set back to the desired config).
The current pipeline doesn't change the module version.
I propose to align with Powershell RFC0004, which is SemVer based, and implement this in the build pipeline.
vSphere uses defaults for most of the optional properties.
How do we assign these defaults in a DSC resource?
Some options:
Each of these has pros and cons, but I feel we should define how it shall be done, before more resources are introduced.
Somewhat related, how do we handle property dependencies?
When property A, for example has value 1, property B can only have values 1 and 2 but not 3.
Do we bury that in the code, or do we use a kind of definition language to document such restrictions?
I would like to contribute a Host Services resource to control those. Should be pretty easy i think as it's currently already included in PowerCLI. I just have to get in how DSCResources are implemented.
Since we are not supposed to commit the 2 VMware.vSphereDSC module files (.psm1 & .psd1), can we add the 2 files to .gitignore?
Although my commits seem to contain
Signed-off-by: Luc Dekens <[email protected]>
I keep getting an email from the VMware CLA Bot, telling me that
Am I missing something?
Currently the Wiki pages on this repo are not open sourced.
Is it the intention to open up these pages to the community?
MSFT has published extensive guidelines for contributing to their DSCResources repo.
Instead of reinventing the wheel, consider adopting these guidelines, where applicable.
For example, the DSC Resource Style Guidelines & Best Practices document has a very extensive list of guidelines and best practices.
Please provide formatting guidelines for the different types of files in the repo.
Isn't it possible to generate the C# code for the Add-Type in the TestHelpers module(s)?
I assume that the object definitions are available, and that a tool (swagger-like) should be able to generate that code?
Create HostInventoryBaseDSC class that resolves the path to a folder in the Host folder of a Datacenter.
In the Coding Guidelines it is proposed to have the following layout
Describe 'MyResource' {
Describe 'MyResource\Set' {
...
}
Describe 'MyResource\Test' {
...
}
Describe 'MyResource\Get' {
...
}
}
But since Pester currently only checks Tags (see issue #770) on the top level Describe, we always have to run the complete test file. Which can be annoying when developing the tests.
PS: the TestName parameter does the same
Would the following be an acceptable layout?
Since the MyResource is already present in the nested Describe blocks, I don't think we would miss anything.
Describe 'MyResource\Set' -Tag 'Set' {
...
}
Describe 'MyResource\Test' -Tag 'Test' {
...
}
Describe 'MyResource\Get' -Tag 'Get' {
...
}
}
And this will allow us to run a specific Describe block with
Invoke-Pester .\Unit\MyResource.Unit.Tests.ps1 -Tag 'Set'
When we store the C# definitions in a separate .cs file, and use Add-Type -Path, we will have better control over the C# code (syntax, lint...).
The current definition of the Get-View cmdlet in the TestHelper module VMware.VimAutomation.Core, is as follows:
function Get-View {
param(
[PSObject] $Server,
[PSObject] $VIObject
)
return $null
}
This doesn't allow using the same definition for other formats of the Get-View cmdlet.
I propose to implement the actual parametersets, present on the actual Get-View cmdlet.
For example (note that this is not complete)
function Get-View {
param(
[PSObject] $Server,
[Parameter(ParameterSetName = 'GetViewByVIObject')]
[PSObject] $VIObject,
[Parameter(ParameterSetName = 'GetView')]
[VMware.Vim.ManagedObjectReference] $Id,
[Parameter(ParameterSetName = 'GetView')]
[string[]] $Property
)
return $null
}
The same remark goes for other PowerCLI cmdlets present in the TestHelpder module(s)
We currently plan to move all content from the dev branch to the master branch and then continue only with the master branch as contributions will be made via pull request. So update of the documentation and build procedures to work with master branch is needed.
Here contributors can propose new content and sections to the Tips & Tricks page and to the Style Guidelines.
Resource implementation already started #51 by @lucdekens.
Currently it isn't clearly documented how to install the module. Also you currently you need to clone the github repo to somewhere as the resource configurations files aren't included in the module folder.
You can read it between the lines and screenshots in the https://blogs.vmware.com/PowerCLI/2018/12/getting-started-dsc-for-vmware.html blogpost.
The build procedure should be updated - the section that iterates over all folders and files should be modified as right now there is a problem on Ubuntu when listing them(They are listed alphabetically and not by folder structure which breaks the build in some special cases).
In the testhelper module VMware.VimAutomation.Core properties that should be of type ManagedObjectReference, are defined as the actual object.
For example:
public class HostConfigManager
{
public HostDateTimeSystem DateTimeSystem { get; set; }
public ManagedObjectReference NetworkSystem { get; set; }
public HostServiceSystem ServiceSystem { get; set; }
}
Where I would expect
public class HostConfigManager
{
public ManagedObjectReference DateTimeSystem { get; set; }
public ManagedObjectReference NetworkSystem { get; set; }
public ManagedObjectReference ServiceSystem { get; set; }
}
with a new object
public class ManagedObjectReference : System.IEquatable
{
public string Type { get; set; }
public string Value { get; set; }
...
This has impact on how the Mocks are set up.
Am I missing something?
When writing resources, some features might be version dependent.
How shall we handle this?
Or shall we always code a resource/feature assuming it is supported?
Do we cover the complete compatibility matrix in the resources, knowing that this will change over time?
The same question for coding features, which might depend on the PowerShell/PowerCLI version?
Do we use #requires directives for that?
Can we make the actual version numbers a property of the base classes?
I'm thinking of
vSphere API
vCenter
ESXi
PowerCLI
PowerShell
Now that we are merging all PRs into the master, I assume that each merge should also update the README.md file?
Since it is the first info a visitor/user sees, it would be handy to list at least all the available DSC resources.
And a related question, is README.md intended for the git administrators, or can all users contribute?
In the master and dev branch all Integration tests stop and prompt for parameters.
All Integration test scripts seem to have Mandatory parameters, hence the prompt.
The IntegrationTests.ps1 script doesn't provide any parameters when starting the Integration test scripts.
When attempting to perform a Test-DSCConfiguration I am getting errors during the process of connecting to vCenter.
Cannot establish connection to server vcsa.sdbrett.lab.
+ CategoryInfo : NotSpecified: (:) [], CimException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException
+ PSComputerName : localhost
Connection with PowerCLI outside of DSC works ok.
Windows 10
PS version: 5.1
PowerCLI 11.0
VCSA 6.7U1
When setting the LCM parameter DebugMode to ForceModuleImport, a configuration based on VMware.vSphereDsc resources fails with the errors
The specified mount name 'vis' is already in use.
+ CategoryInfo : InvalidOperation: (:) [], CimException
+ FullyQualifiedErrorId : NewDriveProviderException,Microsoft.PowerShell.Commands.ImportModuleCommand
+ PSComputerName : localhost
The specified mount name 'vmstores' is already in use.
+ CategoryInfo : InvalidOperation: (:) [], CimException
+ FullyQualifiedErrorId : NewDriveProviderException,Microsoft.PowerShell.Commands.ImportModuleCommand
+ PSComputerName : localhost
This DebugMode setting is useful when writing new DSC resources.
Other PS modules that provide PSDrives do not show this behaviour.
Can these errors be avoided?
Can the mounts be made more intelligent in order to not get these errors?
Since you are looking at a build pipeline, what would be the targeted code coverage percent for the Pester Unit tests?
Currently there are no clear directives on what Pester Unit tests should cover.
With a potential risk of phantom, or even worse malicious, code in the contributions from the community.
Btw, Pester code coverage for DSC resource classes is an open issue.
See the Pester issue#731
I got stuck on writing the unit tests for PR #5 as the tests failing with:
Executing script C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPolicySetting
Tests.ps1
Describing VMHostPowerPolicySettings
Describing VMHostPowerPolicySettings\Get
Context Invoking with default resource properties
[-] Should call the Connect-VIServer mock with the passed server and credentials once 263ms
RuntimeException: Unable to find type [VMware.Vim.PowerSystemInfo].
at ExecuteBlock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 1123
at Invoke-Mock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 966
at <ScriptBlock><Process>, <No file>: line 64
at GetVMHost, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line
at Get, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line 191
at <ScriptBlock>, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPo
tings.Unit.Tests.ps1: line 105
[-] Should call Get-VMHost mock with the passed server and name once 34ms
RuntimeException: Unable to find type [VMware.Vim.PowerSystemInfo].
at ExecuteBlock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 1123
at Invoke-Mock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 966
at <ScriptBlock><Process>, <No file>: line 64
at GetVMHost, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line
at Get, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line 191
at <ScriptBlock>, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPo
tings.Unit.Tests.ps1: line 115
[-] Should return the resource with the properties passed from the server 49ms
RuntimeException: Unable to find type [VMware.Vim.PowerSystemInfo].
at ExecuteBlock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 1123
at Invoke-Mock, C:\Program Files\WindowsPowerShell\Modules\Pester\4.4.2\Functions\Mock.ps1: line 966
at <ScriptBlock><Process>, <No file>: line 64
at GetVMHost, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line
at Get, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\VMware.vSphereDSC.psm1: line 191
at <ScriptBlock>, C:\Program Files\WindowsPowerShell\Modules\VMware.vSphereDSC\Tests\Unit\VMHostPowerPo
tings.Unit.Tests.ps1: line 125
It seams as Tests\Unit\TestHelpers\VMware.VimAutomation.Core is missing classes? How can we add the missing ones?
Since this is an open source project, many contributors can participate.
While this is a great principle, this would also require some basic guidelines/conventions.
Some questions such guidelines might address:
Wouldn't it be better to separate the DSCResource classes like VMHostNtpSettings
in their own folder and files? Something like Resources\VMHostNtpSettings.ps1
instead of directly in .psm1.
I would like to add a resource for a Standard Switch (VSS).
Until #11 is completed, the placement in a Network folder will be left out.
When applying configurations or when running Unit and Integration tests on fresh environments, we hit issues.
For example, PowerCLI by default is not configured to ignore invalid certificates.
Not as critical, but equally annoying, the CEIP prompt and the deprecated warnings are there by default.
How should the DSCR handle this?
By default set this options via Set-PowerCLIConfiguration?
Or make that a separate DSC resource?
To avoid that every contributor to this repo makes the same mistakes and falls into the same pitfalls, it would be nice to have a kind of FAQ.
This FAQ should contain guidelines, but also workarounds for known issues.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.