CHEF-7691 Add resource updates for Client 18.4 (#4231)

* Add resource updates for Client 18.4 Signed-off-by: Ian Maddaus <[email protected]> * powershell_script Signed-off-by: Ian Maddaus <[email protected]> * chocolatey_package Signed-off-by: Ian Maddaus <[email protected]> * powershell_script Signed-off-by: Ian Maddaus <[email protected]> * chocolately_installer Signed-off-by: Ian Maddaus <[email protected]> * Corrections Signed-off-by: Ian Maddaus <[email protected]> --------- Signed-off-by: Ian Maddaus <[email protected]>
chef · Feb 6, 2024 · ebbb17d · ebbb17d
1 parent 5fd761f
commit ebbb17d
Show file tree

Hide file tree

Showing 5 changed files with 286 additions and 56 deletions.
diff --git a/content/resources/chocolatey_installer.md b/content/resources/chocolatey_installer.md
@@ -0,0 +1,19 @@
++++
+title = "chocolatey_installer Resource"
+draft = false
+robots = ""
+gh_repo = "chef-web-docs"
+data_path = ["infra","resources","chocolatey_installer"]
+layout = "infra_resource"
+toc_layout = "infra_resource_toc"
+
+[menu]
+  [menu.infra]
+    title = "chocolatey_installer"
+    identifier = "chef_infra/resources/chocolatey_installer"
+    parent = "chef_infra/resources"
++++
+
+<!-- The contents of this page are automatically generated from the chocolatey_config.yaml file in the data/infra/resources directory. -->
+<!-- To suggest a change, edit the https://github.com/chef/chef/blob/main/lib/chef/resource/chocolatey_installer.rb file and submit a pull request to the https://github.com/chef/chef repository. -->
+<!-- markdownlint-disable-file -->
diff --git a/data/infra/resources/chocolatey_installer.yaml b/data/infra/resources/chocolatey_installer.yaml
@@ -0,0 +1,94 @@
+---
+resource_reference: true
+resources_common_guards: true
+resources_common_notification: true
+resources_common_properties: true
+resource: chocolatey_installer
+resource_description_list:
+- markdown: Use the chocolatey_installer resource to install the Chocolatey package manager. Use the chocolatey_feature resource to customize
+    your install and the chocolatey_package resource to install packages.
+resource_new_in: '18.4'
+syntax_full_code_block: |-
+  chocolatey_installer 'name' do
+    chocolatey_version      String
+    download_url            String
+    ignore_proxy            true, false # default value: false
+    proxy_password          String
+    proxy_url               String
+    proxy_user              String
+    use_native_unzip        true, false # default value: false
+    action                  Symbol # defaults to :install if not specified
+  end
+syntax_properties_list:
+syntax_full_properties_list:
+- "`chocolatey_installer` is the resource."
+- "`name` is the name given to the resource block."
+- "`action` identifies which steps Chef Infra Client will take to bring the node into
+  the desired state."
+- "`chocolatey_version`, `download_url`, `ignore_proxy`, `proxy_password`, `proxy_url`,
+  `proxy_user`, and `use_native_unzip` are the properties available to this resource."
+actions_list:
+  :nothing:
+    shortcode: resources_common_actions_nothing.md
+  :install:
+    markdown: Installs Chocolatey package manager (default).
+  :uninstall:
+    markdown: Uninstall Chocolatey package manager.
+  :upgrade:
+    markdown: Upgrades the Chocolatey package manager.
+properties_list:
+- property: chocolatey_version
+  ruby_type: String
+  required: false
+  description_list:
+  - markdown: Specifies a target version of Chocolatey to install. By default, the
+      latest stable version is installed. This will use the value in `$env:ChocolateyVersion`
+      by default if that environment variable is present. This parameter is ignored
+      if you set `download_url`.
+- property: download_url
+  ruby_type: String
+  required: false
+  description_list:
+  - markdown: The URL to download Chocolatey from. This sets the value of `$env:ChocolateyDownloadUrl`
+      and causes the installer to choose an alternate download location. If this is
+      not set, this resource downloads Chocolatey from the official Chocolatey community
+      repository. You can set a path to a `chocolatey.nupkg` file for offline installation.
+- property: ignore_proxy
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  description_list:
+  - markdown: If set, this overrides any configured proxy, proxy environment
+      variables, or parameters. This is enabled if set
+      to a value other than 'false' or '0'.
+- property: proxy_password
+  ruby_type: String
+  required: false
+  description_list:
+  - markdown: The password used to connect to the proxy server with. If set, you must also set `proxy_user`.
+- property: proxy_url
+  ruby_type: String
+  required: false
+  description_list:
+  - markdown: Specifies the proxy URL to use during the download.
+- property: proxy_user
+  ruby_type: String
+  required: false
+  description_list:
+  - markdown: The username used to connect to the proxy server with. If set, you must also set `proxy_password`.
+- property: use_native_unzip
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  description_list:
+  - markdown: If `true`, this resource uses built-in Windows decompression tools instead of 7zip when
+      unpacking the downloaded NuPkg file. This parameter is ignored in PowerShell 5+ in favour of using
+      the `Expand-Archive` built-in PowerShell cmdlet directly.
+examples: "**Install Chocolatey**\n\n```ruby\nchocolatey_installer 'latest' do\n  action
+  :install\nend\n```\n\n**Uninstall Chocolatey**\n\n```ruby\nchocolatey_installer
+  'Some random verbiage' do\n  action :uninstall\nend\n```\n\n**Install Chocolatey
+  with Parameters**\n\n```ruby\nchocolatey_installer 'latest' do\n  action :install\n
+  \ download_url \"https://www.contoso.com/foo\"\n  chocolatey_version '2.12.24'\nend\n```\n\n```ruby\nchocolatey_installer
+  'latest' do\n  action :install\n  download_url \"c:\\foo\foo.nupkg\"\n  chocolatey_version
+  '2.12.24'\nend\n```\n\n**Upgrade Chocolatey with Parameters**\n\n```ruby\nchocolatey_installer
+  'latest' do\n  action :upgrade\n  chocolatey_version '2.12.24'\nend\n```\n"
diff --git a/data/infra/resources/chocolatey_package.yaml b/data/infra/resources/chocolatey_package.yaml
@@ -18,25 +18,28 @@ resource_description_list:
 resource_new_in: '12.7'
 syntax_full_code_block: |-
   chocolatey_package 'name' do
-    list_options      String
-    options           String, Array
-    package_name      String, Array
-    password          String
-    returns           Integer, Array # default value: [0, 2]
-    source            String
-    timeout           String, Integer
-    user              String
-    version           String, Array
-    action            Symbol # defaults to :install if not specified
+    bulk_query          true, false # default value: false
+    list_options        String
+    options             String, Array
+    package_name        String, Array
+    password            String
+    returns             Integer, Array # default value: [0, 2]
+    source              String
+    timeout             String, Integer
+    use_choco_list      true, false # default value: false
+    user                String
+    version             String, Array
+    action              Symbol # defaults to :install if not specified
   end
 syntax_properties_list:
 syntax_full_properties_list:
 - "`chocolatey_package` is the resource."
 - "`name` is the name given to the resource block."
 - "`action` identifies which steps Chef Infra Client will take to bring the node into
   the desired state."
-- "`list_options`, `options`, `package_name`, `password`, `returns`, `source`, `timeout`,
-  `user`, and `version` are the properties available to this resource."
+- "`bulk_query`, `list_options`, `options`, `package_name`, `password`, `returns`,
+  `source`, `timeout`, `use_choco_list`, `user`, and `version` are the properties
+  available to this resource."
 actions_list:
   :nothing:
     shortcode: resources_common_actions_nothing.md
@@ -51,6 +54,13 @@ actions_list:
     markdown: Purge a package. This action typically removes the configuration files
       as well as the package.
 properties_list:
+- property: bulk_query
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  description_list:
+  - markdown: Whether to bulk query the Chocolatey server. This makes the provider list
+      all packages instead of doing individual queries.
 - property: list_options
   ruby_type: String
   required: false
@@ -86,15 +96,19 @@ properties_list:
   ruby_type: String
   required: false
   description_list:
-  - markdown: 'The optional path to a package on the local file system or a
-      reachable UNC path. Ensure that the path specified is to the
-      **folder** containing the chocolatey package(s), not to the package
-      itself.'
+  - markdown: The optional path to a package on the local file system.
 - property: timeout
   ruby_type: String, Integer
   required: false
   description_list:
   - markdown: The amount of time (in seconds) to wait before timing out.
+- property: use_choco_list
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  description_list:
+  - markdown: Whether to use `choco list` for getting locally installed packages instead of querying for NuGet package files.
+      This defaults to `false` since reading the package data is faster.
 - property: user
   ruby_type: String
   required: false

diff --git a/data/infra/resources/powershell_script.yaml b/data/infra/resources/powershell_script.yaml
@@ -6,14 +6,9 @@ resources_common_properties: true
 resource: powershell_script
 resource_description_list:
 - markdown: |-
-    Use the **powershell_script** resource to execute a script using the Windows PowerShell interpreter, much like how the script
-    and script-based resources **bash**, **csh**, **perl**, **python**, and **ruby** are used. The **powershell_script** resource
-    is specific to the Microsoft Windows platform, but may use both the Windows PowerShell interpreter or the PowerShell Core (pwsh)
-    interpreter as of Chef Infra Client 16.6 and later.
-
-    The **powershell_script** resource creates and executes a temporary file rather than running the command inline. Commands that are
-    executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run.
-    Use `not_if` and `only_if` conditionals to guard this resource for idempotence.
+    Use the **powershell_script** resource to execute a script using the Windows PowerShell interpreter, much like how the script and script-based resources **bash**, **csh**, **perl**, **python**, and **ruby** are used. The **powershell_script** resource is specific to the Microsoft Windows platform, but may use both the Windows PowerShell interpreter or the PowerShell Core (pwsh) interpreter as of Chef Infra Client 16.6 and later.
+
+    The **powershell_script** resource creates and executes a temporary file rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use `not_if` and `only_if` conditionals to guard this resource for idempotence.
 syntax_description: |
   A **powershell_script** resource block executes a batch script using the Windows PowerShell interpreter.
   For example, writing to an interpolated path:
@@ -34,7 +29,6 @@ syntax_full_code_block: |-
     convert_boolean_return      true, false # default value: false
     creates                     String
     cwd                         String
-    default_env                 true, false # default value: false
     domain                      String
     elevated                    true, false # default value: false
     environment                 Hash
@@ -43,10 +37,10 @@ syntax_full_code_block: |-
     input                       String
     interpreter                 String # default value: "powershell"
     live_stream                 true, false # default value: false
-    login                       true, false # default value: false
     password                    String
     returns                     Integer, Array # default value: 0
     timeout                     Integer, String, Float # default value: 3600
+    use_inline_powershell       true, false # default value: false
     user                        String, Integer
     action                      Symbol # defaults to :run if not specified
   end
@@ -56,31 +50,16 @@ syntax_full_properties_list:
 - "`name` is the name given to the resource block."
 - "`action` identifies which steps Chef Infra Client will take to bring the node into
   the desired state."
-- "`architecture`, `code`, `command`, `convert_boolean_return`, `creates`, `cwd`, `domain`,
-  `elevated`, `environment`, `flags`, `group`, `guard_interpreter`, `input`, `interpreter`, `live_stream`,
-  `password`, `returns`, `timeout`, and `user` are the properties available
-  to this resource."
+- "`code`, `command`, `convert_boolean_return`, `creates`, `cwd`, `domain`,
+  `elevated`, `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`,
+  `password`, `returns`, `timeout`, `use_inline_powershell`, and `user` are
+  the properties available to this resource."
 actions_list:
   :nothing:
     shortcode: resources_common_actions_nothing.md
   :run:
     markdown: Run a command. (default)
 properties_list:
-- property: architecture
-  ruby_type: Symbol
-  required: false
-  description_list:
-  - markdown: 'The architecture of the process under which a script is executed. If
-
-      a value is not provided, Chef Infra Client defaults to the correct
-
-      value for the architecture, as determined by Ohai. An exception is
-
-      raised when anything other than `:i386` is specified for a 32-bit
-
-      process. Possible values: `:i386` (for 32-bit processes) and
-
-      `:x86_64` (for 64-bit processes).'
 - property: code
   ruby_type: String
   required: true
@@ -161,10 +140,9 @@ properties_list:
   ruby_type: String
   required: false
   description_list:
-  - markdown: | 
+  - markdown: |
       A string that is passed to the Windows PowerShell command
       value (Windows PowerShell 3.0+):
-
       - `-NoLogo`
       - `-NonInteractive`
       - `-NoProfile`
@@ -181,11 +159,8 @@ properties_list:
   default_value: :powershell_script
   description_list:
   - markdown: 'When this property is set to `:powershell_script`, the 64-bit
-
       version of the Windows PowerShell shell will be used to evaluate
-
       strings values for the `not_if` and `only_if` properties. Set this
-
       value to `:default` to use the 32-bit version of the cmd.exe shell.'
 - property: input
   ruby_type: String
@@ -212,7 +187,7 @@ properties_list:
   required: false
   new_in: '12.21'
   description_list:
-  - markdown: '**Windows only**. The password of the user specified by the user property.
+  - markdown: '**Windows only** The password of the user specified by the user property.
       This property is mandatory if user is specified on Windows and may only be specified
       if user is specified. The sensitive property for this resource will automatically
       be set to true if password is specified.'
@@ -229,6 +204,16 @@ properties_list:
   default_value: '3600'
   description_list:
   - markdown: The amount of time (in seconds) a command is to wait before timing out.
+- property: use_inline_powershell
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  new_in: '18.4'
+  description_list:
+  - markdown: Use the inline PowerShell DLL rather than shelling out. The PowerShell DLL is faster,
+      but its semantics could be different from shelling out. In particular,
+      it doesn't allow for streaming output, nor does it allow for passing custom
+      parameters to the interpreter.
 - property: user
   ruby_type: String, Integer
   required: false