CHEF-7691 Add resource updates for Client 18.4

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 -->

data/infra/resources/chocolatey_installer.yaml

@@ -0,0 +1,99 @@
+---
+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.3'
+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 download_url is set.
+- 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, Chocolatey is downloaded from the official Chocolatey community
+      repository. It can also be used for offline installation
+      by providing a path to a Chocolatey.nupkg.
+- 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 to use to build a proxy credential with. Will be consumed
+      by the proxy_credential property if both this property and proxy_user are set.
+- 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 to use to build a proxy credential with. Will be consumed
+      by the proxy_credential property if both this property and proxy_password are
+      set
+- property: use_native_unzip
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  description_list:
+  - markdown: If set, uses built-in Windows decompression tools instead of 7zip when
+      unpacking the downloaded nupkg. This will be set by default if use_native_unzip
+      is set to a value other than 'false' or '0'. This parameter will be ignored
+      in PS 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"

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
@@ -50,7 +53,20 @@ actions_list:
   :purge:
     markdown: Purge a package. This action typically removes the configuration files
       as well as the package.
+  :reconfig:
+    markdown:
+  :lock:
+    markdown:
+  :unlock:
+    markdown:
 properties_list:
+- property: bulk_query
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  description_list:
+  - markdown: Bulk query the chocolatey server?  This will cause the provider to list
+      all packages instead of doing individual queries.
 - property: list_options
   ruby_type: String
   required: false
@@ -86,15 +102,20 @@ 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: Use choco list for getting the locally installed packages, rather than
+      reading the nupkg database directly?  This defaults to false, since reading
+      the package data is faster.
 - property: user
   ruby_type: String
   required: false

data/infra/resources/powershell_script.yaml

@@ -6,27 +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.
-syntax_description: |
-  A **powershell_script** resource block executes a batch script using the Windows PowerShell interpreter.
-  For example, writing to an interpolated path:
+    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.
 
-  ```ruby
-  powershell_script 'write-to-interpolated-path' do
-    code <<-EOH
-    $stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt"
-    $stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.")
-    $stream.close()
-    EOH
-  end
-  ```
+    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_full_code_block: |-
   powershell_script 'name' do
     code                        String
@@ -47,6 +29,7 @@ syntax_full_code_block: |-
     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 +39,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`, `default_env`, `domain`,
+  `elevated`, `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`,
+  `login`, `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
@@ -128,6 +96,14 @@ properties_list:
   required: false
   description_list:
   - markdown: The current working directory from which the command will be run.
+- property: default_env
+  ruby_type: true, false
+  required: false
+  default_value: 'false'
+  new_in: '14.2'
+  description_list:
+  - markdown: When true this enables ENV magic to add path_sanity to the PATH and
+      force the locale to English+UTF-8 for parsing output
 - property: domain
   ruby_type: String
   required: false
@@ -161,32 +137,12 @@ properties_list:
   ruby_type: String
   required: false
   description_list:
-  - markdown: | 
-      A string that is passed to the Windows PowerShell command
-      value (Windows PowerShell 3.0+):
-
-      - `-NoLogo`
-      - `-NonInteractive`
-      - `-NoProfile`
-      - `-ExecutionPolicy Bypass`
-      - `-InputFormat None`
+  - markdown: A string that's passed to the Windows PowerShell command
 - property: group
   ruby_type: String, Integer
   required: false
   description_list:
   - markdown: The group name or group ID that must be changed before running a command.
-- property: guard_interpreter
-  ruby_type: Symbol
-  required: false
-  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
   required: false
@@ -212,7 +168,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 +185,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