my interpretation of a policy-document defining a state

myAppState.config.yml

@@ -0,0 +1,170 @@
+# Example for a PowerShell dev environment
+
+# A unit of configuration needs to identify the DSC Resource performing actions (dependencies) +
+# A unit of configuration needs to have a unique "instance" identifier (supports dependencies) +
+# A unit of configuration needs properties/parameters +
+# An optional dependency needs to be supported +
+# An optional declaration of user privilege/inpersonation needs to be supported (user vs. admin) +
+# In some cases, a "monitor only" behavior should be supported in a configuration file (or a unit of configuration), with the option to stop or continue the configuration
+# In some cases, the agent may want to assert some conditions before trying to converge or monitor a configuration (i.e. maintenance window, app running, state of windows update...)
+# - I don't want to run Windows update, but I need to ensure some minimum version is present before continuing
+
+# Winget install: vscode, dotnet sdk, powershell 7, git
+# OS Windows 10 or greater (this should be restricted during assignment not config, or you imply you can have many configuration policies)
+# VSCode config: powershell extension, c# extension, powershell 7 as default shell
+# dotnet sdk: 5.0
+# powershell 7: latest stable
+# git: default editor vscode
+
+# for different editors, it may make sense to have separate configs per editor particularly since each
+# editor has different settings and extensions
+
+# consider resources that may require elevation or confirmation and how to support both
+# declaring override in the config and allowing resources to do their own prompting
+
+# for the authoring experience, we would build a vscode extension that has the top level manifest
+# schema, but can dynamically pull in available resources and resource specific schemas and
+# then handle intellisense
+
+# how does the orchestrator/agent know which module(s) to install to get the resources?
+
+# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://aka.ms/schemas/dsc/manifest.schema.yaml #manifest is too generic, that's configuration policy
+
+AgentContext: # Reserved for the "managing context or config before converging to the desired state". Could be a different file!
+  onFailure: stop # stop processing the resource graph as soon as a failure occurs in one of the resources (default)
+  GraphParameters: ResolveAsNeeded # ResolveFirst | ResolveNonInteractive
+  # prechecks:
+  # postchecks:
+  assertBeforeRun:
+  # assertions: # every assertion should pass before any config is applied and calls `test` method, multiple resources can be here and if any fail, the entire config fails
+    - resource: assert-osversion # naming convention for assert resources
+      settings:
+        os: Windows10
+        version: "[10.0.25227-*)"
+  dependencies:
+    resources:
+      - resource: Microsoft.PowerShell.OSResourcesDsc\* # example of specifying a module name
+        # implementedAs: powershell # optional
+        repository: PSGallery # example of specifying a repository name
+        confirm: true # example where you might require Windows update, but need confirmation from user initiated by the orchestrator (do we need support for resources to prompt for confirmation?)
+        signerThumbprint: AFBF0B8B6A18F7E23CCA1DDCD0AC1A55B4035173 # thumbprint of the signer cert valid for multiple versions
+
+      - resource: Microsof.Winget
+        implementedAs: powershell # optional
+        requiredVersion: "[1.0.0-1.1.0)" # version of the resource, not winget itself
+        timeoutSeconds: 300
+
+      - module: gitIdempotentConfigurator.exe
+        implementedAs: binary # optional
+        sha256hash: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef # hash of the resource, this would be specific to a version
+
+DesiredState: # This is the unique desired state we want to converge to (in this context/scope).
+  parameters: # these would just be resources that retrieve information via `get` operation
+    - id: psgalleryKey
+      data_resolver_type:
+        name: Microsoft.PowerShell.SecretManagement\Get-Secret
+        version: "[10.0.25227-*)"
+      data_resolver_parameters:
+        vault: AzureKeyVault
+        name: psgallerykey
+
+    - id: AskForGitUserName
+      data_resolver_type:
+        name: Microsoft.DSC.Configuration\GetUserInput.exe # not necessarily an exe, but refer to the configuration utility capability to request user input
+      data_resolver_parameters:
+        prompt: Please provide the username to use in git
+        type: string
+
+    - id: AskUserWhetherToInstallAzModule
+      data_resolver_type:
+        name: Microsoft.DSC.Configuration\GetUserInput.exe
+      data_resolver_parameters:
+        prompt: do you want to ensure the PS Module PowerShell get is Present or Absent? 
+        type: string
+        ValidateSet: [present,absent]
+
+    - id: PS7InstalledPath
+      data_resolver_type:
+        name: cmd
+      data_resolver_parameters:
+        cmd_parameters: /C Where.exe pwsh
+
+
+  ResourceGraph: # this is the Directed Acyclic Graph of the resources drawing the path of states (nodes) or changes (edges) a system need to go through to converge towards the desired state
+    - resource_instance_id: '[Microsoft.PowerShell.OSResourcesDsc\osversion]MyInstanceOfOsversion' # unique identifier of the instance, composed at "compile" time.
+      resource_type:
+        name: Microsoft.PowerShell.OSResourcesDsc\osversion
+        version: "[10.0.25227-*)"
+      resource_parameters:
+        os: Windows10
+        version: "[10.0.25227-*)"
+        windowsUpdate: true
+
+    - resource_instance_id: '[Microsoft.Winget\winget]install_vscode'
+      resource_type:
+        name: Microsoft.Winget\winget
+        version: "[10.0.25227-*)"
+      resource_parameters:
+        id: Microsoft.VisualStudioCode
+        version: "[1.27.2-*)"
+      runas: Admin # this will require to be more complex objects, which means the interface for this object has to be defined...
+
+    - resource_instance_id: '[Microsoft.Winget\winget]install_DotNetSDK'
+      resource_type: Microsoft.Winget\winget #short version of resource_type object, not specifying version/range
+      resource_parameters:
+        requiredVersion: "[1.0.0-1.1.0)"
+        id: Microsoft.DotnetSDK # for this example, we assume this SDK requires admin to install
+        version: latest # always converge to latest availble from sources
+
+    - resource_instance_id: '[Microsoft.Winget\winget]install_ps7'
+      # if we work with state and idempotency, we can't leverage resource output.
+      # It could have been installed manually for whatever reason, before a reboot or else
+      # if you installed pwsh on one run, and then it failed on the next package (git) the convergence stopped
+      # "at some point", the convergence resumes (who knows when), do you persist all resource outputs?
+      resource_type:
+        name: Microsoft.Winget\winget
+        version: "[10.0.25227-*)"
+      resource_parameters:
+        id: Microsoft.PowerShell
+        version: "[7.0.0-*)"
+
+    - resource_instance_id: '[Microsoft.Winget\winget]install_Git'
+      resource_type:
+        name: Microsoft.Winget\winget
+        version: "[10.0.25227-*)"
+      overrides: # Similar to chef's or test-kitchen ways to override defined keys in hierarchy.
+        AgentContext:
+          onFailure: continue # ok to continue on failure while other resources will stop processing
+      resource_parameters:
+        id: Git.Git
+
+    - resource_instance_id: '[Microsoft.VscodeDsc\extension]install_vscodeExtensions'
+      resource_parameters:
+        extensions:
+          - ms-vscode.powershell
+          - ms-dotnettools.csharp
+        settings:
+          terminal.integrated.shell.windows: $parameters.PS7InstalledPath # use a fact that you can address (periodic? evaluation, or notify?), not output (transactional)
+      dependsOn:
+        - '[Microsoft.Winget\winget]install_ps7'
+        - '[Microsoft.Winget\winget]install_vscode' # automatic id are best done at compilation (resource and key properties of the resource can be used)
+
+    - resource_instance_id: gitIdempotentConfigurator.exe
+      resource_parameters:
+        editor: vscode
+        global.username: $parameters.AskForGitUserName
+      dependsOn:
+        - '[Microsoft.Winget\winget]install_Git'
+        - '[Microsoft.Winget\winget]install_vscode'
+
+    - resource_instance_id: '[Microsoft.PowerShell.PowerShellGet\ModuleDsc]install_az_module'
+      # the directives should not directly condition whether something is installed or not, but the state (absent/present) can be defined as a parameter.
+      # so you define what parameter is allowed, but the policy is still driven by data (authoring config data, merged with allowed runtime parameters)
+      resource_parameters:
+        ensure: $AskUserWhetherToInstallAzModule
+        module: Az
+        version: "[1.0.0-*)"
+        repository: PSGallery
+        apiKey: $parameters.psgalleryKey