Describe how to use existing users

Signed-off-by: Nikolai Rodionov <iam@allanger.xyz>

Author: allanger

docs/database.md

@@ -252,6 +252,24 @@ USER: << base64 encoded user name (generated by db operator) >>
 
 Then DB Operator will connect to an existing database and set up a user for it.
 
+
+## Using an existing user
+
+Since version **2.22.0** it's possible to make DB Operator grant access to a database to an existing user instead of generating a new one. To do so add `.spec.existingUser: ${USERNAME}` to your manifest.
+
+```yaml
+kind: Database
+metadata: {}
+spec:
+  existingUser: my-db-user
+```
+
+When using an existing user, DB Operator is not aware of the password anymore, hence the **password** field in the credentials Secret will be empty. Users must handle the authentication on their own.
+
+It's also important to understand, that when you are switching **from/to** existing user **to/from** a generated one, you need to remove the Secret from the cluster, so it's recreated, otherwise it's either going to be empty for a generated user, or filled for an existing one. It will most probably be fixed in future versions.
+
+Another thing that is worth mentioning, DB Operator is running a health check on each reconciliation, and with generated users it's trying to access a database using these users, but as DB Operator is not aware of a password of an existing users, it's performing a health check as an admin, and hence can't verify whether a user really has the required access.
+
 ## Experimental features
 
 Experimental features are added via annotations, the following features are available for `Databases`

docs/dbuser.md

@@ -60,6 +60,21 @@ spec:
 
 This metadata can be used by external controllers that watch annotations or require specific labels to enable Secret synchronization or reflection across namespaces.
 
+## Using an existing user
+
+Since version **2.22.0** it's possible to make DB Operator grant access to a database to an existing user instead of generating a new one. To do so add `.spec.existingUser: ${USERNAME}` to your manifest.
+
+```yaml
+kind: DbUser
+metadata: {}
+spec:
+  existingUser: my-db-user
+```
+
+When using an existing user, DB Operator is not aware of the password anymore, hence the **password** field in the credentials Secret will be empty. Users must handle the authentication on their own.
+
+It's also important to understand, that when you are switching **from/to** existing user **to/from** a generated one, you need to remove the Secret from the cluster, so it's recreated, otherwise it's either going to be empty for a generated user, or filled for an existing one. It will most probably be fixed in future versions.
+
 ## Experimental features
 
 Experimental features are added via annotations, the following features are available for `DbUsers`