Add capability to specify state args as a dict

changelog/68367.added.md

@@ -0,0 +1 @@
+Added capability to specify module arguments in an sls as a dict

doc/cheatsheet/salt.tex

@@ -48,7 +48,7 @@
     - running
     - enable: True
 /var/www/index.html: # ID declaration
-  file:              # state declaration
+  file:              # state module declaration
     - managed        # function
     - source: salt://webserver/index.html
     - user: root

doc/glossary.rst

@@ -223,6 +223,11 @@ Glossary
         set of host machines. Often used to create and deploy private clouds.
         *See also*: :py:mod:`virt runner <salt.runners.virt>`.
 
+    SLS
+        Structured Layered State. The SLS is a representation of the state in
+        which a system should be in, and is set up to contain this data in a
+        simple format. This is often called configuration management.
+
     SLS Module
         Contains a set of :term:`state declarations <State Declaration>`.
 

doc/ref/states/extend.rst

@@ -1,3 +1,5 @@
+.. _extending-external-sls-data:
+
 ===========================
 Extending External SLS Data
 ===========================
@@ -9,10 +11,53 @@ overwritten or when a service needs to watch an additional state.
 The Extend Declaration
 ----------------------
 
-The standard way to extend is via the extend declaration. The extend
-declaration is a top level declaration like ``include`` and encapsulates ID
-declaration data included from other SLS files. A standard extend looks like
-this:
+A standard way to extend is via the extend declaration. The extend
+declaration is a top level declaration like ``include`` that allows
+overriding or augmenting state declarations from other SLS files.
+Use ``extend`` to override arguments, append requisites,
+or otherwise modify an existing ID without editing the original SLS.
+
+Overview
+--------
+
+- ``extend`` is a top-level mapping at the same syntactic level as ``include`` or a top-level ID.
+- The SLS module that defines the target ID must be included so the ID exists before the
+  extend merge is applied.
+- Requisite lists (for example ``watch`` and ``require``) are appended; most other keys
+  are replaced by the extend entry.
+- Only one top-level ``extend`` mapping may appear in a single SLS file; later mappings
+  will overwrite earlier ones.
+
+Example
+-------
+
+The following shows the original SLS entries (the files being extended) and an extending SLS
+that includes them and declares a single ``extend`` block.
+
+Original: ``salt://http/init.sls``
+
+.. code-block:: yaml
+
+    apache:
+      pkg.installed: []
+      file:
+        - name: /etc/httpd/conf/httpd.conf
+        - source: salt://http/httpd.conf
+      service.running:
+        - name: httpd
+        - watch:
+          - file: apache
+
+Original: ``salt://ssh/init.sls``
+
+.. code-block:: yaml
+
+    ssh-server:
+      pkg.installed: []
+      service.running:
+        - name: sshd
+
+Extending SLS: ``salt://profile/webserver_extend.sls``
 
 .. code-block:: yaml
 
@@ -25,6 +70,7 @@ this:
         file:
           - name: /etc/httpd/conf/httpd.conf
           - source: salt://http/httpd2.conf
+
       ssh-server:
         service:
           - watch:
@@ -34,11 +80,40 @@ this:
       file.managed:
         - source: salt://ssh/banner
 
-A few critical things happened here, first off the SLS files that are going to
-be extended are included, then the extend dec is defined. Under the extend dec
-2 IDs are extended, the apache ID's file state is overwritten with a new name
-and source. Then the ssh server is extended to watch the banner file in
-addition to anything it is already watching.
+Behavior for this example
+-------------------------
+
+- The ``apache:file`` mapping in the extending SLS overrides with the
+  ``name`` and ``source`` values from the original ``file`` mapping
+  in ``http/init.sls`` with the values supplied under ``extend``.
+- The ``ssh-server:service:watch`` list is appended with ``file: /etc/ssh/banner``; any
+  existing watch entries declared in ``ssh/init.sls`` are preserved.
+- The banner resource is declared locally (``/etc/ssh/banner``) so the appended watch has
+  a concrete state to observe; if the resource were absent from the compiled data the
+  relationship would be invalid.
+
+Minimal patterns
+----------------
+
+Replace a mapping (overwrite):
+
+.. code-block:: yaml
+
+    extend:
+      apache:
+        file:
+          - name: /etc/httpd/conf/httpd.conf
+          - source: salt://http/httpd2.conf
+
+Append to a requisite list (merge):
+
+.. code-block:: yaml
+
+    extend:
+      ssh-server:
+        service:
+          - watch:
+            - file: /etc/ssh/banner
 
 Extend is a Top Level Declaration
 ---------------------------------
@@ -85,6 +160,9 @@ cleanly defined like so:
         - watch_in:
           - service: ssh-server
 
+:ref:`State Requisites <requisites>`
+
+
 Rules to Extend By
 ------------------
 There are a few rules to remember when extending states: