ansible.windows.win_environment (2.3.0) — module

Install collection

Install with ansible-galaxy collection install ansible.windows:==2.3.0

Add to requirements.yml

  collections:
    - name: ansible.windows
      version: 2.3.0

Description

Uses .net Environment to set or remove environment variables and can set at User, Machine or Process level.

User level environment variables will be set, but not available until the user has logged off and on again.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Set an environment variable for all users
  ansible.windows.win_environment:
    state: present
    name: TestVariable
    value: Test value
    level: machine

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Remove an environment variable for the current user
  ansible.windows.win_environment:
    state: absent
    name: TestVariable
    level: user

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Set several variables at once
  ansible.windows.win_environment:
    level: machine
    variables:
      TestVariable: Test value
      CUSTOM_APP_VAR: 'Very important value'
      ANOTHER_VAR: '{{ my_ansible_var }}'

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Set and remove multiple variables at once
  ansible.windows.win_environment:
    level: user
    variables:
      TestVariable: Test value
      CUSTOM_APP_VAR: 'Very important value'
      ANOTHER_VAR: '{{ my_ansible_var }}'
      UNWANTED_VAR: ''  # < this will be removed

Inputs

    
name:
    description:
    - The name of the environment variable. Required when I(state=absent).
    type: str

level:
    choices:
    - machine
    - process
    - user
    description:
    - The level at which to set the environment variable.
    - Use C(machine) to set for all users.
    - Use C(user) to set for the current user that ansible is connected as.
    - Use C(process) to set for the current process.  Probably not that useful.
    required: true
    type: str

state:
    choices:
    - absent
    - present
    description:
    - Set to C(present) to ensure environment variable is set.
    - Set to C(absent) to ensure it is removed.
    - When using I(variables), do not set this option.
    type: str

value:
    description:
    - The value to store in the environment variable.
    - Must be set when I(state=present) and cannot be an empty string.
    - Should be omitted for I(state=absent) and I(variables).
    type: str

variables:
    description:
    - A dictionary where multiple environment variables can be defined at once.
    - Not valid when I(state) is set. Variables with a value will be set (C(present))
      and variables with an empty value will be unset (C(absent)).
    - I(level) applies to all vars defined this way.
    type: dict
    version_added: 1.3.0
    version_added_collection: ansible.windows

Outputs

before_value:
  description: the value of the environment key before a change, this is null if it
    didn't exist
  returned: always
  sample: C:\Windows\System32
  type: str
value:
  description: the value the environment key has been set to, this is null if removed
  returned: always
  sample: C:\Program Files\jdk1.8
  type: str
values:
  description: dictionary of before and after values; each key is a variable name,
    each value is another dict with C(before), C(after), and C(changed) keys
  returned: always
  type: dict
  version_added: 1.3.0
  version_added_collection: ansible.windows

See also

• ansible.windows.win_path