Skip to content

Commit

Permalink
Improve the docs on creating Secrets (#883)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
IwonaLanger authored Oct 17, 2024
1 parent a0e4c9c commit a05f80c
Show file tree
Hide file tree
Showing 15 changed files with 527 additions and 477 deletions.
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand All @@ -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! --->
Expand Down
364 changes: 4 additions & 360 deletions docs/assets/access_configuration.drawio.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
322 changes: 322 additions & 0 deletions docs/assets/secrets_precedence_4.drawio.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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).
2 changes: 1 addition & 1 deletion docs/user/03-10-preconfigured-secret.md
Original file line number Diff line number Diff line change
Expand Up @@ -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**
Expand Down
35 changes: 26 additions & 9 deletions docs/user/03-20-multitenancy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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).

83 changes: 83 additions & 0 deletions docs/user/03-21-create-service-instance-with-custom-secret.md
Original file line number Diff line number Diff line change
@@ -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)
Original file line number Diff line number Diff line change
@@ -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)
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/user/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
11 changes: 6 additions & 5 deletions docs/user/_sidebar.md
Original file line number Diff line number Diff line change
@@ -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 -->
Loading

0 comments on commit a05f80c

Please sign in to comment.