windows-formula

A SaltStack formula for Windows operating systems inspired by salt-formula-linux.

Tested Windows Operating Systems:

• Windows 10, version 1909
• Windows 10, version 1903
• Windows 10, version 1809
• Windows 10, version 1803
• Windows 10, version 1709
• Windows Server 2019, version 1809
• Windows Server 2016, version 1607
• Windows Server 2012 R2

Table of Contents

General notes

See the full SaltStack Formulas installation and usage instructions.

If you want to use this formula, please pay attention to the FORMULA file and/or git tag, which contains the currently released version. This formula is versioned according to Semantic Versioning.

See Formula Versioning Section for more details.

If you need (non-default) configuration, please pay attention to the pillar.example file and/or Special notes section.

Available states

windows

"Meta-state (This is a state that includes other states).

This installs the windows package, manages the windows configuration file and then starts the associated windows service.ku

windows.states

This state uses a jinja macro to render salt state modules dynamically from the windows.states pillar dictionary.

Optional

These optional dictionary keys can be included with each state definition defined in the pillar.

enabled (bool)

Enabled or disable rendering of a state included in the pillar dictionary. If the key is not present, it is assumed to be true.

id (str)

If provided, id will be used as the ID Declaration suffix, instead of name in the format windows.state.state_name.state_function_name.id.

global arguments

The use of requisites and other global state arguments is supported but has not been exhaustively tested.

Example 1:

The following pillar definition implements the salt.states.timezone.system state module:

windows:
  states:
    enabled: true
    timezone:
      system:
        name: America/New_York
        utc: false

It is rendered as:

windows.state.timezone.system.America/New_York:
  timezone.system:
    - name: America/New_York
    - utc: False

Example 2:

The following pillar definition implements the salt.states.win_system.computer_desc, salt.states.win_system.hostname, salt.states.win_system.reboot, salt.states.timezone.system, and salt.states.win_wua.uptodate state modules, uses the optional enabled and id keys and includes the use of the require requisite.

windows:
  states:
    enabled: true
    system:
      computer_desc:
        enabled: true
        id: description
        name: "Saltstack Computer Description"
        require:
          - windows.state.system.hostname.saltstack1
      hostname:
        name: "saltstack1"
      reboot:
        enabled: false
        message: rebooting in 60 seconds
        timeout: 60
        in_seconds: true
    timezone:
      system:
        name: America/New_York
        utc: false
    wua:
      uptodate:
        enabled: true
        software: true
        drivers: true
        skip_hidden: false
        skip_mandatory: false
        skip_reboot: false
        categories:
          - Critical Updates
          - Definition Updates
          - Drivers
          - Feature Packs
          - Security Updates
          - Update Rollups
          - Updates
          - Update Rollups
          - Windows Defender
        severities:
          - Critical
          - Important

The system.reboot state is not rendered as this example has an enabled key set to false.

windows.state.system.computer_desc.description:
  system.computer_desc:
    - name: Saltstack Computer Description
    - require:
        - windows.state.system.hostname.saltstack1

windows.state.system.hostname.saltstack1:
  system.hostname:
    - name: saltstack1

windows.state.timezone.system.America/New_York:
  timezone.system:
    - name: America/New_York
    - utc: False

windows.state.wua.uptodate:
  wua.uptodate:
    - software: True
    - drivers: True
    - skip_hidden: False
    - skip_mandatory: False
    - skip_reboot: False
    - categories:
        - Critical Updates
        - Definition Updates
        - Drivers
        - Feature Packs
        - Security Updates
        - Update Rollups
        - Updates
        - Update Rollups
        - Windows Defender
    - severities:
        - Critical
        - Important

This approach is modular and creates a direct relationship between pillars and states , however, there are several tradeoffs.

#. The pure jinja implementation does not go Easy on the Jinja so changes to the macro can be difficult to debug. #. Theoritaclly, this could be used to implement any state, which makes exhaustive testing difficult. Report any issues that are found.

A maximum dept of four is currently supported.

While this state is not windows specific, it has only been tested within the scope of this formula.

windows.modules

This state uses a jinja macro to render salt execution modules from pillar dictionaries.

While this state is not windows specific, it has only been tested within the scope of this formula.

Testing

Linux testing is done with kitchen-salt.

Requirements

• Ruby
• Docker
• Vagrant 2.2.7
• Virtualbox 6.1

$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]

Where [platform] is the platform name defined in kitchen.yml, e.g. debian-9-2019-2-py3.

bin/kitchen converge

Creates the docker instance and runs the windows main state, ready for testing.

bin/kitchen verify

Runs the inspec tests on the actual instance.

bin/kitchen destroy

Removes the docker instance.

bin/kitchen test

Runs all of the stages above in one go: i.e. destroy + converge + verify + destroy.

bin/kitchen login

Gives you SSH access to the instance for manual testing.

Manually Run salt on windows:

C:\Windows\system32\cmd.exe /c ""C:\salt\salt-call.bat" --state-output=changes --config-dir=C:\Users\vagrant\AppData\Local\Temp\kitchen\etc\salt state.highstate --log-level=trace --retcode-passthrough"

SaltStack installation

Masterless Minion

https://docs.saltstack.com/en/develop/topics/installation/windows.html

https://raw.githubusercontent.com/saltstack/salt-bootstrap/v2019.10.03/bootstrap-salt.ps1 https://github.com/saltstack/salt-bootstrap/blob/v2019.10.03/bootstrap-salt.ps1

Contributing to this repo

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.

Commit message formatting is significant!!

Please see How to contribute for more details.

Commit Message Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

` <type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>`

The header is mandatory and the scope of the header is optional.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Type

Must be one of the following:

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing or correcting existing tests
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Scope

The scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

You can use * when the change affects more than a single scope.

Subject

The subject contains succinct description of the change:

• use the imperative, present tense: "change" not "changed" nor "changes"
• don't capitalize first letter
• no dot (.) at the end

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to [reference GitHub issues that this commit closes][closing-issues].

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

A detailed explanation can be found in this document.

Special notes

None

Examples

windows.state.system.computer_desc.description:
  system.computer_desc:
    - name: Saltstack Computer Description
    - require:
      - windows.state.system.hostname.saltstack1
windows.state.system.hostname.saltstack1:
  system.hostname:
    - name: saltstack1
windows.state.timezone.system.America/New_York:
  timezone.system:
    - name: America/New_York
    - utc: False

windows.module.system.reboot:
  module.run:
    - system.reboot:
      - timeout: 5
      - in_seconds: True
      - only_on_pending_reboot: True
      - wait_for_reboot: False
    - order: last
windows.module.user.current:
  module.run:
    - user.current:
      - sam: True
windows.module.status.uptime:
  module.run:
    - status.uptime:
      - human_readable: True
    - require:
      - windows.module.user.current

ToDo

1. discuss with windows working group: https://github.com/saltstack/community/tree/master/working_groups/wg-Windows
2. Salt builds: https://jenkinsci.saltstack.com/, noxfile.py, https://nox.thea.codes/en/stable/