Salt 2019.2.0 Release Notes - Codename Fluorine¶

Python 2.7 Deprecation¶

In light of Python 2.7 reaching its End of Life (EOL) on Jan 1st 2020, Python 2 will be deprecated from SaltStack no earlier than the 3001 release, that is either the 3001 release or a later release. This decision is pending further community discussion.

Known Issues¶

The following are known issues for the 2019.2.0 release and will be fixed for 2019.2.1:

• #51699

Non-Backward-Compatible Change to YAML Renderer¶

In earlier releases, this was considered valid usage in Python 2, assuming that data was a list or dictionary containing keys/values which are unicode types:

/etc/foo.conf:
  file.managed:
    - source: salt://foo.conf.jinja
    - template: jinja
    - context:
        data: {{ data }}

One common use case for this is when using one of Salt's custom Jinja filters which return lists or dictionaries, such as the ipv4 filter.

In Python 2, Jinja will render the unicode string types within the list/dictionary with the "u" prefix (e.g. {u'foo': u'bar'}). While not valid YAML, earlier releases would successfully load these values.

As of this release, the above SLS would result in an error message. To allow for a data structure to be dumped directly into your SLS file, use the tojson Jinja filter:

/etc/foo.conf:
  file.managed:
    - source: salt://foo.conf.jinja
    - template: jinja
    - context:
        data: {{ data|tojson }}

Another example where the new filter needs to be used is the following state example:

grafana_packages:
  pkg.installed:
  - names: {{ server.pkgs }}

This will fail when pkgs is a list or dictionary. You will need to update the state:

grafana_packages:
  pkg.installed:
  - names: {{ server.pkgs|tojson }}

This test case has also been tested with the yaml and json filters successfully.

Ansible Playbook State and Execution Modules¶

Along with the including the ansible modules in the Oxygen release, running playbooks has been added in 2019.2.0 with the playbooks function. This also includes an ansible playbooks state module which can be used on a targeted host to run ansible playbooks, or used in an orchestration state runner.

install nginx:
  ansible.playbooks:
    - name: install.yml
    - git_repo: git://github.com/gtmanfred/playbook.git
    - git_kwargs:
        rev: master

The playbooks modules also includes the ability to specify a git repo to clone and use, or a specific directory can to used when running the playbook.

Network Automation¶

Beginning with this release, Salt provides much broader support for a variety of network operating systems, and features for configuration manipulation or operational command execution.

manage_bgp_and_ntp:
  netconfig.managed:
    - template_name:
        - salt://templates/bgp.jinja
        - salt://templates/ntp.jinja
    - context:
        bpg: {{ pillar.bgp }}
        ntp: {{ pillar.ntp }}

salt '*' net.arp username=my-alt-usr force_reconnect=True

salt '*' net.replace_pattern OLD-POLICY-CONFIG new-policy-config

/var/backups/{{ opts.id }}/running.cfg:
  netconfig.saved:
    - source: running
    - makedirs: true

salt '*' napalm.junos_cli 'show arp' format=xml
salt '*' napalm.junos_rpc get-interface-information

salt '*' napalm.netmiko_commands 'show version' 'show interfaces'
salt '*' napalm.netmiko_config config_file=https://bit.ly/2sgljCB

salt '*' napalm.pyeapi_run_commands 'show version' 'show interfaces'
salt '*' napalm.pyeapi_config config_file=salt://path/to/template.jinja

salt '*' napalm.nxos_api_show 'show bgp sessions' 'show processes' raw_text=False

salt '*' napalm.config_lines_w_child 'interface' 'shutdown'

New Docker Proxy Minion¶

Docker containers can now be treated as actual minions without installing salt in the container, using the new docker proxy minion.

This proxy minion uses the docker executor to pass commands to the docker container using docker.call. Any state module calls are passed through the corresponding function from the docker module.

proxy:
  proxytype: docker
  name: keen_proskuriakova

Terraform Salt-SSH Roster¶

You can now dynamically generate a Salt-SSH roster from the terraform resources defined with terraform-provider-salt.

This allows you to combine both terraform and Salt-SSH to provision and configure your hosts. See the terraform roster for an example on how to setup and use.

Grains Dictionary Passed into Custom Grains¶

Starting in this release, if a custom grains function accepts a variable named grains, the Grains dictionary of the already compiled grains will be passed in. Because of the non-deterministic order that grains are rendered in, the only grains that can be relied upon to be passed in are core.py grains, since those are compiled first.

More Precise virtual Grain¶

This release improves the accuracy of the virtual grain when running Salt in a nested virtualization environment (e.g. systemd-nspawn container inside a VM) and having virt-what installed.

Until now, the virtual grain was determined by matching against all output lines of virt-what instead of individual items which could lead to not quite precise results (e.g. reporting HyperV inside a systemd-nspawn container running within a Hyper-V-based VM.

Configurable Module Environment¶

Salt modules (states, execution modules, returners, etc.) now can have custom environment variables applied when running shell commands. This can be configured by setting a system-environment key either in Grains or Pillar. The syntax is as follows:

system-environment:
  <type>
    <module>:
      # Namespace for all functions in the module
      _:
        <key>: <value>

      # Namespace only for particular function in the module
      <function>:
        <key>: <value>

• <type> would be the type of module (i.e. states, modules, etc.).

• <module> would be the module's name.

  Note

  The module name can be either the virtual name (e.g. pkg), or the physical name (e.g. yumpkg).

• <function> would be the function name within that module. To apply environment variables to all functions in a given module, use an underscore (i.e. _) as the function name. For example, to set the same environment variable for all package management functions, the following could be used:

  system-environment:
    modules:
      pkg:
        _:
          SOMETHING: for_all
  

  To set an environment variable in pkg.install only:

  system-environment:
    modules:
      pkg:
        install:
          LC_ALL: en_GB.UTF-8
  

  To set the same variable but only for SUSE minions (which use zypper for package management):

  system-environment:
    modules:
      zypper:
        install:
          LC_ALL: en_GB.UTF-8
  

"Virtual Package" Support Dropped for APT¶

In APT, some packages have an associated list of packages which they provide. This allows one to do things like run apt-get install foo when the real package name is foo1.0, and get the right package installed.

Salt has traditionally designated as "virtual packages" those which are provided by an installed package, but for which there is no real package by that name installed. Given the above example, if one were to run a pkg.installed state for a package named foo, then pkg.list_pkgs would show a package version of simply 1 for package foo, denoting that it is a virtual package.

However, while this makes certain aspects of package management convenient, there are issues with this approach that make relying on "virtual packages" problematic. For instance, Ubuntu has four different mutually-conflicting packages for nginx:

• nginx-core

• nginx-full

• nginx-light

• nginx-extras

All four of these provide nginx. Yet there is an nginx package as well, which has no actual content and merely has dependencies on any one of the above four packages. If one used nginx in a pkg.installed state, and none of the above four packages were installed, then the nginx metapackage would be installed, which would pull in nginx-core_. Later, if nginx were used in a pkg.removed state, the nginx metapackage would be removed, leaving nginx-core installed. The result would be that, since nginx-core_ provides nginx_, Salt would now see nginx as an installed virtual package, and the pkg.removed state would fail. Moreover, nginx would not actually have been removed, since nginx-core would remain installed.

Starting with this release, Salt will no longer support using "virtual package" names in pkg states, and package names will need to be specified using the proper package name. The pkg.list_repo_pkgs function can be used to find matching package names in the repositories, given a package name (or glob):

# salt myminion pkg.list_repo_pkgs 'nginx*'
myminion:
    ----------
    nginx:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-common:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-core:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-core-dbg:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-doc:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-extras:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-extras-dbg:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-full:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-full-dbg:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-light:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1
    nginx-light-dbg:
        - 1.10.3-0ubuntu0.16.04.2
        - 1.9.15-0ubuntu1

Alternatively, the newly-added pkg.show function can be used to get more detailed information about a given package and help determine what package name is correct:

# salt myminion pkg.show 'nginx*' filter=description,provides
myminion:
    ----------
    nginx:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                small, powerful, scalable web/proxy server
        1.9.15-0ubuntu1:
            ----------
            Description:
                small, powerful, scalable web/proxy server
    nginx-common:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                small, powerful, scalable web/proxy server - common files
        1.9.15-0ubuntu1:
            ----------
            Description:
                small, powerful, scalable web/proxy server - common files
    nginx-core:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (core version)
            Provides:
                httpd, httpd-cgi, nginx
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (core version)
            Provides:
                httpd, httpd-cgi, nginx
    nginx-core-dbg:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (core version) - debugging symbols
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (core version) - debugging symbols
    nginx-doc:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                small, powerful, scalable web/proxy server - documentation
        1.9.15-0ubuntu1:
            ----------
            Description:
                small, powerful, scalable web/proxy server - documentation
    nginx-extras:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (extended version)
            Provides:
                httpd, httpd-cgi, nginx
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (extended version)
            Provides:
                httpd, httpd-cgi, nginx
    nginx-extras-dbg:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (extended version) - debugging symbols
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (extended version) - debugging symbols
    nginx-full:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (standard version)
            Provides:
                httpd, httpd-cgi, nginx
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (standard version)
            Provides:
                httpd, httpd-cgi, nginx
    nginx-full-dbg:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (standard version) - debugging symbols
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (standard version) - debugging symbols
    nginx-light:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (basic version)
            Provides:
                httpd, httpd-cgi, nginx
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (basic version)
            Provides:
                httpd, httpd-cgi, nginx
    nginx-light-dbg:
        ----------
        1.10.3-0ubuntu0.16.04.2:
            ----------
            Description:
                nginx web/proxy server (basic version) - debugging symbols
        1.9.15-0ubuntu1:
            ----------
            Description:
                nginx web/proxy server (basic version) - debugging symbols

Minion Startup Events¶

When a minion starts up it sends a notification on the event bus with a tag that looks like this: salt/minion/<minion_id>/start. For historical reasons the minion also sends a similar event with an event tag like this: minion_start. This duplication can cause a lot of clutter on the event bus when there are many minions. Set enable_legacy_startup_events: False in the minion config to ensure only the salt/minion/<minion_id>/start events are sent.

The new enable_legacy_startup_events minion config option defaults to True, but will be set to default to False beginning with the 3001 release of Salt.

The Salt Syndic currently sends an old style syndic_start event as well. The syndic respects enable_legacy_startup_events as well.

Failhard changes¶

It is now possible to override a global failhard setting with a state-level failhard setting. This is most useful in case where global failhard is set to True and you want the execution not to stop for a specific state that could fail, by setting the state level failhard to False. This also allows for the use of onfail*-requisites, which would previously be ignored when a global failhard was set to True. This is a deviation from previous behavior, where the global failhard setting always resulted in an immediate stop whenever any state failed (regardless of whether the failing state had a failhard setting of its own, or whether any onfail*-requisites were used).

Pass Through Options to file.serialize State¶

This allows for more granular control over the way in which the dataset is serialized. See the documentation for the new serializer_opts and deserializer_opts options in the file.serialize state for more information.

file.patch State Rewritten¶

The file.patch state has been rewritten with several new features:

• Patch sources can now be remote files instead of only salt:// URLs

• Multi-file patches are now supported

• Patch files can be templated

In addition, it is no longer necessary to specify what the hash of the patched file should be.

New no_proxy Minion Configuration¶

Pass a list of hosts using the no_proxy minion config option to bypass an HTTP proxy.

no_proxy: [ '127.0.0.1', 'foo.tld' ]

Changes to slack Engine¶

The output returned to Slack from functions run using this engine is now formatted using that function's proper outputter. Earlier releases would format the output in YAML for all functions except for when states were run.

Enhancements to wtmp Beacon¶

A new key, action, has been added to the events fired by this beacon, which will contain either the string login or logout. This will simplify reactors which use this beacon's data, as it will no longer be necessary to check the integer value of the type key to know whether the event is a login or logout.

Additionally, in the event that your platform has a non-standard utmp.h, you can now configure which type numbers indicate a login and logout.

See the wtmp beacon documentation for more information.

Deprecated and Removed Options¶

>>> import salt.client
>>> local = salt.client.LocalClient()
>>> local.cmd("*", "cmd.run", ["whoami"], tgt_type="glob")
{'jerry': 'root'}

SaltSSH Major Updates¶

SaltSSH now works across different major Python versions. Python 2.7 ~ Python 3.x are now supported transparently. Requirement is, however, that the SaltMaster should have installed Salt, including all related dependencies for Python 2 and Python 3. Everything needs to be importable from the respective Python environment.

SaltSSH can bundle up an arbitrary version of Salt. If there would be an old box for example, running an outdated and unsupported Python 2.6, it is still possible from a SaltMaster with Python 3.5 or newer to access it. This feature requires an additional configuration in /etc/salt/master as follows:

ssh_ext_alternatives:
    2016.3:                     # Namespace, can be actually anything.
        py-version: [2, 6]      # Constraint to specific interpreter version
        path: /opt/2016.3/salt  # Main Salt installation
        dependencies:           # List of dependencies and their installation paths
          jinja2: /opt/jinja2
          yaml: /opt/yaml
          tornado: /opt/tornado
          msgpack: /opt/msgpack
          certifi: /opt/certifi
          singledispatch: /opt/singledispatch.py
          singledispatch_helpers: /opt/singledispatch_helpers.py
          markupsafe: /opt/markupsafe
          backports_abc: /opt/backports_abc.py

It is also possible to use several alternative versions of Salt. You can for instance generate a minimal tarball using runners and include that. But this is only possible, when such specific Salt version is also available on the Master machine, although does not need to be directly installed together with the older Python interpreter.

SaltSSH now support private key's passphrase. You can configure it by:

• --priv-passwd for salt-ssh cli

• salt_priv_passwd for salt master configure file

• priv_passwd for salt roster file

State Module Changes¶

influxdb_user.present:
  - name: exampleuser
  - password: exampleuserpassword
  - user: admin
  - password: adminpassword

influxdb_user.present:
  - name: exampleuser
  - passwd: exampleuserpassword
  - user: admin
  - password: adminpassword

LDAP External Authentication¶

Jinja Include Relative Paths¶

When a jinja include template name begins with ./ or ../ then the import will be relative to the importing file.

Prior practices required the following construct:

{% from tpldir ~ '/foo' import bar %}

A more "natural" construct is now supported:

{% from './foo' import bar %}

Comparatively when importing from a parent directory - prior practice:

{% from tpldir ~ '/../foo' import bar %}

New style for including from a parent directory:

{% from '../foo' import bar %}

salt-api¶

Logging Changes¶

log_fmt_console: "[%(levelname)-8s] %(jid)s %(message)s"

log_fmt_jid: "[JID: %(jid)s]"

Security¶

New Modules¶