From 7c5f177c57b71e9abe7aadb45ab9342055304497 Mon Sep 17 00:00:00 2001
From: Bob Taylor <robertt@pobox.com>
Date: Thu, 1 Sep 2016 18:34:17 +0000
Subject: [PATCH] Add a doc example for yaml file overrides

Adds an example for yaml config file overrides and provides
clarification that the entire yaml file contents are overwritten
by any supplied override values, not just the added or changed values.

Change-Id: Ia64b6dceace4f33617736426c7818cfb6fc101e7
Partial-Bug: 1605758
---
 .../app-advanced-config-override.rst          | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/doc/source/install-guide/app-advanced-config-override.rst b/doc/source/install-guide/app-advanced-config-override.rst
index dc45b6b001..4d778de0b1 100644
--- a/doc/source/install-guide/app-advanced-config-override.rst
+++ b/doc/source/install-guide/app-advanced-config-override.rst
@@ -116,6 +116,52 @@ To assist you in finding the appropriate variable name to use for
 overrides, the general format for the variable name is
 ``<service>_policy_overrides``.
 
+Overriding YAML files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can override ``.yml`` file values by supplying replacement YAML content.
+
+.. note::
+
+   All default YAML file content will be completely overwritten by
+   the provided overrides, so the entire YAML source (both the existing
+   content and your changes) must be provided.
+
+For example, you can define a meter exclusion for all hardware items
+in the default content of ceilometer's ``pipeline.yml``:
+
+.. code-block:: yaml
+
+    sources:
+        - name: meter_source
+        interval: 600
+        meters:
+            - "!hardware.*"
+        sinks:
+            - meter_sink
+        - name: foo_source
+        value: foo
+
+You can accomplish this through the use of the following configuration
+entry in ``/etc/openstack_deploy/user_variables.yml``:
+
+.. code-block:: yaml
+
+    ceilometer_pipeline_yaml_overrides:
+      sources:
+          - name: meter_source
+          interval: 600
+          meters:
+              - "!hardware.*"
+          sinks:
+              - meter_sink
+          - name: source_foo
+          value: foo
+
+To assist you in finding the appropriate variable name to use for
+overrides, the general format for the variable name is
+``<service>_<filename>_<file extension>_overrides``.
+
 Currently available overrides
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~