diff --git a/myAppState.config.yml b/myAppState.config.yml new file mode 100644 index 000000000..d75417f64 --- /dev/null +++ b/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 \ No newline at end of file