search

MicrosoftDocs / PowerShell-Docs

The official PowerShell documentation sources
https://learn.microsoft.com/powershell
Other
2.02k stars 1.58k forks source link

Clarify "community resources", the state of the DscResources GitHub repository and more #5260

Closed heinrich-ulbricht closed 4 years ago

heinrich-ulbricht commented 4 years ago

The section "Built-in resources" states:

In addition to community resources, there are built-in resources for Windows, resources for Linux, and resources for cross-node dependency.

As a technical person trying to understand the DSC big picture I have the following questions after reading the above statement:

  1. What are those "community resources"? They are mentioned here casually without linking somewhere. Is there a well-known set of community resources? Or is this rather a generic term referring to any resource that might have been created by a third party?
  2. "there are built-in resources for Windows, resources for Linux, and resources for cross-node dependency" - what is "built-in" and what is "not built-in"? Does the term "built-in" also refer to Linux? In the sub-heading of the listed resources it says "Linux resources", "built-in" is missing. In the resource reference left navigation node it says "Linux built-in resources" instead. This should be made consistent. Why am I harping on this? Because "built-in" for me means: I don't have to do anything. "Not built-in" means: I have to install something. (Is this even right? What exactly is built into what?)
  3. How does the GitHub repository DscResources fit into the picture? The repo readme states that this is a list of resources from Microsoft. Is it equivalent to the "built-in" resources? Is this the "community resources"? Is it a different set of resources? And if yes, do I have to differentiate between the "non-x"-resources and the "x"-resources (those were kind of beta if I remember correctly)?
  4. Looking also at Azure Automation State Configuration (DSC) I wonder which resources are available there in Azure. Is it the "built-in" ones? The GitHub repo ones? ...? Since the topics are somewhat connected I wished there was a hint in the right direction here.
  5. And a bit fringy but also connected: what's the deal with the Office365DSC resource? Is there a connection to the aforementioned topics or is this a project completely separated from it all?

My goal is to

Clarifying the above questions would help a lot.

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

heinrich-ulbricht commented 4 years ago

My current understanding regarding questions 1 and 3 is that https://github.com/PowerShell/DscResources indeed is the "official" community resource repository. This should be referenced to as such from the DSC documentation. The other questions remain.

heinrich-ulbricht commented 4 years ago

Not so sure anymore. Discovered https://github.com/dsccommunity... The questions remain.

sdwheeler commented 4 years ago

This might answer some of the questions: https://dsccommunity.org/faq/

johlju commented 4 years ago

The "built-in modules" is the list here https://docs.microsoft.com/en-us/powershell/scripting/dsc/resources/resources?view=powershell-7#built-in-resources. They are replaced by the module PSDscResources with the exception of File which still is only available as a 'built-in' module (close to the OS for speed). The Microsoft module PSDscResources (supported only by Microsoft) does not allow any changes no longer as they are 1:1 replacement of the built-in modules. Hence the community module xPSDesiredStateConfiguration (supported by the community) which have the same resources as PSDscResource but do allow changes and breaking changes.

At present day the community modules in the DSC Resource Kit (https://github.com/PowerShell/DscResources) have been transferred over to the DSC Community (https://dsccommunity.org) making it even more clear that they are community supported modules. Read more here: https://dsccommunity.org/community/origin-story/. The exception is PSDscResources because it is supported by Microsoft. Also deprecated modules have not been transferred as their resources have been moved to another module that has been transferred.

johlju commented 4 years ago

Btw, "x" resources are not beta production ready resources. The community is slowly renaming the modules and resource names removing the 'x' from the names because the 'x' for many years never had any meaning.

johlju commented 4 years ago

More thoughts from me...

  1. All modules are community modules (supported by the contributors in the the DSC Community - everyone wanting to contribute). The exception is PSDscResource and the Windows built-in modules that is part of the OS (linked to above)
  2. No Linux distro have built-in resource (as far as I know). This probably have to be installed, see https://github.com/microsoft/PowerShell-DSC-for-Linux.
  3. Same as number 1 above. Also see my previous comment.
  4. Built-in resource is in OS, all other you need to download from the PowerShell Gallery to use (PSDScResource and all other Community modules). Not sure how it works with the Linux ones.
  5. The Office365Dsc is a community module as well. It just happens that it the OSS project is under the Microsoft GitHub org because the maintainer is MS employee that works on it in his free time. It might be transferred over to DSC Community too eventually.
heinrich-ulbricht commented 4 years ago

This is very valuable information @johlju thank you very much. I was not able to read this from the official sources, which is not surprising given that this topic is kind of a moving target which is going to be consolidated eventually. I close this ticket since my questions have been answered. Thanks again!

sdwheeler commented 4 years ago

@chasewilson Do we want to try to update the docs here?

chasewilson commented 4 years ago

I think there are a few adjustments we can make to clarify the information a bit better. Reopening to make some edits.