support multi subaccount documentation

README.md

@@ -25,7 +25,7 @@ The SAP BTP service operator is based on the [Kubernetes Operator pattern](https
     * [Managing access](#managing-access)
 * [SAP BTP kubectl Extension](#sap-btp-kubectl-plugin-experimental) 
 * [Credentials Rotation](#credentials-rotation)
-* [Multitenancy](#multitenancy)
+* [Working with Multiple Subaccounts](#working-with-multiple-subaccounts)
 * [Troubleshooting and Support](#troubleshooting-and-support)
 * [Formats of Secret Objects](#formats-of-secret-objects)
 * [Uninstalling the Operator](#uninstalling-the-operator)
@@ -241,7 +241,9 @@ spec:
 | parametersFrom | `[]object` | List of sources to populate parameters.                                                                                                                                                                           |
 | customTags | `[]string` | List of custom tags describing the ServiceInstance, will be copied to `ServiceBinding` secret in the key called `tags`.                                                                                           |
 | userInfo | `object` | Contains information about the user that last modified this service instance.                                                                                                                                     |
-| shared |  `*bool`   | The shared state. Possible values: true, false, or nil (value was not specified, counts as "false").                                                                                                                                                                               |
+| shared |  `*bool`   | The shared state. Possible values: true, false, or nil (value was not specified, counts as "false").                                                                                                              |
+| btpAccessCredentialsSecret |  `string`   | Name of a secret which contain access credentials for the SAP BTP service operator. see [Working with Multiple Subaccounts](#Working-with-multiple-subaccounts)                                                                                 |
+
 
 #### Status
 | Parameter         | Type     | Description                                                                                                   |
@@ -426,24 +428,38 @@ You can also choose the `services.cloud.sap.com/forceRotate` annotation (value d
 
 [Back to top](#sap-business-technology-platform-sap-btp-service-operator-for-kubernetes)
 
-## Multitenancy
-You can configure the SAP BTP service operator to work with more than one subaccount in the same Kubernetes cluster. This means that different namespaces can be connected to different subaccounts.
-The association between a namespace and a subaccount is based on a different set of credentials configured for different namespaces.
+## Working with Multiple Subaccounts
 
-To connect the namespace to a subaccount, you first have to obtain the [access credentials](#setup) for the SAP BTP service operator and then maintain them in a secret that is specific for that namespace.
+By default, a Kubernetes cluster is associated with one subaccount (see step 4 of the [Setup](#setup) section.)
+The general steps you must execute to associate a subaccount to a cluster:
 
-There are two options to maintain namespace-specific credentials, and they differ between default and TLS-based access credentials types:
+* Obtain the SAP BTP service operator's [access credentials](#setup).
+
+* Store these credentials securely in a secret.
+
+You can also apply more complex use cases whereby more than one subaccount is associated with a Kubernetes cluster.
+This can happen on the two levels within the cluster:
+
+- in a namespace
+- in a specific `ServiceInstance` resource in a namespace
+
+Secret types related to these use cases are outlined below. 
+
+### Default Secret For a Namespace
+
+To associate namespace to a specific subaccount you maintain the access credentials to the subaccount in a secret which is dedicated to a specific namespace. 
+Define a secret named: `<namespace-name>-sap-btp-service-operator` in the centrally-managed namespace.
+
+**Note:**
+The system's centrally-managed namespace is set by the value in `.Values.manager.management_namespace`. You can provide this value during installation (refer to step 4 in the [Setup](#setup) section). 
+If you don't specify this value, the system will use the installation namespace as the default.
 
-### Default Access Credentials
-- Define a secret named `sap-btp-service-operator` in the namespace. `ServiceInstance` and `ServiceBinding` that are applied in the namespace will belong to the subaccount from which the credentials were issued.  
-- Define different secrets for different namespaces in a [centrally managed namespace](./sapbtp-operator-charts/templates/configmap.yml), following the secret naming convention: `<namespace>-sap-btp-service-operator`.
-#### Namespace Secret Structure
 ```yaml
 apiVersion: v1
 kind: Secret
 metadata:
-  name: sap-btp-service-operator
-  namespace: <namespace>
+  name: <namespace-name>-sap-btp-service-operator
+  namespace: <centrally managed namespace>
 type: Opaque
 data:
   clientid: "<clientid>"
@@ -452,11 +468,67 @@ data:
   tokenurl: "<auth_url>"
   tokenurlsuffix: "/oauth/token"
 ```
+If you are using TLS binding, create additional secret named `<namespace-name>-sap-btp-service-operator-tls`. It contains the TLS certificate and key.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: <namespace-name>-sap-btp-service-operator-tls
+  namespace: <centrally managed namespace>
+type: kubernetes.io/tls
+data:
+  tls.crt: <crt> #base64 encoded
+  tls.key: <key> #base64 encoded
+```
+
+
+### Explicit Subaccount per `ServiceInstance` Resource  
 
-### TLS-Based Access Credentials
-- Define a secret pair named `sap-btp-service-operator` and `sap-btp-service-operator-tls`  in the namespace. `ServiceInstance` and `ServiceBinding` that are applied in the namespace will belong to the subaccount from which the credentials were issued.  
-- Define different secrets for different namespaces in a [centrally managed namespace](./sapbtp-operator-charts/templates/configmap.yml), following the secret naming convention: `<namespace>-sap-btp-service-operator` and `<namespace>-sap-btp-service-operator-tls`. For more information, see [tls secret](./sapbtp-operator-charts/templates/secret-tls.yml).
-#### Namespace Secrets Structure
+To associate a `ServiceInstance` resource to a specific subaccount, you maintain the access credentials to the subaccount in a secret which is located in the centrally-managed namespace.
+
+#### Define a new secret
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: mybtpsecret
+  namespace: <centrally managed namespace>
+type: Opaque
+data:
+  clientid: "<clientid>"
+  clientsecret: "<clientsecret>"
+  sm_url: "<sm_url>"
+  tokenurl: "<auth_url>"
+  tokenurlsuffix: "/oauth/token"
+```
+
+#### Configure the secret name in the `ServiceInstance` resource within the property `btpAccessCredentialsSecret`:
+```yaml
+apiVersion: services.cloud.sap.com/v1
+kind: ServiceInstance
+metadata:
+  name: sample-instance-1
+spec:
+  serviceOfferingName: service-manager
+  servicePlanName: subaccount-audit
+  btpAccessCredentialsSecret: mybtpsecret
+```
+
+##### Presedence during Authentication
+SAP BRP service operator checks for the credentials in the following order:
+1. Explicit secret defined in the `ServiceInstance` resource
+2. Default namespace secret
+3. Default cluster secret
+
+[Back to top](#sap-business-technology-platform-sap-btp-service-operator-for-kubernetes)
+
+### Developer Mode Secret
+To allow a user to work with....
+Define a secret named `sap-btp-service-operator` in the namespace.
+`ServiceInstance` and `ServiceBinding` applied in the namespace belong to the subaccount from which the credentials were issued.
+
+#### Namespace Secret Structure
 ```yaml
 apiVersion: v1
 kind: Secret
@@ -466,10 +538,12 @@ metadata:
 type: Opaque
 data:
   clientid: "<clientid>"
+  clientsecret: "<clientsecret>"
   sm_url: "<sm_url>"
   tokenurl: "<auth_url>"
   tokenurlsuffix: "/oauth/token"
 ```
+with TLS configurations:
 ```yaml
 apiVersion: v1
 kind: Secret
@@ -482,12 +556,6 @@ data:
   tls.key: <key> #base64 encoded
 ```
 
-**Notes:**
-- If none of the those mentioned above options are set, `sap-btp-service-operator` secret of a release namespace is used.<br>
-  See step 4 of the [Setup](#setup) section.
-
-[Back to top](#sap-business-technology-platform-sap-btp-service-operator-for-kubernetes)
-
 ## Troubleshooting and Support
 
   #### Cannot Create a Service Binding for Service Instance in `Delete Failed` State