Merge pull request #4 from jnunyez/update-docs

updates on UserGuide

docs/reference-config-guide.md

@@ -33,6 +33,41 @@ the required CRs in the group are included then no report of "missing content" f
 In this version Parts only help with organization of the components into groups and don't have any affection on the diff
 process.
 
+Thus, the file `metadata.yaml` includes an array denoted by `Parts` of one or more objects. Each object includes:
+
+- a key "name" with a value of a string typically identifying a workload or a set of workloads
+- a key "Components" defined as an array of objects
+
+```yaml
+# Every part denotes typically denotes a workload or set of workloads
+ Parts:
+  - name: ExamplePart1 
+    Components:
+      - name: ExampleComponent1
+        ---- here goes ExampleComponent1 configuration ----
+  - name: ExamplePart2
+    ---- here goes Part2 configuration ----
+```
+
+"Components" array includes:
+
+- a pair at key "name" with a value of a string identifying a component required for the part
+- a pair at key "type" with a value of:
+  - `Optional` for optional components; or
+  - `Required` for mandatory components
+- the key "requiredTemplates" defined by:
+  - an array of at least one template `YAML` files. Each template `YAML` file has one Reference Configuration CR.
+
+```yaml
+# requiredTemplates contains all needed reference CRs to comply with ExampleComponent1
+Components:
+  - name: ExampleComponent1
+    type: Optional
+    requiredTemplates:
+      - RequiredTemplate1.yaml
+      - RequiredTemplate2.yaml
+```
+
 ### Example Reference Configuration CR
 
 User variable content is handled by golang formatted templating within the reference configuration

docs/user-guide.md

@@ -10,6 +10,19 @@ support engineers, and others can validate a cluster’s configuration against a
 
 # Concepts
 
+## Reference Configuration
+
+The target of `kubectl cluster compare` tool is to detect deviations from a live or local set of CRs with respect to a Reference Configuration specified by a set of recommended Custom Resources (CRs).
+
+But first, what do we understand by Reference Configuration? The Reference Configuration consists of a set of CRs and an entry-point which defines the expected mandatory and optional components. This entrypoint is a YAML file called `metadata.yaml`.
+
+- A Reference Configuration is typically versioned to account for necessary differences in the configuration based on the specific cluster version.
+- The top level (entry point) of the reference configuration is the metadata descriptor YAML file (`metadata.yaml`). This file defines the Reference Configuration.
+- A published `metadata.yaml` identifies the set of compliant Reference Configuration CR objects for the covered use case. Any differences in cluster configuration found when running the `kubectl cluster compare` tool shall be identified as a deviation from the expected Reference Configuration.  
+
+For guidance on the Reference Configuration defined by `metadata.yaml` see
+[this guide](./ReferenceConfigGuide.md).
+
 ## Optional vs required
 
 ## CR selection (correlation)
@@ -65,7 +78,7 @@ largest number of fields from this group:  apiVersion, kind, namespace, name.
 
 ## How it works
 
-* eg how templates pull content into reference prior to compare
+- eg how templates pull content into reference prior to compare
 
 ## Limits
 
@@ -85,6 +98,18 @@ hardware, os configuratoin, etc (unless available through the api) out of scope.
 
 # Understanding the output
 
+## States of a Reference Configuration CR after running the tool
+
+After running `kubectl cluster-compare` tool, the reference configuration CRs will be identified in one of the following states: missing and present in the live cluster.
+
+1. Missing CR. A `missing` reference CR can be in the following state:
+    1. Required: Reference CR is required and does not appear in the target cluster CRs. Note that a missed reference CRs declared as optional is not going to be reported as missed.
+
+2. Present CR. A `present` reference CR can be in one of the following states:
+    1. Matched once: The reference CR has one correlated instance in the live cluster.
+    2. Matched more than once: The reference CR has more than one correlated instance in the live cluster. There are additional reference CRs in the live cluster with equivalent apiVersion-kind-namespace-name.
+    3. Present and unmatched: The reference configuration CR is present, which means that there is a match for api-kind-name-namespace, in the target cluster but does not follow some configuration value specific to the live cluster. This should be identified as a deviation.
+
 # Options and advanced usage
 
 # Troubleshooting