Doc for opt-in propagation mode

Addresses issue kubernetes-retired#221, documentation is added on the `AllowPropagate` sync mode and on the `all` selector.

Signed-off-by: mzeevi <[email protected]>

Author: mzeevi

docs/user-guide/concepts.md

@@ -319,10 +319,10 @@ application.
 for policy purposes.*
 
 <a name="basic-exceptions"/>
-
+ 
 ### Exceptions and propagation control
 
-By default, HNC propagates _all_ objects of a [specified type](how-to.md#admin-resources)
+HNC typically propagates _all_ objects of a [specified type](how-to.md#admin-resources)
 from ancestor namespaces to descendant namespaces. However, sometimes this is
 too restrictive, and you need to create ***exceptions*** to certain policies. For example:
 
@@ -352,6 +352,20 @@ overwritten by your actions. You can then rewrite the exception to safely
 exclude those objects, or else delete the conflicting objects to allow them to
 be replaced.
 
+#### (Beta in v1.1) Opt-in propagation
+The `Propagate` mode propagates all objects unless directed to otherwise via a selector,
+using exceptions. By contrast, opt-in propagation, as set by the `AllowPropagate` 
+mode, doesn't propagate objects unless directed to by a selector. That is, for an object 
+with a selector, its behaviour will be identical in both the `Propagate` and `AllowPropagate` modes; 
+the only difference in behaviours is for objects without a selector.
+
+For example:
+ 
+* A Secret exists on a namespace but we don't want this secret to be propagated
+to all subnamespaces by default but instead only to one namespace of our choosing. 
+So you can choose to propagate to that _one_ child namespace using `AllowPropagate`
+and exceptions.
+
 #### Built-in exceptions
 
 There are some built-in exceptions to prevent certain known (auto-generated)

docs/user-guide/how-to.md

@@ -366,7 +366,17 @@ can use any of the following annotations:
 
 * **`propagate.hnc.x-k8s.io/none`**: Setting `none` to `true` (case insensitive)
   will result in the object not propagating to _any_ descendant namespace. Any
-  other value will be rejected.
+  other value will be rejected. This is only useful in `Propagate`
+  [synchronization mode](#modify-the-resources-propagated-by-hnc).
+
+* **`propagate.hnc.x-k8s.io/all`**: Setting `all` to `true` (case insensitive)
+  will result in the object propagating to _any_ descendant namespace. Any
+  other value will be rejected. This is only useful in `AllowPropagate`
+  [synchronization mode](#modify-the-resources-propagated-by-hnc).
+
+Warning: only use one of the propagation annotations on any one object at a time. 
+Interactions between multiple propagation annotations is undefined and may change 
+from release to release.
 
 For example, consider a case with a parent namespace with three child
 namespaces, and the parent namespace has a secret called `my-secret`. To set
@@ -382,12 +392,18 @@ kubectl annotate secret my-secret -n parent propagate.hnc.x-k8s.io/select=child1
 kubectl annotate secret my-secret -n parent propagate.hnc.x-k8s.io/select='!child2.tree.hnc.x-k8s.io/depth, !child3.tree.hnc.x-k8s.io/depth'
 ```
 
-To set `my-secret` not to propagate to any namespace, you can use:
+To set `my-secret` not to propagate to any namespace when the sync mode is `Propagate`, you can use:
 
 ```bash
 kubectl annotate secret my-secret -n parent propagate.hnc.x-k8s.io/none=true
 ```
 
+To set `my-secret` to propagate to any namespace when the sync mode is `AllowPropagate`, you can use:
+
+```bash
+kubectl annotate secret my-secret -n parent propagate.hnc.x-k8s.io/all=true
+```
+
 All these are equivalent to creating the object with the selector annotations:
 
 ```bash
@@ -677,6 +693,10 @@ The most important type of configuration is the way each object type
 
 * **Propagate:** propagates objects from ancestors to descendants and deletes
   obsolete descendants.
+* **AllowPropagate:** opt-in propagation - only propagates objects from ancestors 
+  to descendants and deletes obsolete descendants when at least one
+  [selector](#limit-the-propagation-of-an-object-to-descendant-namespaces) is set
+  on the object.
 * **Remove:** deletes all existing propagated copies, but does not touch source
   objects.
 * **Ignore:** stops modifying this resource. New or changed objects will not be
@@ -700,7 +720,7 @@ To configure an object resource using the kubectl plugin:
 
 ```
 # "--group" can be omitted if the resource is a core K8s resource
-kubectl hns config set-resource [resource] --group [group] --mode [Propagate|Remove|Ignore]
+kubectl-hns config set-resource RESOURCE [--group GROUP] [--force] --mode <Propagate|Remove|Ignore|AllowPropagate>
 ```
 
 For example:
@@ -737,20 +757,20 @@ spec:
       mode: Propagate     <<<
 ```
 
-Adding a new resource in the `Propagate` mode is potentially dangerous, since
-there could be existing objects of that resource type that would be overwritten
-by objects of the same name from ancestor namespaces. As a result, the HNS
-plugin will not allow you to add a new resource directly in the `Propagate`
-mode.  Instead, to do so safely:
+Adding a new resource in the `Propagate` mode or `AllowPropagate` mode is potentially 
+dangerous, since there could be existing objects of that resource type that 
+would be overwritten by objects of the same name from ancestor namespaces. 
+As a result, the HNS plugin will not allow you to add a new resource directly 
+in the `Propagate` mode or `AllowPropagate`.  Instead, to do so safely:
 
 * Add the new resource in the `Remove` mode. This will remove any propagated
   copies (of which there should be none) but will force HNC to start
   synchronizing all known source objects.
 * Wait until `kubectl hns config describe` looks like it's identified the
   correct number of objects of the newly added resource in its status.
-* Change the propagation mode from `Remove` to `Propagate`. HNC will then check
-  to see if any objects will be overwritten, and will not allow you to change
-  the propagation mode until all such conflicts are resolved.
+* Change the propagation mode from `Remove` to `Propagate` or `AllowPropagate`. 
+  HNC will then check to see if any objects will be overwritten, and will not 
+  allow you to change the propagation mode until all such conflicts are resolved.
 
 Alternatively, if you're certain you want to start propagating objects
 immediately, you can use the `--force` flag with `kubectl hns config