win_chocolatey: refactor module to fix bugs and add new features (#43013)

* win_chocolatey: refactor module to fix bugs and add new features

* Fix some typos and only emit install warning not in check mode

* Fixes when testing out installing chocolatey from a server

* Added changelog fragment
This commit is contained in:
Jordan Borean 2018-07-24 07:52:13 +10:00 committed by GitHub
commit 93c05074ee
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 1267 additions and 600 deletions

File diff suppressed because it is too large Load diff

View file

@ -2,6 +2,7 @@
# -*- coding: utf-8 -*-
# Copyright: (c) 2014, Trond Hindenes <trond@hindenes.com>
# Copyright: (c) 2018, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# this is a windows documentation stub. actual code lives in the .ps1
@ -17,111 +18,184 @@ module: win_chocolatey
version_added: "1.9"
short_description: Manage packages using chocolatey
description:
- Manage packages using Chocolatey (U(http://chocolatey.org/)).
- If Chocolatey is missing from the system, the module will install it.
- List of packages can be found at U(http://chocolatey.org/packages).
- Manage packages using Chocolatey (U(http://chocolatey.org/)).
- If Chocolatey is missing from the system, the module will install it.
- List of packages can be found at U(http://chocolatey.org/packages).
requirements:
- chocolatey >= 0.10.5 (will be upgraded if older)
options:
name:
description:
- Name of the package to be installed.
- This must be a single package name.
required: yes
state:
description:
- State of the package on the system.
choices:
- absent
- downgrade
- latest
- present
- reinstalled
default: present
force:
description:
- Forces install of the package (even if it already exists).
- Using C(force) will cause ansible to always report that a change was made.
type: bool
default: 'no'
version:
description:
- Specific version of the package to be installed.
- Ignored when C(state) is set to C(absent).
source:
description:
- Specify source rather than using default chocolatey repository.
architecture:
description:
- Allows installation of alternative architecture packages, for example,
32bit on 64bit windows.
version_added: '2.7'
choices:
- default
- x86
default: default
install_args:
description:
- Arguments to pass to the native installer.
version_added: '2.1'
params:
description:
- Parameters to pass to the package
version_added: '2.1'
allow_empty_checksums:
description:
- Allow empty checksums to be used.
- Allow empty checksums to be used for downloaded resource from non-secure
locations.
- Use M(win_chocolatey_feature) with the name C(allowEmptyChecksums) to
control this option globally.
type: bool
default: 'no'
version_added: '2.2'
allow_prerelease:
description:
- Allow the installation of pre-release packages.
- If I(state) is C(latest), the latest pre-release package will be
installed.
type: bool
default: 'no'
version_added: '2.6'
architecture:
description:
- Force Chocolatey to install the package of a specific process
architecture.
- When setting C(x86), will ensure Chocolatey installs the x86 package
even when on an x64 bit OS.
choices:
- default
- x86
default: default
version_added: '2.7'
force:
description:
- Forces the install of a package, even if it already is installed.
- Using I(force) will cause Ansible to always report that a change was
made.
type: bool
default: 'no'
install_args:
description:
- Arguments to pass to the native installer.
- These are arguments that are passed directly to the installer the
Chocolatey package runs, this is generally an advanced option.
type: str
version_added: '2.1'
ignore_checksums:
description:
- Ignore checksums altogether.
- Ignore the checksums provided by the package.
- Use M(win_chocolatey_feature) with the name C(checksumFiles) to control
this option globally.
type: bool
default: 'no'
version_added: '2.2'
ignore_dependencies:
description:
- Ignore dependencies, only install/upgrade the package itself.
- Ignore dependencies, only install/upgrade the package itself.
type: bool
default: 'no'
version_added: '2.1'
timeout:
name:
description:
- The time to allow chocolatey to finish before timing out.
type: int
default: 2700
version_added: '2.3'
aliases: [ execution_timeout ]
skip_scripts:
- Name of the package(s) to be installed.
- Set to C(all) to run the action on all the installed packages.
required: yes
type: list
package_params:
description:
- Do not run I(chocolateyInstall.ps1) or I(chocolateyUninstall.ps1) scripts.
type: bool
default: 'no'
version_added: '2.4'
- Parameters to pass to the package.
- These are parameters specific to the Chocolatey package and are generally
documented by the package itself.
- Before Ansible 2.7, this option was just I(params).
type: str
version_added: '2.1'
aliases:
- params
proxy_url:
description:
- Proxy url used to install chocolatey and the package.
- Proxy URL used to install chocolatey and the package.
- Use M(win_chocolatey_config) with the name C(proxy) to control this
option globally.
type: str
version_added: '2.4'
proxy_username:
description:
- Proxy username used to install chocolatey and the package.
- When dealing with a username with double quote characters C("), they
need to be escaped with C(\) beforehand. See examples for more details.
- Proxy username used to install Chocolatey and the package.
- Before Ansible 2.7, users with double quote characters C(") would need to
be escaped with C(\) beforehand. This is no longer necessary.
- Use M(win_chocolatey_config) with the name C(proxyUser) to control this
option globally.
type: str
version_added: '2.4'
proxy_password:
description:
- Proxy password used to install chocolatey and the package.
- See notes in C(proxy_username) when dealing with double quotes in a
password.
- Proxy password used to install Chocolatey and the package.
- This value is exposed as a command argument and any privileged account
can see this value when the module is running Chocolatey, define the
password on the global config level with M(win_chocolatey_config) with
name C(proxyPassword) to avoid this.
type: str
version_added: '2.4'
allow_prerelease:
skip_scripts:
description:
- Allow install of prerelease packages.
- If state C(state) is C(latest) the highest prerelease package will be installed.
- Do not run I(chocolateyInstall.ps1) or I(chocolateyUninstall.ps1) scripts
when installing a package.
type: bool
default: 'no'
version_added: '2.6'
version_added: '2.4'
source:
description:
- Specify the source to retrieve the package from.
- Use M(win_chocolatey_source) to manage global sources.
- This value can either be the URL to a Chocolatey feed, a path to a folder
containing C(.nupkg) packages or the name of a source defined by
M(win_chocolatey_source).
- This value is also used when Chocolatey is not installed as the location
of the install.ps1 script and only supports URLs for this case.
type: str
source_username:
description:
- A username to use with I(source) when accessing a feed that requires
authentication.
- It is recommended you define the credentials on a source with
M(win_chocolatey_source) instead of passing it per task.
type: str
version_added: '2.7'
source_password:
description:
- The password for I(source_username).
- This value is exposed as a command argument and any privileged account
can see this value when the module is running Chocolatey, define the
credentials with a source with M(win_chocolatey_source) to avoid this.
type: str
version_added: '2.7'
state:
description:
- State of the package on the system.
- When C(absent), will ensure the package is not installed.
- When C(present), will ensure the package is installed.
- When C(downgrade), will allow Chocolatey to downgrade a package if
I(version) is older than the installed version.
- When C(latest), will ensure the package is installed to the latest
available version.
- When C(reinstalled), will uninstall and reinstall the package.
choices:
- absent
- downgrade
- latest
- present
- reinstalled
default: present
type: str
timeout:
description:
- The time to allow chocolatey to finish before timing out.
type: int
default: 2700
version_added: '2.3'
aliases:
- execution_timeout
validate_certs:
description:
- Used when downloading the Chocolatey install script if Chocolatey is not
already installed, this does not affect the Chocolatey package install
process.
- When C(no), no SSL certificates will be validated.
- This should only be used on personally controlled sites using self-signed
certificate.
type: bool
default: 'yes'
version_added: '2.7'
version:
description:
- Specific version of the package to be installed.
- Ignored when I(state) is set to C(absent).
type: str
notes:
- Provide the C(version) parameter value as a string (e.g. C('6.1')), otherwise it
is considered to be a floating-point number and depending on the locale could
@ -130,15 +204,22 @@ notes:
- When using verbosity 4 (C(-vvvv)) the C(stdout) output will be more verbose.
- When using verbosity 5 (C(-vvvvv)) the C(stdout) output will include debug output.
- This module will install or upgrade Chocolatey when needed.
- Some packages need an interactive user logon in order to install. You can use (C(become)) to achieve this.
- Even if you are connecting as local Administrator, using (C(become)) to become Administrator will give you an interactive user logon, see examples below.
- Use (M(win_hotfix) to install hotfixes instead of (M(win_chocolatey)) as (M(win_hotfix)) avoids using wusa.exe which cannot be run remotely.
- Some packages, like hotfixes or updates need an interactive user logon in
order to install. You can use (C(become)) to achieve this, see
:doc:`/user_guide/become`.
- Even if you are connecting as local Administrator, using (C(become)) to
become Administrator will give you an interactive user logon, see examples
below.
- If (C(become)) is unavailable, use (M(win_hotfix) to install hotfixes instead
of (M(win_chocolatey)) as (M(win_hotfix)) avoids using wusa.exe which cannot
be run without (C(become)).
author:
- Trond Hindenes (@trondhindenes)
- Peter Mounce (@petemounce)
- Pepe Barbe (@elventear)
- Adam Keech (@smadam813)
- Pierre Templier (@ptemplier)
- Jordan Borean (@jborean93)
'''
# TODO:
@ -166,19 +247,37 @@ EXAMPLES = r'''
- name: Install notepadplusplus 32 bit version
win_chocolatey:
name: notepadplusplus
architecture: 'x86'
architecture: x86
- name: Install git from specified repository
win_chocolatey:
name: git
source: https://someserver/api/v2/
- name: Install git from a pre configured source (win_chocolatey_source)
win_chocolatey:
name: git
source: internal_repo
- name: ensure Chocolatey itself is installed and use internal repo as source
win_chocolatey:
name: chocolatey
source: http://someserver/chocolatey
- name: Uninstall git
win_chocolatey:
name: git
state: absent
- name: Install multiple packages
win_chocolatey:
name:
- procexp
- putty
- windirstat
state: present
- name: Install multiple packages sequentially
win_chocolatey:
name: '{{ item }}'
state: present
@ -189,12 +288,11 @@ EXAMPLES = r'''
- name: uninstall multiple packages
win_chocolatey:
name: '{{ item }}'
name:
- procexp
- putty
- windirstat
state: absent
with_items:
- procexp
- putty
- windirstat
- name: Install curl using proxy
win_chocolatey:
@ -203,13 +301,6 @@ EXAMPLES = r'''
proxy_username: joe
proxy_password: p@ssw0rd
- name: Install curl with proxy credentials that contain quotes
win_chocolatey:
name: curl
proxy_url: http://proxy-server:8080/
proxy_username: user with \"escaped\" double quotes
proxy_password: pass with \"escaped\" double quotes
- name: Install a package that requires 'become'
win_chocolatey:
name: officepro2013