Improve the docs on creating Secrets (#883)

* Improve the docs on creating Secrets

* Update the secrets precedence diagram

* Formatting fixes

* Fix broken links

* Use placeholders in code blocks

* Fix the sidebar file

* Add step 6 in creating Secret procedure

* CR section

* Apply review suggestions

* More review suggestions applied

README.md

@@ -8,11 +8,11 @@ BTP Manager is an operator for the [SAP BTP service operator](https://github.com
 
 ## Installation
 
-To enable the SAP BTP Operator module from the latest release, you must install BTP Manager. For installation instructions, see [Install the SAP BTP Operator module](./docs/user/tutorials/04-30-install-module.md).
+To enable the SAP BTP Operator module from the latest release, you must install BTP Manager. For installation instructions, see [Install the SAP BTP Operator module](./docs/user/03-05-install-module.md).
 
 ## Usage
 
-Use SAP BTP Operator to create SAP BTP services in your Kyma cluster. To find out how to do it, see [Create an SAP BTP Service Instance in Your Kyma Cluster](./docs/user/tutorials/04-40-create-service-in-cluster.md).
+Use SAP BTP Operator to create SAP BTP services in your Kyma cluster. To find out how to do it, see the tutorial [Create an SAP BTP Service Instance in Your Kyma Cluster](./docs/user/tutorials/04-40-create-service-in-cluster.md).
 
 ## Uninstallation
 
@@ -38,8 +38,12 @@ If you want to provide new features for BTP Manager, visit the [`contributor`](.
 
 In the [`user`](./docs/user) folder, you will find the following documents:
 * [SAP BTP Operator Module](./docs/user/README.md)
+* [Create the `sap-btp-manager` Secret](./docs/user/03-00-create-btp-manager-secret.md)
+* [Install the SAP BTP Operator Module](./docs/user/03-05-install-module.md)
 * [Preconfigured Credentials and Access](./docs/user/03-10-preconfigured-secret.md)
 * [Working with Multiple Subaccounts](./docs//user/03-20-multitenancy.md)
+* [Create a Service Instance with a Custom Secret](./docs/user/03-21-create-service-instance-with-custom-secret.md)
+* [Create a Service Instance with a Namespace-Based Secret](./docs/user/03-22-create-service-instance-with-namespace-based-secret.md)
 * [Management of the Service Instances and Service Bindings Lifecycle](./docs//user/03-30-management-of-service-instances-and-bindings.md)
 * [Service Binding Rotation](./docs//user/03-40-service-binding-rotation.md)
 * [Formats of Service Binding Secrets](./docs//user/03-50-formatting-service-binding-secret.md)
@@ -48,11 +52,7 @@ In the [`user`](./docs/user) folder, you will find the following documents:
   * [Service Instance Custom Resource](./docs/user/resources/02-20-service-instance-cr.md)
   * [Service Binding Custom Resource](./docs/user/resources/02-30-service-binding-cr.md)
 * [Tutorials](./docs/user/tutorials/README.md)
-  * [Create a BTP Manager Secret](./docs/user/tutorials/04-10-create-btp-manager-secret.md)
-  * [Create a SAP BTP Service Operator Secret](./docs/user/tutorials/04-20-create-btp-service-operator-secret.md)
-  * [Install the SAP BTP Operator Module](./docs/user/tutorials/04-30-install-module.md)
   * [Create an SAP BTP Service Instance in Your Kyma Cluster](./docs/user/tutorials/04-40-create-service-in-cluster.md)
-  * [Create a Service Instance with a Custom Secret](./docs/user/tutorials/04-50-create-service-instance-with-custom-secret.md)
 
 ## Contributing
 <!--- mandatory section - do not change this! --->

docs/user/tutorials/04-10-create-btp-manager-secret.md → docs/user/03-00-create-btp-manager-secret.md

@@ -1,4 +1,4 @@
-# Create `sap-btp-manager` Secret
+# Create the `sap-btp-manager` Secret
 
 <!--this content is for OS users only-->
 To create the `sap-btp-manager` Secret, follow these steps:

docs/user/tutorials/04-30-install-module.md → docs/user/03-05-install-module.md

@@ -8,7 +8,7 @@ To install the SAP BTP Operator module from the latest release, you must install
 * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
 * Kubernetes cluster, or [k3d](https://k3d.io) for local installation
 * [jq](https://github.com/stedolan/jq)
-* `sap-btp-manager` Secret created. See [Create `sap-btp-manager` Secret](04-10-create-btp-manager-secret.md).
+* `sap-btp-manager` Secret created. See [Create the `sap-btp-manager` Secret](03-00-create-btp-manager-secret.md).
   > [!NOTE]
   > If you don't create the `sap-btp-manager` Secret, the BtpOperator CR is in the `Warning` state and the message is `Secret resource not found reason: MissingSecret`.
 * `kyma-system` namespace. If you don't have it in your cluster, use the following command to create it:
@@ -40,4 +40,4 @@ To install the SAP BTP Operator module from the latest release, you must install
    kubectl get btpoperators btpoperator
    ```
 
-For more installation options, see [Install and Uninstall BTP Manager](../../contributor/01-10-installation.md)
+For more installation options, see [Install and Uninstall BTP Manager](../contributor/01-10-installation.md).

docs/user/03-10-preconfigured-secret.md

@@ -15,7 +15,7 @@ When you create a Kyma instance in the SAP BTP cockpit, the following events hap
    * The `sap-btp-operator-config` ConfigMap.
 
 > [!TIP]
-> In this scenario, the `sap-btp-service-operator` Secret is automatically generated when you create Kyma runtime. To create this Secret manually for a specific namespace, see [Create `sap-btp-service-operator` Secret](./tutorials/04-20-create-btp-service-operator-secret.md).
+> In this scenario, the `sap-btp-service-operator` Secret is automatically generated when you create Kyma runtime. To create this Secret manually for a specific namespace, see [Create a Namespace-Based Secret](03-22-create-service-instance-with-namespace-based-secret.md#create-a-namespace-based-secret).
 
 The `sap-btp-manager` Secret provides the following credentials:
 * **clientid**

docs/user/03-20-multitenancy.md

@@ -2,15 +2,28 @@
 
 With the SAP BTP Operator module, you can create configurations for several subaccounts in a single Kyma cluster.
 
+## Context
+
+By default, a Kyma cluster is associated with one subaccount. Consequently, any service instance created within any namespace is provisioned in the associated subaccount. See [Preconfigured Credentials and Access](03-10-preconfigured-secret.md). However, SAP BTP Operator also supports configurations for several subaccounts in a single Kyma cluster.
 To apply the multitenancy feature, choose the method that suits your needs and application architecture: 
 * Namespace-based mapping: Connect namespaces to separate subaccounts by configuring dedicated credentials for each namespace.
 * Instance-level mapping: Define a specific subaccount for each service instance, regardless of the namespace context.
 
 Regardless of the method, you must create Secrets managed in the `kyma-system` namespace.
 
-### Namespace-Based Mapping
+### Secrets Precedence
+
+SAP BTP Operator searches for the credentials in the following order:
+1. Explicit Secret defined in a service instance
+2. Managed namespace Secret assigned for a given namespace
+3. Managed namespace default Secret
+
+![Secrets precedence](../assets/secrets_precedence_4.drawio.svg) 
+
+## Namespace-Based Mapping
+
+To connect a namespace to a specific subaccount, maintain access credentials to this subaccount in a Secret dedicated to the specific namespace. Define the `{NAMESPACE-NAME}-sap-btp-service-operator` Secret in the `kyma-system` namespace.
 
-To connect a namespace to a specific subaccount, maintain access credentials to this subaccount in a Secret dedicated to the specific namespace. Define the `{NAMESPACE-NAME}-sap-btp-service-operator` Secret in the `kyma-system` namespace. 
 See the following examples:
 * Default access credentials:
 
@@ -47,12 +60,17 @@ See the following examples:
     tokenurlsuffix: "/oauth/token"
   ```
 
-### Instance-Level Mapping
+For more information, see [Create a Service Instance with a Namespace-Based Secret](03-22-create-service-instance-with-namespace-based-secret.md).
+
+
+## Instance-Level Mapping
 
 To deploy service instances belonging to different subaccounts within the same namespace, follow these steps:
-1. Define a new Secret: Securely store access credentials for each subaccount in a separate Secret in the `kyma-system` namespace. 
+1. Define a new Secret: Securely store access credentials for each subaccount in a separate Secret in the `kyma-system` namespace.
+
    See the following examples:
    * Default access credentials
+
       ```yaml
       apiVersion: v1
       kind: Secret
@@ -68,6 +86,7 @@ To deploy service instances belonging to different subaccounts within the same n
         tokenurlsuffix: "/oauth/token"
       ```
     * mTLS access credentials
+
       ```yaml
       apiVersion: v1
       kind: Secret
@@ -85,6 +104,7 @@ To deploy service instances belonging to different subaccounts within the same n
       ```
 
 2. Specify a subaccount per service: Configure the Secret name in the ServiceInstance resource within the **btpAccessCredentialsSecret** property. The Secret containing the relevant subaccount's credentials tells SAP BTP Operator explicitly which subaccount to use to provision the service instance. The Secret must be located in the `kyma-system` namespace.
+
     ```yaml
     apiVersion: services.cloud.sap.com/v1
     kind: ServiceInstance
@@ -95,9 +115,6 @@ To deploy service instances belonging to different subaccounts within the same n
       servicePlanName: subaccount-audit
       btpAccessCredentialsSecret: {SECRET_NAME}
     ```
-### Secrets Precedence
 
-SAP BTP Operator searches for the credentials in the following order:
-1. Explicit Secret defined in a service instance
-2. Default namespace Secret
-3. Default cluster Secret
+  For more information, see [Create a Service Instance with a Custom Secret](03-21-create-service-instance-with-custom-secret.md).
+

docs/user/03-21-create-service-instance-with-custom-secret.md

@@ -0,0 +1,83 @@
+# Create a Service Instance with a Custom Secret
+
+To have multiple service instances from different subaccounts associated with one namespace, you must use a custom Secret to create these service instances.
+
+## Context
+
+To create a service instance with a custom Secret, you must use the **btpAccessCredentialsSecret** field in the `spec` of the service instance. In it, you pass the Secret from the `kyma-system` namespace to create your service instance. You can use different Secrets for different service instances.
+
+## Prerequisites
+
+* A subaccount in the SAP BTP cockpit
+
+## Procedure
+
+### Create Your Custom Secret
+
+1. [Create an SAP Service Manager service instance](03-30-management-of-service-instances-and-bindings.md#create-a-service-instance) with the `service-operator-access` plan.
+2. [Create a service binding](03-30-management-of-service-instances-and-bindings.md#create-a-service-binding) to the SAP Service Manager service instance you have created.
+3. Get the access credentials of the SAP Service Manager instance from its service binding. Copy them from the BTP cockpit as a JSON.
+4. Create the `creds.json` file in your working directory and save the credentials there.
+5. In the same working directory, generate the Secret by calling the `create-secret-file.sh` script with the **operator** option as the first parameter and **your-secret-name**  as the second parameter.
+
+    > [!WARNING] 
+    > Once you set a Secret name in the service instance, you cannot change it in the future.
+
+    ```sh
+    curl https://raw.githubusercontent.com/kyma-project/btp-manager/main/hack/create-secret-file.sh | bash -s operator {YOUR_SECRET_NAME}
+    ```
+
+    The expected result is the file `btp-access-credentials-secret.yaml` created in your working directory:
+
+    ```yaml
+    apiVersion: v1
+    kind: Secret
+    type: Opaque
+    metadata:
+      name: {YOUR_SECRET_NAME}
+      namespace: kyma-system
+    data:
+      clientid: {CLIENT_ID}
+      clientsecret: {CLIENT_SECRET}
+      sm_url: {SM_URL}
+      tokenurl: {AUTH_URL}
+      tokenurlsuffix: "/oauth/token"
+    ```
+
+6. To verify if you've correctly added the access credentials of the SAP Service Manager instance in your service instance, go to the CR `status` section, and make sure the subaccount ID to which the instance belongs is provided in the **subaccountID** field. The field must not be empty.
+
+### Create a Service Instance with the Custom Secret
+
+1. Create your service instance with:
+   * the **btpAccessCredentialsSecret** field in the `spec` pointing to the custom Secret you have created
+   * other parameters as needed<br>
+
+    See an example of a ServiceInstance custom resource:
+
+    ```yaml
+    kubectl create -f - <<EOF
+    apiVersion: services.cloud.sap.com/v1
+    kind: ServiceInstance
+    metadata:
+      name: {SERVICE_INSTANCE_NAME}
+      namespace: {NAMESPACE_NAME}
+    spec:
+      serviceOfferingName: {SERVICE_OFFERING_NAME}
+      servicePlanName: {SERVICE_PLAN_NAME}
+      btpAccessCredentialsSecret: {YOUR_SECRET_NAME}
+    EOF
+    ```
+
+2. To verify that your service instance has been created successfully, run:
+
+    ```bash
+    kubectl get serviceinstances.services.cloud.sap.com {SERVICE_INSTANCE_NAME} -o yaml
+    ```
+
+    You see the status `Created`.
+    You also see your Secret name in the **btpAccessCredentialsSecret** field of the `spec`.
+
+## Related Information
+
+[Working with Multiple Subaccounts](03-20-multitenancy.md)<br>
+[Create a Service Instance with a Namespace-Based Secret](03-22-create-service-instance-with-namespace-based-secret.md)

docs/user/03-22-create-service-instance-with-namespace-based-secret.md

@@ -0,0 +1,73 @@
+# Create a Service Instance with a Namespace-Based Secret
+
+To have service instances from one subaccount associated with one namespace, you must use a Secret dedicated to this namespace to create these service instances.
+
+## Prerequisites
+
+* A subaccount in the SAP BTP cockpit
+
+## Procedure
+
+### Create a Namespace-Based Secret
+
+1. [Create an SAP Service Manager service instance](03-30-management-of-service-instances-and-bindings.md#create-a-service-instance) with the `service-operator-access` plan.
+2. [Create a service binding](03-30-management-of-service-instances-and-bindings.md#create-a-service-binding) to the SAP Service Manager service instance you have created.
+3. Get the access credentials of the SAP Service Manager instance with the `service-operator-access` plan from its service binding. Copy them from the SAP BTP cockpit as a JSON.
+4. Create the `creds.json` file in your working directory and save the credentials there.
+5. In the same working directory, generate the Secret by calling the `create-secret-file.sh` script with the **operator** option as the first parameter and **managed namespace sap-btp-service-operator secret**  as the second parameter.
+
+    ```sh
+    curl https://raw.githubusercontent.com/kyma-project/btp-manager/main/hack/create-secret-file.sh | bash -s operator {NAMESPACE_NAME}-sap-btp-service-operator
+    ```
+
+    The expected result is the file `btp-access-credentials-secret.yaml` created in your working directory:
+
+    ```yaml
+    apiVersion: v1
+    kind: Secret
+    type: Opaque
+    metadata:
+      name: {NAMESPACE_NAME}-sap-btp-service-operator
+      namespace: kyma-system
+    data:
+      clientid: {CLIENT_ID}
+      clientsecret: {CLIENT_SECRET}
+      sm_url: {SM_URL}
+      tokenurl: {AUTH_URL}
+      tokenurlsuffix: "/oauth/token"
+    ```
+6. To verify if you've correctly added the access credentials of the SAP Service Manager instance in your service instance, go to the CR `status` section, and make sure the subaccount ID to which the instance belongs is provided in the **subaccountID** field. The field must not be empty.
+
+### Create a Service Instance with a Managed Namespace Secret
+
+1. Provide the needed parameters and create your service instance.
+
+    See an example of a ServiceInstance custom resource:
+
+    ```yaml
+    kubectl create -f - <<EOF
+    apiVersion: services.cloud.sap.com/v1
+    kind: ServiceInstance
+    metadata:
+      name: {SERVICE_INSTANCE_NAME}
+      namespace: {NAMESPACE_NAME}
+    spec:
+      serviceOfferingName: {SERVICE_OFFERING_NAME}
+      servicePlanName: {SERVICE_PLAN_NAME}
+    EOF
+    ```
+
+2. To verify that your service instance has been created successfully, run:
+
+    ```bash
+    kubectl get serviceinstances.services.cloud.sap.com {SERVICE_INSTANCE_NAME} -o yaml
+    ```
+
+## Result
+
+You see the status `Created` and the message confirming that your servicde instance was created successfully.
+
+## Related Information
+
+[Working with Multiple Subaccounts](03-20-multitenancy.md)<br>
+[Create a Service Instance with a Custom Secret](03-21-create-service-instance-with-custom-secret.md)

docs/user/03-30-management-of-service-instances-and-bindings.md

@@ -70,7 +70,7 @@ These access credentials are available to applications through a Secret resource
     ```bash
     kubectl get secrets {SECRET_NAME} -n {NAMESPACE}
     NAME              TYPE     DATA   AGE
-    {SECRET_NAME}    Opaque   5      32s
+    {SECRET_NAME}     Opaque   5      32s
     ```
 
     To learn about different options for using the credentials from your application running in the Kubernetes cluster, see [Uses for Secrets](https://kubernetes.io/docs/concepts/configuration/secret/#uses-for-secrets).
@@ -121,7 +121,7 @@ See the following example of the `spec` format in JSON:
 }
 ```
 
-See the exampple of a Secret with the key named **secret-parameter**:
+See the example of a Secret with the key named **secret-parameter**:
 
 ```yaml
 apiVersion: v1

docs/user/README.md

@@ -23,7 +23,7 @@ By default, the scope of the SAP BTP Operator module is your Kyma runtime, which
 
 ## Architecture
 
-The SAP BTP Operator module provides and retrieves the initial credentials necessary that your application needs to use an SAP BTP service.
+The SAP BTP Operator module provides and retrieves the initial credentials that your application needs to use an SAP BTP service.
 
 ![SAP BTP Operator architecture](../assets/module_architecture.drawio.svg)
 

docs/user/_sidebar.md

@@ -1,19 +1,20 @@
 <!-- markdown-link-check-disable -->
 * [Back to Kyma Home](/)
 * [SAP BTP Operator Module](/btp-manager/user/README.md)
+* [Create the `sap-btp-manager` Secret](/btp-manager/user/03-00-create-btp-manager-secret.md)
+* [Install the SAP BTP Operator Module](/btp-manager/user/03-05-install-module.md)
 * [Preconfigured Credentials and Access](/btp-manager/user/03-10-preconfigured-secret.md)
-* [Working with Multiple Subaccounts](/btp-manager/user/03-20-multitenancy.md)
 * [Management of the Service Instances and Service Bindings Lifecycle](/btp-manager/user/03-30-management-of-service-instances-and-bindings.md)
+* [Working with Multiple Subaccounts](/btp-manager/user/03-20-multitenancy.md)
+   * [Create a Service Instance with a Custom Secret](/btp-manager/user/03-21-create-service-instance-with-custom-secret.md)
+   * [Create a Service Instance with a Namespace-Based Secret](/btp-manager/user/03-22-create-service-instance-with-namespace-based-secret.md)
 * [Service Binding Rotation](/btp-manager/user/03-40-service-binding-rotation.md)
 * [Formats of Service Binding Secrets](/btp-manager/user/03-50-formatting-service-binding-secret.md)
 * [Resources](/btp-manager/user/resources/README.md)
   * [SAP BTP Operator Custom Resource](/btp-manager/user/resources/02-10-sap-btp-operator-cr.md)
   * [Service Instance Custom Resource](/btp-manager/user/resources/02-20-service-instance-cr.md)
   * [Service Binding Custom Resource](/btp-manager/user/resources/02-30-service-binding-cr.md)
 * [Tutorials](/btp-manager/user/tutorials/README.md)
-  * [Create `sap-btp-manager` Secret](/btp-manager/user/tutorials/04-10-create-btp-manager-secret.md)
-  * [Create a Custom `sap-btp-service-operator` Secret](/btp-manager/user/tutorials/04-20-create-btp-service-operator-secret.md)
-  * [Install the SAP BTP Operator Module](/btp-manager/user/tutorials/04-30-install-module.md)
   * [Create an SAP BTP Service in Your Kyma Cluster](/btp-manager/user/tutorials/04-40-create-service-in-cluster.md)
-  * [Create a Service Instance with a Custom Secret](/btp-manager/user/tutorials/04-50-create-service-instance-with-custom-secret.md)
+
 <!-- markdown-link-check-enable -->