add more context in the docs about additional_owner_roles

docs/reference/operator_parameters.md

@@ -179,12 +179,17 @@ under the `users` key.
 
 * **additional_owner_roles**
   Specifies database roles that will be granted to all database owners. Owners
-  can then use `SET ROLE` to obtain privileges of these roles to e.g.
+  can then use `SET ROLE` to obtain privileges of these roles to e.g. create
-  create/update functionality from extensions as part of a migration script.
+  or update functionality from extensions as part of a migration script. One
-  Note, that roles listed here should be preconfigured in the docker image
+  such role can be `cron_admin` which is provided by the Spilo docker image to
-  and already exist in the database cluster on startup. One such role can be
+  set up cron jobs inside the `postgres` database. In general, roles listed
-  `cron_admin` which is provided by the Spilo docker image to set up cron
+  here should be preconfigured in the docker image and already exist in the
-  jobs inside the `postgres` database. Default is `empty`.
+  database cluster on startup. Otherwise, syncing roles will return an error
+  on each cluster sync process. Alternatively, you have to create the role and
+  do the GRANT manually. Note, the operator will not allow additional owner
+  roles to be members of database owners because it should be vice versa. If
+  the operator cannot set up the correct membership it tries to revoke all
+  additional owner roles from database owners. Default is `empty`.
 
 * **enable_password_rotation**
   For all `LOGIN` roles that are not database owners the operator can rotate

pkg/util/users/users.go

@@ -119,8 +119,10 @@ func (strategy DefaultUserSyncStrategy) ExecuteSyncRequests(requests []spec.PgSy
 			if err := strategy.alterPgUser(request.User, db); err != nil {
 				reqretries = append(reqretries, request)
 				errors = append(errors, fmt.Sprintf("could not alter user %q: %v", request.User.Name, err))
-				// check if additional owners are misconfigured as members to a database owner (check #1862 for details)
+				// XXX: we do not allow additional owner roles to be members of database owners
-				// resolve it by revoking the database owner from the additional owner role
+				// if ALTER fails it could be because of the wrong memberhip (check #1862 for details)
+				// so in any case try to revoke the database owner from the additional owner roles
+				// the initial ALTER statement will be retried once and should work then
 				if request.User.IsDbOwner && len(strategy.AdditionalOwnerRoles) > 0 {
 					if err := resolveOwnerMembership(request.User, strategy.AdditionalOwnerRoles, db); err != nil {
 						errors = append(errors, fmt.Sprintf("could not resolve owner membership for %q: %v", request.User.Name, err))