Describe postgres.server.image state in README

Author: vutny

README.rst

@@ -16,8 +16,8 @@ Available states
 ``postgres``
 ------------
 
-Installs and configures both PostgreSQL server and client with creation of
-various DB objects in the cluster.
+Installs and configures both PostgreSQL server and client with creation of various DB objects in
+the cluster.
 
 ``postgres.client``
 -------------------
@@ -27,8 +27,8 @@ Installs the PostgreSQL client binaries and libraries.
 ``postgres.manage``
 -------------------
 
-Creates such DB objects as: users, tablespaces, databases, schemas and
-extensions. See ``pillar.example`` file for details.
+Creates such DB objects as: users, tablespaces, databases, schemas and extensions.
+See ``pillar.example`` file for details.
 
 ``postgres.python``
 -------------------
@@ -38,22 +38,48 @@ Installs the PostgreSQL adapter for Python.
 ``postgres.server``
 -------------------
 
-Installs the PostgreSQL server package and prepares the DB cluster.
+Installs the PostgreSQL server package, prepares the DB cluster and starts the server using
+packaged init script, job or unit.
+
+``postgres.server.image``
+-------------------------
+
+Installs the PostgreSQL server package, prepares the DB cluster and starts the server by issuing
+raw ``pg_ctl`` command. The ``postgres:bake_image`` Pillar toggles this behaviour. For example:
+
+.. code:: yaml
+
+  postgres:
+    bake_image: True
+
+If set ``True``, then it becomes possible to fully provision PostgreSQL with all supported entities
+from ``postgres.manage`` state during the build ("baking") of AMI / VM / Container images (using
+Packer, Docker or similar tools), i.e. when OS ``init`` process is not available to start the
+service and enable it on "boot" of resulting appliance.
+
+Also it allows to make Docker images with PostgreSQL using functionality being available since Salt
+2016.11.0 release:
+
+.. code:: console
+
+  salt 'minion.with.docker' dockerng.sls_build my-postgres base=centos/systemd mods=postgres
+
+If a lookup dictionary or Pillar has ``postgres:bake_image`` set ``False`` (this is default), it is
+equivalent of applying ``postgres.server`` state.
 
 ``postgres.upstream``
 ---------------------
 
 Configures the PostgreSQL Official (upstream) repository on target system if
 applicable.
 
-The state relies on the ``postgres:use_upstream_repo`` Pillar value which could
-be set as following:
+The state relies on the ``postgres:use_upstream_repo`` Pillar value which could be set as following:
 
 * ``True`` (default): adds the upstream repository to install packages from
 * ``False``: makes sure that the repository configuration is absent
 
-The ``postgres:version`` Pillar controls which version of the PostgreSQL
-packages should be installed from the upstream repository. Defaults to ``9.5``.
+The ``postgres:version`` Pillar controls which version of the PostgreSQL packages should be
+installed from the upstream repository. Defaults to ``9.5``.
 
 Testing
 =======
@@ -79,3 +105,5 @@ Builds and runs tests from scratch.
 -----------------
 
 Gives you ssh to the vagrant machine for manual testing.
+
+.. vim: fenc=utf-8 spell spl=en cc=100 tw=99 fo=want sts=2 sw=2 et

pillar.example

@@ -52,8 +52,8 @@ postgres:
 
   # If Salt is unable to detect init system running in the scope of state run,
   # probably we are trying to bake a container/VM image with PostgreSQL.
-  # Use ``service`` setting to contol how PostgreSQL will be started: if set to
-  # ``True`` the raw ``pg_ctl`` will be utilized instead of packaged init
+  # Use ``bake_image`` setting to contol how PostgreSQL will be started: if set
+  # to ``True`` the raw ``pg_ctl`` will be utilized instead of packaged init
   # script, job or unit run with Salt ``service`` state.
   bake_image: True
 

postgres/server/image.sls

@@ -1,7 +1,7 @@
 {%- from "postgres/map.jinja" import postgres with context -%}
 
-# This state is used to launch PostgreSQL and enable it on "boot" with `pg_ctl`
-# during an image (Docker, Virtual Appliance, AMI) preparation
+# This state is used to launch PostgreSQL with ``pg_ctl`` command and enable it
+# on "boot" during an image (Docker, Virtual Appliance, AMI) preparation
 
 {%- if postgres.bake_image %}
 
@@ -40,6 +40,6 @@ postgresql-enable:
 
 postgresql-start:
   test.show_notification:
-    - text: The 'postgres.bake_image' Pillar is disabled (set to 'False').
+    - text: The 'postgres:bake_image' Pillar is disabled (set to 'False').
 
 {%- endif %}