docs(operatorgroups): add more extensive docs

Author: njhale

Documentation/design/architecture.md

@@ -10,7 +10,7 @@ Each of these Operators are responsible for managing the CRDs that are the basis
 | InstallPlan           | ip         | Catalog | calculated list of resources to be created in order to automatically install/upgrade a CSV |
 | CatalogSource         | catsrc         | Catalog | a repository of CSVs, CRDs, and packages that define an application                        |
 | Subscription          | sub        | Catalog | used to keep CSVs up to date by tracking a channel in a package                            |
-| OperatorGroup         | og     | OLM     | method to group multiple namespaces and prepare for use by an operator                     |
+| OperatorGroup         | og     | OLM     | used to group multiple namespaces and prepare for use by an operator                     |
 
 Each of these Operators are also responsible for creating resources:
 
@@ -21,7 +21,7 @@ Each of these Operators are also responsible for creating resources:
 | OLM      | (Cluster)Roles             |
 | OLM      | (Cluster)RoleBindings      |
 | Catalog  | Custom Resource Definition |
-| Catalog  | ClusterServiceVersion   |
+| Catalog  | ClusterServiceVersion      |
 
 ## What is a ClusterServiceVersion
 
@@ -78,6 +78,7 @@ Replacing --> Deleting
 | Failed     | upon failed execution of the Install Strategy, or an installed component dissapears the CSV transitions to this phase; if the component can be recreated by OLM, this may transition to `Pending`                                     |
 | Replacing  | a newer CSV that replaces this one has been discovered in the cluster. This status means the CSV is marked for GC                                                                                                                     |
 | Deleting   | the GC loop has determined this CSV is safe to delete from the cluster. It will disappear soon.                                                                                                                                       |
+> Note: In order to transition, a CSV must first be an active member of an OperatorGroup
 
 ## Catalog Operator
 
@@ -134,17 +135,3 @@ Package {name}
   |
   +-- Channel {name} --> CSV {version}
 ```
-
-## Operator Group design
-
-An operator group consists of a group of target namespaces as specified by the label selector in the spec, plus the namespace that the operator group is created within known as the operator namespace. The operator namespace is always considered to also be a target namespace, without regard to matching the label selector. The operator namespace is where the operator actually runs and the target namespace(s) are namespaces the operator have permissions to operate in.
-
-Once an operator group has been created, the focus is around the target namespaces and the resources contained in those namespaces. The status for an operator group is constantly updated to always list the namespaces matching the label selector as specified in the spec. In addition to maintaining an updated status, the operator group control loop also maintains creating RBAC rules and providing operator group knowledge to operators. Some operations such as copying CSVs and creating additional RBAC rules are handled by the CSV control loop. Details for these operations are described further below.
-
-RBAC rules are created for two reasons. The first reason is for restricting access to the API (CRDs) of the installed operators. It is possible that the administrator does not want the full functionality of the operator to be granted in all cases. The second reason is to give the operator the necessary permissions to operate, which is tied to the specified operator group service account.
-
-Operator group target namespace information is made available to operators via annotations on the deployment. A second step of using downward API is technically necessary to pass this information, which is used to know where the operator has permissions to operate.
-
-Each CSV in the operator namespace is copied into the target namespace(s), which is done in case a user does not have access to the operator namespace. The copied CSV is annotated with the operator group name and the operator namespace (the target namespace list is intentionally not included for security reasons).
-
-In summary, the goal of the above functionality is to assist in bringing multitenancy features to running operators in a cluster in the easiest most automated way. For creating your own operator group resource, refer to the operator group custom resource definition file in the templates directory.

Documentation/design/building-your-csv.md

@@ -239,10 +239,10 @@ The metadata section contains general metadata around the name, version and othe
 **Selectors** (optional): A label selector to identify related resources. Set this to select on current labels applied to this CSV object (if applicable).
 
 **InstallModes**: A set of `InstallMode`s that tell OLM which `OperatorGroup`s an Operator can belong to. Belonging to an `OperatorGroup` means that OLM provides the set of targetted namespaces as an annotation on the Operator's CSV and any deployments defined therin. These deployments can then untilize [the Downward API](https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#the-downward-api) to inject the list of namespaces into its container(s). An `InstallMode` consists of an `InstallModeType` field and a boolean `Supported` field. There are four `InstallModeTypes`: 
-* `OwnNamespace`: If supported, the set of namespaces targetted by an `OperatorGroup` must contain the namespace the Operator is to be installed in.
-* `SingleNamespace`: If supported, the set of namespaces targetted by an `OperatorGroup` can be of length 1.
-* `MultiNamespace`: If supported, the set of namespaces targetted by an `OperatorGroup` can be of length >= 1. Any Operator supporting `MultiNamespace` implicitly supports `SingleNamespace` as well.
-* `AllNamespaces`: If supported, the Operator can support an `OperatorGroup` that selects all namespaces with a targetted set = [""]. Any Operator supporting `AllNamespaces` implicity supports `OwnNamespace` as well. 
+* `OwnNamespace`: If supported, the operator can be a member of an `OperatorGroup` that selects its own namespace
+* `SingleNamespace`: If supported, the operator can be a member of an `OperatorGroup` that selects one namespace
+* `MultiNamespace`: If supported, the operator can be a member of an `OperatorGroup` that selects more than one namespace
+* `AllNamespaces`: If supported, the operator can be a member of an `OperatorGroup` that selects all namespaces (target namespace set is the empty string "")
 
 Here's an example: