improve PostgresTeam docs

docs/user.md

@@ -275,9 +275,18 @@ Postgres clusters are associated with one team by providing the `teamID` in
 the manifest. Additional superuser teams can be configured as mentioned in
 the previous paragraph. However, this is a global setting. To assign
 additional teams, superuser teams and single users to clusters of a given
-team, use the [PostgresTeam CRD](../manifests/postgresteam.yaml). It provides
+team, use the [PostgresTeam CRD](../manifests/postgresteam.yaml).
-a simple mapping structure.
 
+Note, by default the `PostgresTeam` support is disabled in the configuration.
+Switch `enable_postgres_team_crd` flag to `true` and the operator will start to
+watch for this CRD. Make sure, the cluster role is up to date and contains a
+section for [PostgresTeam](../manifests/operator-service-account-rbac.yaml#L30).
+
+#### Additional teams
+
+To assign additional teams and single users to clusters of a given team,
+define a mapping with the `PostgresTeam` Kubernetes resource. The Postgres
+Operator will read such team mappings each time it syncs all Postgres clusters.
 
 ```yaml
 apiVersion: "acid.zalan.do/v1"
@@ -285,55 +294,118 @@ kind: PostgresTeam
 metadata:
   name: custom-team-membership
 spec:
-  additionalSuperuserTeams:
-    acid:
-    - "postgres_superusers"
   additionalTeams:
-    acid: []
+    a-team:
-  additionalMembers:
+    - "b-team"
-    acid:
-    - "elephant"
 ```
 
-One `PostgresTeam` resource could contain mappings of multiple teams but you
+With the example above the operator will create login roles for all members
-can choose to create separate CRDs, alternatively. On each CRD creation or
+of `b-team` in every cluster owned by `a-team`. It's possible to do vice versa
-update the operator will gather all mappings to create additional human users
+for clusters of `b-team` in one manifest:
-in databases the next time they are synced. Additional teams are resolved
-transitively, meaning you will also add users for their `additionalTeams`
-or (not and) `additionalSuperuserTeams`.
 
-For each additional team the Teams API would be queried. Additional members
+```yaml
-will be added either way. There can be "virtual teams" that do not exists in
+spec:
-your Teams API but users of associated teams as well as members will get
+  additionalTeams:
-created. With `PostgresTeams` it's also easy to cover team name changes. Just
+    a-team:
-add the mapping between old and new team name and the rest can stay the same.
+    - "b-team"
+    b-team:
+    - "a-team"
+```
+
+You see, the `PostgresTeam` CRD is a global team mapping and independent from
+the Postgres manifests. It is possible to define multiple mappings, even with
+redundant content - the Postgres operator will create one internal cache from
+it. Additional teams are resolved transitively, meaning you will also add
+users for their `additionalTeams`, e.g.:
+
+```yaml
+spec:
+  additionalTeams:
+    a-team:
+    - "b-team"
+    - "c-team"
+    b-team:
+    - "a-team"
+```
+
+This creates roles for members of the `c-team` team not only in all clusters
+owned by `a-team`, but as well in cluster owned by `b-team`, as `a-team` is
+an `additionalTeam` to `b-team` 
+
+Not, you can also define `additionalSuperuserTeams` in the `PostgresTeam`
+manifest. By default, this option is disabled and must be configured with
+`enable_postgres_team_crd_superusers` to make it work.
+
+#### Virtual teams
+
+There can be "virtual teams" that do not exist in the Teams API. It can make
+it easier to map a group of teams to many other teams:
+
+```yaml
+spec:
+  additionalTeams:
+    a-team:
+    - "virtual-team"
+    b-team:
+    - "virtual-team"
+    virtual-team:
+    - "c-team"
+    - "d-team"
+```
+
+This example would create roles for members of `c-team` and `d-team` plus
+additional `virtual-team` members in clusters owned by `a-team` or `b-team`.
+
+#### Teams changing their names
+
+With `PostgresTeams` it is also easy to cover team name changes. Just add
+the mapping between old and new team name and the rest can stay the same.
+E.g. if team `a-team`'s name would change to `f-team` in the teams API it
+could be reflected in a `PostgresTeam` mapping with just two lines:
+
+```yaml
+spec:
+  additionalTeams:
+    a-team:
+    - "f-team"
+```
+
+This is helpful, because Postgres cluster names are immutable and can not
+be changed. Only via cloning it could get a different name starting with the
+new `teamID`.
+
+#### Additional members
+
+Single members might be excluded from teams although they continue to work
+with the same people. However, the teams API would not reflect this anymore.
+To still add a database role for former team members list their role under
+the `additionalMembers` section of the `PostgresTeam` resource:
 
 ```yaml
 apiVersion: "acid.zalan.do/v1"
 kind: PostgresTeam
 metadata:
-  name: virtualteam-membership
+  name: custom-team-membership
 spec:
-  additionalSuperuserTeams:
-    acid:
-    - "virtual_superusers"
-    virtual_superusers:
-    - "real_teamA"
-    - "real_teamB"
-    real_teamA:
-    - "real_teamA_renamed"
-  additionalTeams:
-    real_teamA:
-    - "real_teamA_renamed"
   additionalMembers:
-    virtual_superusers:
+    a-team:
-    - "foo"
+    - "tia"
 ```
 
-Note, by default the `PostgresTeam` support is disabled in the configuration.
+This will create the login role `tia` in every cluster owned by `a-team`.
-Switch `enable_postgres_team_crd` flag to `true` and the operator will start to
+The user can connect to databases like the other team members.
-watch for this CRD. Make sure, the cluster role is up to date and contains a
+
-section for [PostgresTeam](../manifests/operator-service-account-rbac.yaml#L30).
+The `additionalMembers` map can also be used to define users of virtual
+teams, e.g. for `virtual-team` we used above:
+
+```yaml
+spec:
+  additionalMembers:
+    virtual-team:
+    - "flynch"
+    - "rdecker"
+    - "briggs"
+```
 
 ## Prepared databases with roles and default privileges