Add section on indexing facts to the octofacts-updater document

Author: kpaulisse

doc/octofacts-updater.md

@@ -99,6 +99,40 @@ Note that `facter` may need to run as root to gather all of the facts for the sy
 
 Also, if you are using Puppet 4 or later, but are relying on "legacy" facts that were used in Puppet 3, you may need to add `--show-legacy` to the `facter` command line.
 
+## Indexing facts
+
+`octofacts` supports an index of facts, allowing you to select fixtures dynamically based on parameters, rather than by specifying the name of a specific file in your tests. When properly set up, the use of an index in rspec-puppet tests will look like this example:
+
+```
+let(:facts) { Octofacts.from_index(app: "my_app", role: "my_role") }
+```
+
+To set up the index, you need to configure three settings:
+
+- `file`: The absolute or relative path to the index file.
+- `node_path`: The absolute or relative path to the directory where fixtures for nodes are stored.
+- `indexed_facts`: An array of facts that you want to index. For the example above, you would need to index the `app` and `role` facts.
+
+In your configuration, this might look like:
+
+```title=octofacts-updater.yaml
+index:
+  file: ../spec/fixtures/facts/octofacts-index.yaml
+  node_path: ../spec/fixtures/facts/octofacts
+  indexed_facts:
+    - app
+    - role
+```
+
+Once you have configured the index, you can use `octofacts-updater` to build the index from the node fixtures you already have.
+
+```
+touch spec/fixtures/facts/octofacts-index.yaml
+octofacts-updater --config octofacts-updater.yaml --action reindex
+```
+
+:information_source: If a file or directory path starts with `.` or `..`, the path is treated as relative to the configuration file itself. This allows you to specify locations within a Puppet code repository, without regard to where on the system `octofacts-updater` is actually installed. Of course, you can also use absolute paths (starting with `/`).
+
 ## Anonymizing and rewriting facts
 
 To avoid committing sensitive information into source control, and to prevent rspec-puppet tests from inadvertently contacting actual systems, `octofacts-updater` supports anonymizing and rewriting facts. For example, you might remove or scramble SSH keys, delete or hard-code facts like system uptime that change upon each run, or change IP addresses.