"Doc for inclusive configuration of resources to propagate"

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

@@ -322,28 +322,46 @@ for policy purposes.*
 
 ### Exceptions and propagation control
 
-By default, HNC 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:
+You can choose whether HNC propagates _all_ objects of a [specified type](how-to.md#admin-resources)
+from ancestor namespaces to descendant namespaces by using the `Propagate`
+[synchronization mode](how-to.md#modify-the-resources-propagated-by-hnc), or if HNC only
+propagates objects of a specified type when selectors are used, using the `AllowPropagate`
+synchronization mode.
+
+When `Propagate` [synchronization mode](how-to.md#modify-the-resources-propagated-by-hnc) is
+configured for a [specified type](how-to.md#admin-resources), HNC propagates _all_ objects of this type
+from ancestor namespaces to descendant namespaces. When `AllowPropagate` synchronization mode
+is configured for a specified type, HNC does not propagates _any_ objects of this type
+from ancestor namespaces to descendant namespaces. ***Exceptions*** are used to create
+certain policies to modify the behavior of the propagation. For example:
 
 * A ResourceQuota was propagated to many children, but one child namespace now
 has higher requirements than the rest. Rather than getting rid of the quota in
 the parent namespace, or raising the limit for everyone, you can stop the
 quota in the parent from being propagated to that _one_ child namespace,
-allowing you to replace it with another, more suitable quota.
+allowing you to replace it with another, more suitable quota. This is true 
+when `Propagate` synchronization is set for the type.
 
 * A RoleBinding allows any user to create subnamespaces under one namespace, but
 we don’t want to allow those users to create additional levels of hierarchy
 underneath those subnamespaces. So you can stop the role binding from being
-propagated to _any_ child namespace.
+propagated to _any_ child namespace. This is true when `Propagate` 
+synchronization is set for the type.
+
+* A Secret exists on a namespace but we don't want this secret to get propagated
+to all subnamespaces by default but only to one. So you can choose to propagate 
+to that _one_ child namespace. This is true when `AllowPropagate` 
+synchronization is set for the type.
+
 
 Exceptions are defined using [annotations on the objects
 themselves](how-to.md#use-limit-propagation).  As a result, anyone who can edit
 an object can also control how it is propagated to descendant namespaces.
 
 If you modify an exception - for example, by removing it - this could cause
 the object to be propagated to descendants from which it had previously been
-excluded. This could cause you to accidentally overwrite objects that were
+excluded, or be deleted from descendants to which it had previously been
+propagated. This could cause you to accidentally overwrite objects that were
 intended to be exceptions from higher-level policies, like the ResourceQuota
 in the example above. To prevent this, if modifying an exception would cause
 HNC to overwrite another object, HNC’s admission controllers will prevent you

docs/user-guide/how-to.md

@@ -366,7 +366,15 @@ 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. The behavior would be the same as setting
+  [synchronization mode](#modify-the-resources-propagated-by-hnc) to 
+  `AllowPropagate` with no selectors at all.
+
+* **`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. The behavior would be the same as setting
+  [synchronization mode](#modify-the-resources-propagated-by-hnc) to 
+  `Propagate` with no selectors at all.
 
 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
@@ -388,6 +396,12 @@ To set `my-secret` not to propagate to any namespace, you can use:
 kubectl annotate secret my-secret -n parent propagate.hnc.x-k8s.io/none=true
 ```
 
+To set `my-secret` to propagate to any namespace, 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 +691,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:** inclusive propagation - only propagates objects from ancestors 
+  to descendants and deletes obsolete descendants when
+  [selectors](#limit-the-propagation-of-an-object-to-descendant-namespaces) are 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 +718,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 +755,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 `AlowPropagate`.  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