From 57bdcaa28a32c6597caa7c4b80f0deb2c84e702d Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Mon, 5 Feb 2024 10:43:05 -0600 Subject: [PATCH] (DOCS) Document parameters implementation This change adds documentation to the CLI and schema reference for the parameters support implementation in #291 and #294. It also updates the changelog with the relevant information. --- CHANGELOG.md | 29 ++++- docs/reference/cli/config/command.md | 40 ++++++- .../schemas/config/functions/parameters.md | 112 ++++++++++++++++++ docs/reference/schemas/config/parameter.md | 7 +- 4 files changed, 184 insertions(+), 4 deletions(-) create mode 100644 docs/reference/schemas/config/functions/parameters.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f14894b..dec92717 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ title: "Desired State Configuration changelog" description: >- A log of the changes for releases of DSCv3. -ms.date: 01/17/2024 +ms.date: 02/05/2024 --- # Changelog @@ -24,6 +24,24 @@ changes since the last release, see the [diff on GitHub][unreleased]. [unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main +### Added + +- Implemented support for referencing parameters in a configuration with the [parameters()][32] + configuration function. This enables you to take advantage of parameterized configurations. Until + this release, you could define but not reference parameters. + + Now, you can use the [--parameters][33] and [--parameters-file][34] options with the + [dsc config][35] commands to pass values for any parameter defined in the configuration document. + +
Related work items + + - Issues: [#49][#49] + - PRs: + - [#291][#291] + - [#294][#294] + +
+ ## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14 @@ -472,6 +490,12 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [30]: docs/reference/schemas/config/functions/concat.md [31]: docs/reference/schemas/config/functions/resourceId.md + +[32]: docs/reference/schemas/config/functions/parameters.md +[33]: docs/reference/cli/config/command.md#-p---parameters +[34]: docs/reference/cli/config/command.md#-f---parameters_file +[35]: docs/reference/cli/config/command.md + [#107]: https://github.com/PowerShell/DSC/issues/107 [#121]: https://github.com/PowerShell/DSC/issues/121 @@ -510,7 +534,10 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#241]: https://github.com/PowerShell/DSC/issues/241 [#248]: https://github.com/PowerShell/DSC/issues/248 [#252]: https://github.com/PowerShell/DSC/issues/252 +[#291]: https://github.com/PowerShell/DSC/issues/291 +[#294]: https://github.com/PowerShell/DSC/issues/294 [#45]: https://github.com/PowerShell/DSC/issues/45 +[#49]: https://github.com/PowerShell/DSC/issues/49 [#57]: https://github.com/PowerShell/DSC/issues/57 [#73]: https://github.com/PowerShell/DSC/issues/73 [#98]: https://github.com/PowerShell/DSC/issues/98 diff --git a/docs/reference/cli/config/command.md b/docs/reference/cli/config/command.md index 6ad96046..c9ac0350 100644 --- a/docs/reference/cli/config/command.md +++ b/docs/reference/cli/config/command.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config' command -ms.date: 09/06/2023 +ms.date: 02/05/2024 ms.topic: reference title: dsc config --- @@ -62,6 +62,42 @@ information. For example, `dsc config --help` or `dsc config set --help`. ## Options +### -f, --parameters_file + +Specifies the path to a data file containing the parameters to pass to the configuration as JSON or +YAML. When you specify this option, DSC interprets the keys in the data file as parameters and uses +the specified values. The values in the data file override any defaults defined in the +configuration itself. + +The data file must contain an object with the `parameters` key. The value of the `parameters` key +must be an object where each key is the name of a defined parameter and each value is a valid value +for that parameter. + +This option can't be used with the `--parameters` option. Choose whether to pass the parameters as +a data string with the `--parameters` option or in a data file with the `--parameters_file` option. + +For more information about defining parameters in a configuration document, see +[DSC Configuration document parameter schema][06]. For more information about using parameters in +configuration document, see the [parameters function reference][07]. + +### -p, --parameters + +Specifies the parameters to pass to the configuration as a JSON or YAML string. When you specify +this option, DSC interprets the keys in the data string as parameters and uses the specified +values. The values in the data string override any defaults defined in the configuration itself. + +The data string must contain an object with the `parameters` key. The value of the `parameters` key +must be an object where each key is the name of a defined parameter and each value is a valid value +for that parameter. + +This option can't be used with the `--parameters_file` option. Choose whether to pass the +parameters as a data string with the `--parameters` option or in a data file with the +`--parameters_file` option. + +For more information about defining parameters in a configuration document, see +[DSC Configuration document parameter schema][06]. For more information about using parameters in +configuration document, see the [parameters function reference][07]. + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the @@ -77,3 +113,5 @@ Mandatory: false [03]: get.md [04]: set.md [05]: test.md +[06]: ../../schemas/config/parameter.md +[07]: ../../schemas/config/functions/parameters.md diff --git a/docs/reference/schemas/config/functions/parameters.md b/docs/reference/schemas/config/functions/parameters.md new file mode 100644 index 00000000..808ef09d --- /dev/null +++ b/docs/reference/schemas/config/functions/parameters.md @@ -0,0 +1,112 @@ +--- +description: Reference for the 'parameters' DSC configuration document function +ms.date: 02/05/2024 +ms.topic: reference +title: parameters +--- + +# parameters + +## Synopsis + +Returns the value of a configuration parameter. + +## Syntax + +```Syntax +parameters('') +``` + +## Description + +The `parameters()` function returns the value of a specific parameter. You must pass the name of +a valid parameter. When using this function for a resource instance, DSC validates the instance +properties after this function runs and before calling the resource for the current operation. If +the referenced parameter value is invalid for the property, DSC raises a validation error. + +For more information about defining parameters in a configuration document, see +[DSC Configuration document parameter schema][01]. + +## Examples + +### Example 1 - Use a parameter as a resource instance property value + +The configuration uses the `parameters()` function to echo the value of the `message` parameter. + +```yaml +# parameters.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +parameters: + message: + type: string + defaultValue: Hello, world! +resources: + - name: Echo message parameter + type: Test/Echo + properties: + text: "[parameters('message')]" +``` + +First, get the current state of the configuration without overriding the parameters with the +[--parameters][02] or [`--parameters_file`][03] options. The output shows the default value for the +`message` parameter. + +```bash +config_file=parameters.example.1.dsc.config.yaml +cat $config_file | dsc config get +``` + +```yaml +results: +- name: Echo message parameter + type: Test/Echo + result: + actualState: + text: Hello, world! +messages: [] +hadErrors: false +``` + +Next, override the `message` parameter with the `--parameters` option. + +```bash +params='{"parameters": {"message": "Hi, override."}}' +cat $config_file | dsc config --parameters $params get +``` + +```yaml +results: +- name: Echo message parameter + type: Test/Echo + result: + actualState: + text: Hi, override. +messages: [] +hadErrors: false +``` + +## Parameters + +### name + +The name of the parameter to return. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The output of the function is the value of the specified parameter. + +```yaml +Type: [string, int, bool, object, array] +``` + + +[01]: ../parameter.md +[02]: ../../../cli/config/command.md#-p---parameters +[03]: ../../../cli/config/command.md#-f---parameters_file diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md index 50f78f02..68848545 100644 --- a/docs/reference/schemas/config/parameter.md +++ b/docs/reference/schemas/config/parameter.md @@ -32,6 +32,8 @@ property of the configuration document. The value is an object that defines the Every parameter defines its data type. Parameters may also define a default value, validation checks, a description of their purpose, and arbitrary metadata. +To reference parameters in resource instances, use the [parameters() configuration function][02]. + ## Required Properties - [type](#type) @@ -72,7 +74,7 @@ independent logging or recording that isn't handled by DSC, the value may be sto Use secure strings for passwords and secrets. For more information about data types, see -[DSC configuration parameter data type schema reference][02]. +[DSC configuration parameter data type schema reference][03]. ```yaml Type: string @@ -172,4 +174,5 @@ Required: false ``` [01]: resource.md -[02]: ../definitions/parameters/dataTypes.md +[02]: ./functions/parameters.md +[03]: ../definitions/parameters/dataTypes.md