From d76d4dc2f05ea3bc0e7386489804e7871351374d Mon Sep 17 00:00:00 2001
From: Svetlana Karslioglu <skarslioglu@mirantis.com>
Date: Fri, 25 Nov 2016 08:02:47 -0800
Subject: [PATCH] [UG][IaC] Added section about audit and enforce

Added a section about changes audit and enforcing changes
to an environment.

Change-Id: I122c05796f13e61185c7aa164e20ff6f48e51d3a
---
 .../post-deployment-conf/lcm-git-repo.rst     |  2 +
 .../lcm-git-repo/audit-enforce-changes.rst    | 40 +++++++++++
 .../lcm-git-repo/filter-results.rst           | 71 +++++++++++++++++++
 3 files changed, 113 insertions(+)
 create mode 100644 userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/audit-enforce-changes.rst
 create mode 100644 userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/filter-results.rst

diff --git a/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo.rst b/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo.rst
index abf566ad9..0a246269a 100644
--- a/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo.rst
+++ b/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo.rst
@@ -32,6 +32,8 @@ This section includes the following topics:
    lcm-git-repo/configure-iac.rst
    lcm-git-repo/repo-structure.rst
    lcm-git-repo/set-up-git-repo.rst
+   lcm-git-repo/audit-enforce-changes.rst
+   lcm-git-repo/filter-results.rst
 
 .. seealso::
 
diff --git a/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/audit-enforce-changes.rst b/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/audit-enforce-changes.rst
new file mode 100644
index 000000000..089330756
--- /dev/null
+++ b/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/audit-enforce-changes.rst
@@ -0,0 +1,40 @@
+.. _audit-enforce-changes:
+
+Verify and enforce the changes
+==============================
+
+You can check whether a file has been modified or not using
+the ``fuel2 audit`` command and then enforce application of
+the changed configuration if needed.
+
+Similarly to running a Fuel deployment workflows with the ``noop`` flag,
+the ``fuel2 audit`` command performs a dry-run of the applied
+changes and records Puppet resources that will be modified after
+applying the changes.
+
+**To verify and enforce the changes:**
+
+#. Verify the changes by performing a dry-run of the applied changes:
+
+   ::
+
+     fuel2 audit noop --env <ENV_ID> || --repo <REPO_ID>
+
+#. List the changes to Puppet resources:
+
+   ::
+
+     fuel2 audit list outofsync --task <NOOP_TASK_ID> || --repo <REPO_ID>
+
+#. Redeploy (enforce) the environment with the new changes:
+
+   ::
+
+     fuel2 env redeploy <ENV_ID>
+
+#. Alternatively, you can perform a dry-run and redeployment
+   in one go:
+
+   ::
+
+     fuel2 audit enforce --env <ENV_ID> || --repo <REPO_ID>
diff --git a/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/filter-results.rst b/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/filter-results.rst
new file mode 100644
index 000000000..61481a36c
--- /dev/null
+++ b/userdocs/fuel-user-guide/post-deployment-conf/lcm-git-repo/filter-results.rst
@@ -0,0 +1,71 @@
+.. _filter-results:
+
+Exclude tasks from an audit
+===========================
+
+When you verify changes with the ``fuel2 audit`` command, Fuel checks
+all Puppet tasks disregarding whether they do not change their states
+(idempotent) or they do change their states (non-idempotent). Each audit
+report includes both types of tasks. However, the result of the
+non-idempotent task run typically does not provide important information
+about the state of the system, and, therefore, can be ignored.
+
+You can exclude the non-idempotent Puppet tasks from the audit by creating a
+whitelist.
+A whitelist includes a set of rules in a form of a pair of strings. The first
+string is a Fuel Puppet task. The second string is the rule.
+
+**Example:**
+
+::
+
+  - fuel_task: netconfig
+    rule: L23_stored_configs
+  - fuel_task: top-role-compute
+    rule: Service[nova-compute]/ensure
+
+To apply a rule to all tasks, specify an empty task.
+
+Fuel provides a default whitelist for your reference.
+
+**To exclude tasks from an audit:**
+
+#. Log in to the Fuel Master node.
+
+#. Create a new whitelist or upload the existing one.
+
+   * If you want upload the default whitelist:
+
+     ::
+
+       fuel2 audit whitelist load fromfile <ENV_ID>
+       /usr/lib/python2.7/site-packages/fuel_external_git/default_whitelist.yaml
+
+   * If you need to create a new whitelist:
+
+     #. In the ``/usr/lib/python2.7/site-packages/fuel_external_git/``
+        directory, create a ``.yaml`` file with the required rules.
+
+     #. Alternatively, specify rules using the following command:
+
+        ::
+
+         fuel2 audit whitelist add <ENV_ID> --task <FUEL_TASK> --rule <RULE>
+
+        or by providing a path to the corresponding ``.yaml`` file:
+
+        ::
+
+         fuel2 audit whitelist load fromfile <ENV_ID> <PATH_TO_YAML>
+
+#. Verify that you created a whitelist for the selected environment:
+
+   ::
+
+     fuel2 audit whitelist show <ENV_ID>
+
+#. If you need to delete a rule, run:
+
+   ::
+
+     fuel2 audit whitelist delete <RULE_ID>