diff --git a/README.md b/README.md index 1c362f16b..337a3d37a 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,11 @@ In the [`user`](./docs/user) folder, you will find the following documents: * [Working with Multiple Subaccounts](./docs//user/03-20-multitenancy.md) * [Instance-Level Mapping](./docs/user/03-21-instance-level-mapping.md) * [Namespace-Level Mapping](./docs/user/03-22-namespace-level-mapping.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) +* [Create Service Instances and Service Bindings](./docs//user/03-30-create-instances-and-bindings.md) +* [Rotate Service Binding](./docs//user/03-40-service-binding-rotation.md) * [Formats of Service Binding Secrets](./docs//user/03-50-formatting-service-binding-secret.md) +* [Pass Parameters](./docs/user/03-60-pass-parameters.md) +* [Delete Service Bindigs and Service Instances](./docs/user/03-70-delete-bindings-and-instances.md) * [Resources](./docs/user/resources/README.md) * [SAP BTP Operator Custom Resource](./docs/user/resources/02-10-sap-btp-operator-cr.md) * [Service Instance Custom Resource](./docs/user/resources/02-20-service-instance-cr.md) diff --git a/docs/user/03-10-preconfigured-secret.md b/docs/user/03-10-preconfigured-secret.md index bedec0cb7..2ca915a57 100644 --- a/docs/user/03-10-preconfigured-secret.md +++ b/docs/user/03-10-preconfigured-secret.md @@ -5,25 +5,31 @@ When you create SAP BTP, Kyma runtime, all necessary resources for consuming SAP ## Credentials When you create a Kyma instance in the SAP BTP cockpit, the following events happen in your subaccount: + 1. An SAP Service Manager service instance with the `service-operator-access` plan is created. 2. An SAP Service Manager service binding with access credentials for the SAP BTP Operator is created. 3. The credentials from the service binding are passed on to the Kyma service instance in the creation process. 4. The `sap-btp-manager` Secret is created and managed in the `kyma-system` namespace. 5. The SAP BTP Operator module is installed by default together with: + * The `sap-btp-manager` Secret. * The `sap-btp-service-operator` Secret with the access credentials for the SAP BTP service operator. You can view the credentials in the `kyma-system` namespace. * The `sap-btp-operator-config` ConfigMap. -> [!TIP] +> [!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 a Namespace-Based Secret](03-22-namespace-level-mapping.md#create-a-namespace-based-secret). The `sap-btp-manager` Secret provides the following credentials: + * **clientid** * **clientsecret** * **cluster_id** * **sm_url** * **tokenurl** +> [!NOTE] +> If you modify or delete the `sap-btp-manager` Secret, it is modified back to its previous settings or regenerated within up to 24 hours. + When you add the SAP BTP Operator module to your cluster, the `sap-btp-manager` Secret generates the SAP BTP service operator's resources as shown in the following diagram: @@ -31,11 +37,9 @@ When you add the SAP BTP Operator module to your cluster, the `sap-btp-manager` The cluster ID represents a Kyma service instance created in a particular subaccount and allows for its identification. You can view the cluster ID in the SAP BTP cockpit: * In the `sap-btp-manager` Secret +* In the `sap-btp-service-operator` Secret * In the `sap-btp-operator-config` ConfigMap -> [!NOTE] -> If you modify or delete the `sap-btp-manager` Secret, it is modified back to its previous settings or regenerated within up to 24 hours. - ## Cluster Access By default, SAP BTP Operator has cluster-wide permissions. You cannot reconfigure the predefined settings. diff --git a/docs/user/03-20-multitenancy.md b/docs/user/03-20-multitenancy.md index 5b8d2927b..6c16dbe49 100644 --- a/docs/user/03-20-multitenancy.md +++ b/docs/user/03-20-multitenancy.md @@ -4,8 +4,9 @@ With the SAP BTP Operator module, you can create configurations for several suba ## 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: +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, with SAP BTP Operator, you can create configurations in a single Kyma cluster that are applied to several subaccounts. +To apply the multitenancy feature, choose the method that suits your needs and application architecture: + * [Namespace-level mapping](03-22-namespace-level-mapping.md): Connect namespaces to separate subaccounts by configuring dedicated credentials for each namespace. * [Instance-level mapping](03-21-instance-level-mapping.md): Define a specific subaccount for each service instance, regardless of the namespace context. @@ -14,103 +15,14 @@ Regardless of the method, you must create Secrets managed in the `kyma-system` n ### 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-Level 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. - -See the following examples: -* Default access credentials: - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: {NAMESPACE_NAME}-sap-btp-service-operator - namespace: kyma-system - type: Opaque - stringData: - clientid: {CLIENT_ID} - clientsecret: {CLIENT_SECRET} - sm_url: {SM_URL} - tokenurl: {AUTH_URL} - tokenurlsuffix: "/oauth/token" - ``` - -* mTLS access credentials: - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: {NAMESPACE_NAME}-sap-btp-service-operator - namespace: kyma-system - type: Opaque - stringData: - clientid: {CLIENT_ID} - tls.crt: {TLS_CERTIFICATE} - tls.key: {TLS_KEY} - sm_url: {SM_URL} - tokenurl: {AUTH_URL} - tokenurlsuffix: "/oauth/token" - ``` - -## 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. - - See the following examples: - * Default access credentials - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: {SECRET_NAME} - namespace: kyma-system - type: Opaque - stringData: - clientid: {CLIENT_ID} - clientsecret: {CLIENT_SECRET} - sm_url: {SM_URL} - tokenurl: {AUTH_URL} - tokenurlsuffix: "/oauth/token" - ``` - - * mTLS access credentials - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: {SECRET_NAME} - namespace: kyma-system - type: Opaque - stringData: - clientid: {CLIENT_ID} - tls.crt: {TLS_CERTIFICATE} - tls.key: {TLS_KEY} - sm_url: {SM_URL} - tokenurl: {AUTH_URL} - tokenurlsuffix: "/oauth/token" - ``` - -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. +## Procedure - ```yaml - apiVersion: services.cloud.sap.com/v1 - kind: ServiceInstance - metadata: - name: {SERVICE_INSTANCE_NAME} - spec: - serviceOfferingName: service-manager - servicePlanName: subaccount-audit - btpAccessCredentialsSecret: {SECRET_NAME} - ``` - \ No newline at end of file +* To connect a namespace to a specific subaccount, see [Namespace-Level Mapping](03-22-namespace-level-mapping.md). +* To deploy service instances belonging to different subaccounts within the same namespace, see [Instance-Level Mapping](03-21-instance-level-mapping.md). diff --git a/docs/user/03-21-instance-level-mapping.md b/docs/user/03-21-instance-level-mapping.md index d685970f1..91803b7a0 100644 --- a/docs/user/03-21-instance-level-mapping.md +++ b/docs/user/03-21-instance-level-mapping.md @@ -5,22 +5,20 @@ You can map a Kubernetes service instance to an SAP Service Manager instance in ## Prerequisites * A subaccount in the SAP BTP cockpit. -* kubectl configured for communicating with your Kyma instance. +* kubectl configured for communicating with your Kyma instance. See [Access a Kyma Instance Using kubectl](https://help.sap.com/docs/btp/sap-business-technology-platform/access-kyma-instance-using-kubectl). ## Context -To have multiple service instances from different subaccounts associated with a namespace, you must use a custom Secret to create these service instances. +To have multiple service instances from different subaccounts associated with a namespace, you must store access credentials for each subaccount in a custom Secret in the `kyma-system` namespace. 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. -## Procedure - -### Create Your Custom Secret +## Create Your Custom Secret 1. In the SAP BTP cockpit, create an SAP Service Manager service instance with the `service-operator-access` plan. See [Creating Instances in Other Environments](https://help.sap.com/docs/service-manager/sap-service-manager/creating-instances-in-other-environments?locale=en-US&version=Cloud). 2. Create a service binding to the SAP Service Manager service instance you have created. See [Creating Service Bindings in Other Environments](https://help.sap.com/docs/service-manager/sap-service-manager/creating-service-bindings-in-other-environments?locale=en-US&version=Cloud). -3. Get the access credentials of the SAP Service Manager instance from its service binding. Copy them from the BTP cockpit as a JSON. +3. Get the access credentials of the SAP Service Manager instance from its service binding. Copy them from the BTP cockpit as a JSON file. 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: +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: ```sh curl https://raw.githubusercontent.com/kyma-project/btp-manager/main/hack/create-secret-file.sh | bash -s operator {YOUR_SECRET_NAME} @@ -49,13 +47,42 @@ To create a service instance with a custom Secret, you must use the **btpAccessC kubectl create -f ./btp-access-credentials-secret.yaml ``` +7. To verify if the Secret has been successfully created, run: + + ``` + kubectl get secret -n kyma-system {YOUR_SECRET_NAME} + ``` + You see the status `Created`. -### Create a Service Instance with the Custom Secret + > [!NOTE] + > You can also view the Secret in Kyma dashboard. In the `kyma-system` namespace, go to **Configuration** -> **Secrets**, and check the list of Secrets. + +## Create a Service Instance with the Custom Secret + +To create the service instance, use either Kyma dashboard or kubectl. + +### Procedure + + +#### Use Kyma Dashboard + +1. In the **Namespaces** view, go to the namespace you want to work in. +2. Go to **Service Management** -> **Service Instances**. +3. In the **BTP Access Credentials Secret** field, add the name of the custom Secret you have created. +4. Provide other required service details and create a service instance. + + > [!WARNING] + > Once you set a Secret name in the service instance, you cannot change it in the future. + + You see the status `PROVISIONED`. + +#### Use kubectl 1. Create your service instance with: - * the **btpAccessCredentialsSecret** field in the `spec` pointing to the custom Secret you have created - * other parameters as needed
+ + * The **btpAccessCredentialsSecret** field in the `spec` pointing to the custom Secret you have created + * Other parameters as needed > [!WARNING] > Once you set a Secret name in the service instance, you cannot change it in the future. @@ -86,6 +113,7 @@ To create a service instance with a custom Secret, you must use the **btpAccessC You also see your Secret name in the **btpAccessCredentialsSecret** field of the `spec`. 3. 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. + ## Related Information diff --git a/docs/user/03-22-namespace-level-mapping.md b/docs/user/03-22-namespace-level-mapping.md index 22df838cf..0389d2af4 100644 --- a/docs/user/03-22-namespace-level-mapping.md +++ b/docs/user/03-22-namespace-level-mapping.md @@ -5,19 +5,17 @@ You can map a Kubernetes namespace to an SAP Service Manager instance in a given ## Prerequisites * A subaccount in the SAP BTP cockpit. -* kubectl configured for communicating with your Kyma instance. +* kubectl configured for communicating with your Kyma instance. See [Access a Kyma Instance Using kubectl](https://help.sap.com/docs/btp/sap-business-technology-platform/access-kyma-instance-using-kubectl). ## Context -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. +To connect a namespace to a specific subaccount, maintain the access credentials to the subaccount in a Secret dedicated to a specific namespace. Create the `{NAMESPACE-NAME}-sap-btp-service-operator` Secret in the `kyma-system` namespace. -## Procedure +## Create a Namespace-Based Secret -### Create a Namespace-Based Secret - -1. In the SAP BTP cockpit, create an SAP Service Manager service instance with the `service-operator-access` plan. See [Creating Instances in Other Environments](https://help.sap.com/docs/service-manager/sap-service-manager/creating-instances-in-other-environments?locale=en-US&version=Cloud). +1. In the SAP BTP cockpit, create a new SAP Service Manager service instance with the `service-operator-access` plan. See [Creating Instances in Other Environments](https://help.sap.com/docs/service-manager/sap-service-manager/creating-instances-in-other-environments?locale=en-US&version=Cloud). 2. Create a service binding to the SAP Service Manager service instance you have created. See [Creating Service Bindings in Other Environments](https://help.sap.com/docs/service-manager/sap-service-manager/creating-service-bindings-in-other-environments?locale=en-US&version=Cloud). -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. +3. Get the access credentials of the SAP Service Manager instance from its service binding. Copy them from the SAP BTP cockpit as a JSON file. 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 **namespace-name-sap-btp-service-operator** Secret as the second parameter. @@ -50,11 +48,11 @@ To have service instances from one subaccount associated with one namespace, you You can see the status `Created`. -### Create a Service Instance with a Namespace-Based Secret +## Create a Service Instance with a Namespace-Based Secret -1. To create a service instance with a namespace-based Secret, follow the instructions on [creating service instances](03-30-management-of-service-instances-and-bindings.md#create-a-service-instance). +1. To create a service instance with a namespace-based Secret, follow the instructions in [Create Service Instances and Service Bindings](03-30-create-instances-and-bindings.md). -2. 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. +2. To verify if you've correctly added the access credentials of the SAP Service Manager instance in your service instance, go to the custom resource (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. ## Related Information diff --git a/docs/user/03-30-create-instances-and-bindings.md b/docs/user/03-30-create-instances-and-bindings.md new file mode 100644 index 000000000..145a1a6fa --- /dev/null +++ b/docs/user/03-30-create-instances-and-bindings.md @@ -0,0 +1,125 @@ +# Create Service Instances and Service Bindings + +To use an SAP BTP service in your Kyma cluster, create its service instance and service binding using Kyma dashboard or kubectl. + +## Prerequisites + +* The [SAP BTP Operator module](README.md) is added. For instructions on adding modules, see [Add and Delete a Kyma Module](https://help.sap.com/docs/btp/sap-business-technology-platform/enable-and-disable-kyma-module). +* For CLI interactions: [kubectl](https://kubernetes.io/docs/tasks/tools/) v1.17 or higher. +* You know the service offering name and service plan name for the SAP BTP service you want to connect to your Kyma cluster. + To find the service and service plan names, in the SAP BTP cockpit, go to **Services**->**Service Marketplace**. Click on the service tile and find its **name** and **Plan**. + +> [!NOTE] +> You can use [SAP BTP kubectl plugin](https://github.com/SAP/sap-btp-service-operator#sap-btp-kubectl-plugin-experimental) to get the available services in your SAP BTP account by using the access credentials stored in the cluster. However, the plugin is still experimental. + +## Create a Service Instance + +### Context + +To create a service instance, use either Kyma dashboard or kubectl. + + +#### Use Kyma Dashboard + +1. In the **Namespaces** view, go to the namespace you want to work in. +2. Go to **Service Management** -> **Service Instances**. +3. Provide the required service details and create a service instance.
+ You see the status `PROVISIONED`. + +#### Use kubectl + +1. To create a ServiceInstance custom resource (CR), follow this example: + + ```yaml + kubectl create -f - < + +## Create a Service Binding + +### Context + +With a ServiceBinding custom resource (CR), your application can get access credentials for communicating with an SAP BTP service. +These access credentials are available to applications through a Secret resource generated in your cluster. + +To create a service binding, use either Kyma dashboard or kubectl. + +### Procedure + + +#### Use Kyma Dashboard + +1. In the **Namespaces** view, go to the namespace you want to work in. +2. Go to **Service Management** -> **Service Bindings**. +3. Choose your service instance name from the dropdown list and create a service binding.
+ You see the status `PROVISIONED`. + +#### Use kubectl + +1. To create a ServiceBinding CR, follow this example: + + ```yaml + kubectl create -f - < [!NOTE] + > In the **serviceInstanceName** field of the ServiceBinding, enter the name of the ServiceInstance resource you previously created. + +2. To check your service binding status, run: + + ```bash + kubectl get servicebindings {BINDING_NAME} -n {NAMESPACE} + ``` + + You see the staus `Created`. + +3. Verify the Secret is created with the name specified in the **spec.secretName** field of the ServiceBinding CR. The Secret contains access credentials that the applications need to use the service: + + ```bash + kubectl get secrets {SECRET_NAME} -n {NAMESPACE} + ``` + You see the same Secret name as in the **spec.secretName** field of the ServiceBinding CR. + + +### Results + +You can use a given service in your Kyma cluster. diff --git a/docs/user/03-30-management-of-service-instances-and-bindings.md b/docs/user/03-30-management-of-service-instances-and-bindings.md deleted file mode 100644 index e4a800a6e..000000000 --- a/docs/user/03-30-management-of-service-instances-and-bindings.md +++ /dev/null @@ -1,188 +0,0 @@ -# Management of the Service Instances and Service Bindings Lifecycle - -Use the SAP BTP Operator module to manage the lifecycle of service instances and service bindings in the Kyma environment. - -## Create a Service Instance - -1. To create an instance of an SAP BTP service, create a ServiceInstance custom resource (CR) file following this example: - - ```yaml - kubectl create -f - < [!NOTE] - > Only one parameter field per `spec` can be specified. -* **parametersFrom**: Specifies which Secret, together with the key in it, to include in the set of parameters sent to the service broker. - The key contains a `string` that represents the JSON. The **parametersFrom** field is a list that supports multiple sources referenced per `spec`. - -If you specified multiple sources in the **parameters** and **parametersFrom** fields, the final payload results from merging all of them at the top level. -If there are any duplicate properties defined at the top level, the specification is considered to be invalid. -The further processing of the ServiceInstance or ServiceBinding resource stops with the status `Error`. - -See the following example of the `spec` format in YAML: - -```yaml -spec: - ... - parameters: - name: value - parametersFrom: - - secretKeyRef: - name: {SECRET_NAME} - key: secret-parameter -``` - -See the following example of the `spec` format in JSON: - -```json -{ - "spec": { - "parameters": { - "name": "value" - }, - "parametersFrom": { - "secretKeyRef": { - "name": "{SECRET_NAME}", - "key": "secret-parameter" - } - } - } -} -``` - -See the example of a Secret with the key named **secret-parameter**: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: {SECRET_NAME} -type: Opaque -stringData: - secret-parameter: - '{ - "password": "password" - }' -``` - -See the example of the final JSON payload sent to the service broker: -```json -{ - "name": "value", - "password": "password" -} -``` - -To list multiple parameters in the Secret, separate key-value pairs with commas. See the following example: - -```yaml -secret-parameter: - '{ - "password": "password", - "key2": "value2", - "key3": "value3" - }' -``` - -## Delete Service Bindigs and Service Instances - -You can't delete service instances or service bindings created in Kyma using the SAP BTP cockpit. You can only perform these operations using Kyma dashboard or kubectl. - -> [!WARNING] -> Once you delete your service instances and service bindings, you cannot revert the operation. - -If you haven't deleted all the service instances and service bindings associated with the `sap-btp-service-operator` Secret in the `kyma-system` namespace, you can't delete your Kyma cluster from the SAP BTP cockpit. To delete the remaining service instances and service bindings, go to Kyma dashboard.
-If you have not deleted service instances and bindings connected to your expired free tier service, you can still find the service binding credentials in the SAP Service Manager instance details in the SAP BTP cockpit. Use them to delete the leftover service instances and bindings. - -### Delete Resources Using Kyma Dashboard - -> [!TIP] -> To successfully delete a service instance, first delete its service bindings. - -1. In the **Namespace** view, go to **Service Management** -> **Service Bindings**/**Service Instances**. -2. Use the trashbin icon to delete the service binding/instance. - -### Delete Resources Using kubectl - -To delete a service binding, run: - -```bash -kubectl delete servicebindings.services.cloud.sap.com {BINDING_NAME} -``` - -To delete a service instance, run: - -```bash -kubectl delete serviceinstances.services.cloud.sap.com {SERVICE_INSTANCE_NAME} -``` diff --git a/docs/user/03-40-service-binding-rotation.md b/docs/user/03-40-service-binding-rotation.md index 41c853ac7..ef49f5241 100644 --- a/docs/user/03-40-service-binding-rotation.md +++ b/docs/user/03-40-service-binding-rotation.md @@ -1,4 +1,4 @@ -# Service Binding Rotation +# Rotate Service Bindings Enhance security by automatically rotating the credentials associated with your service bindings. This process involves generating a new service binding while keeping the old credentials active for a specified period to ensure a smooth transition. @@ -15,11 +15,9 @@ To enable automatic service binding rotation, use the **credentialsRotationPolic > [!NOTE] > The `credentialsRotationPolicy` does not manage the validity or expiration of the credentials themselves. This is determined by the service you are using. -## Rotation Process - The `credentialsRotationPolicy` is evaluated periodically during a [control loop](https://kubernetes.io/docs/concepts/architecture/controller/) on every service binding update or during a complete reconciliation process. This means the actual rotation occurs in the closest upcoming reconciliation loop. -## Immediate Rotation +## Enable Immediate Rotation To trigger an immediate rotation regardless of the configured **rotationFrequency**, add the `services.cloud.sap.com/forceRotate: "true"` annotation to the ServiceBinding resource. The immediate rotation only works if automatic rotation is already enabled. @@ -42,6 +40,7 @@ spec: ## Result Rotating the service binding has the following results: + * The Secret is updated with the latest credentials. * The old credentials are kept in a newly-created Secret named `original-secret-name(variable)-guid(variable)`. This temporary Secret is kept until the configured deletion time (TTL) expires. diff --git a/docs/user/03-50-formatting-service-binding-secret.md b/docs/user/03-50-formatting-service-binding-secret.md index 92130f50b..3a6262e92 100644 --- a/docs/user/03-50-formatting-service-binding-secret.md +++ b/docs/user/03-50-formatting-service-binding-secret.md @@ -2,19 +2,20 @@ Use different attributes in your ServiceBinding resource to generate different formats of your Secret resources. -## Overview +## Context Secret resources share a common set of basic parameters that can be divided into two categories: + * Credentials returned from the service broker that allow your application to access and consume an SAP BTP service. * Attributes of the associated service instance: The details of the service instance itself. However, the Secret resources can come in various formats: + * Default key-value pairs * A JSON object * One JSON object with credentials and service information * Custom formats - ## Key-Value Pairs If you do not use any of the attributes, the generated Secret is by default in the key-value pair format, as in the following examples: @@ -121,14 +122,15 @@ See the following examples: ## Custom Formats For additional flexibility, you can model the Secret resources according to your needs. -To generate a custom-formatted Secret, use the **secretTemplate** attribute in the ServiceBinding spec. -This attribute expects a Go template as its value. For more information, see [Go Templates](https://pkg.go.dev/text/template).
+To generate a custom-formatted Secret, use the **secretTemplate** attribute in the ServiceBinding `spec`. +This attribute expects a Go template as its value. For more information, see [Go Templates](https://pkg.go.dev/text/template). + Ensure the template is in the YAML format and has the structure of a Kubernetes Secret. In the provided Secret, you can customize the `metadata` and `data` sections with the following options: -- `metadata`: labels and annotations -- `data`: customize or utilize one of the available formatting options following the instructions in the [Overview](#overview) section. +* `metadata`: labels and annotations +* `data`: customize or utilize one of the available formatting options following the instructions in the [Context](#context) section > [!NOTE] @@ -147,9 +149,7 @@ The provided templates are executed on a map with the following available attrib The following examples demonstrate the ServiceBinding and generated Secret resources: -* Service binding with customized `metadata` and `data` sections: - - In this example, you specify both `metadata` and `data` in the `secretTemplate`: +* In a service binding with customized `metadata` and `data` sections, you specify both `metadata` and `data` in the `secretTemplate`: * Service binding @@ -188,9 +188,7 @@ The following examples demonstrate the ServiceBinding and generated Secret resou PASSWORD: {CLIENT_SECRET} ``` -* Example of a binding with a customized `metadata` section and applied pre-existing formatting option for `data` with credentials as a JSON object: - - In this example, you omit `data` from the `secretTemplate` and use the `secretKey` to format your `data` instead. +* In a binding with a customized `metadata` section and applied pre-existing formatting option for `data` with credentials as a JSON object, you omit `data` from the `secretTemplate` and use the `secretKey` to format your `data` instead. * Service binding diff --git a/docs/user/03-60-pass-parameters.md b/docs/user/03-60-pass-parameters.md new file mode 100644 index 000000000..3a13edafc --- /dev/null +++ b/docs/user/03-60-pass-parameters.md @@ -0,0 +1,91 @@ +# Pass Parameters + +You can set input parameters for your resources. + +## Procedure + +To set input parameters, go to the `spec` of the ServiceInstance or ServiceBinding resource, and use both or one of the following fields: +* **parameters**: Specifies a set of properties sent to the service broker. + The specified data is passed to the service broker without any modifications - aside from converting it to the JSON format for transmission to the broker if the `spec` field is specified as a YAML file. + All valid YAML or JSON constructs are supported. + + > [!NOTE] + > Only one parameter field per `spec` can be specified. + +* **parametersFrom**: Specifies which Secret, together with the key in it, to include in the set of parameters sent to the service broker. + The key contains a `string` that represents a JSON file. The **parametersFrom** field is a list that supports multiple sources referenced per `spec`. + +If you specified multiple sources in the **parameters** and **parametersFrom** fields, the final payload results from merging all of them at the top level. + +If there are any duplicate properties defined at the top level, the specification is considered to be invalid. +The further processing of the ServiceInstance or ServiceBinding resource stops with the status `Error`. + +## Examples + +See the following examples: + +* The `spec` format in YAML: + + ```yaml + spec: + ... + parameters: + name: value + parametersFrom: + - secretKeyRef: + name: {SECRET_NAME} + key: secret-parameter + ``` + +* The `spec` format in JSON: + + ```json + { + "spec": { + "parameters": { + "name": "value" + }, + "parametersFrom": { + "secretKeyRef": { + "name": "{SECRET_NAME}", + "key": "secret-parameter" + } + } + } + } + ``` + +* A Secret with the key named **secret-parameter**: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: {SECRET_NAME} + type: Opaque + stringData: + secret-parameter: + '{ + "password": "password" + }' + ``` + +* The final JSON payload sent to the service broker: + + ```json + { + "name": "value", + "password": "password" + } + ``` + +* Multiple parameters in the Secret with key-value pairs separated with commas: + + ```yaml + secret-parameter: + '{ + "password": "password", + "key2": "value2", + "key3": "value3" + }' + ``` diff --git a/docs/user/03-70-delete-bindings-and-instances.md b/docs/user/03-70-delete-bindings-and-instances.md new file mode 100644 index 000000000..f44671257 --- /dev/null +++ b/docs/user/03-70-delete-bindings-and-instances.md @@ -0,0 +1,43 @@ +# Delete Service Bindigs and Service Instances + +Delete service bindings and service instances using Kyma dashboard or kubectl. + +## Context + +You can only delete service instances or service bindings created in Kyma using Kyma dashboard or kubectl. You can't perform these operations using the SAP BTP cockpit. + +> [!WARNING] +> Once you delete your service instances and service bindings, you cannot revert the operation. + +If you haven't deleted all the service instances and service bindings associated with the `sap-btp-service-operator` Secret in the `kyma-system` namespace, you can't delete your Kyma cluster from the SAP BTP cockpit. To delete the remaining service instances and service bindings, go to Kyma dashboard. + +If you have not deleted service instances and bindings connected to your expired free tier service, you can still find the service binding credentials in the SAP Service Manager instance details in the SAP BTP cockpit. Use them to delete the leftover service instances and bindings. + +> [!TIP] +> To successfully delete a service instance, first delete its service bindings. + +Use either Kyma dashboard or kubectl to delete a service binding or a service instance. + +## Procedure + + +#### Use Kyma Dashboard + +1. In the **Namespaces** view, go to the namespace you want to delete a service binding/instance from. +2. Go to **Service Management** -> **Service Bindings**/**Service Instances**. +3. Delete the service binding/instance. + +#### Use kubectl + +To delete a service binding, run: + +```bash +kubectl delete servicebindings.services.cloud.sap.com {BINDING_NAME} +``` + +To delete a service instance, run: + +```bash +kubectl delete serviceinstances.services.cloud.sap.com {SERVICE_INSTANCE_NAME} +``` + \ No newline at end of file diff --git a/docs/user/README.md b/docs/user/README.md index 5f6822ffc..68feeedb6 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -1,25 +1,26 @@ # SAP BTP Operator Module -Learn more about the SAP BTP Operator module. Use it to enable Service Management and consume SAP BTP services from your Kyma cluster. +Use the SAP BTP Operator module to enable service management and consume SAP BTP services from your Kyma cluster. ## What is SAP BTP Operator? -The SAP BTP Operator module provides Service Management, which allows you to consume [SAP BTP services](https://discovery-center.cloud.sap/protected/index.html#/viewServices) from your Kyma cluster using Kubernetes-native tools. -Within the SAP BTP Operator module, [BTP Manager](https://github.com/kyma-project/btp-manager) installs an open source component: the [SAP BTP service operator](https://github.com/SAP/sap-btp-service-operator/blob/main/README.md). -The SAP BTP service operator enables provisioning and managing service instances and service bindings of SAP BTP services so that your Kubernetes-native applications can access and use the services from your cluster. +The SAP BTP Operator module provides service management, which allows you to consume [SAP BTP services](https://discovery-center.cloud.sap/protected/index.html#/viewServices) from your Kyma cluster using Kubernetes-native tools. +Within the SAP BTP Operator module, [BTP Manager](https://github.com/kyma-project/btp-manager) installs the [SAP BTP service operator](https://github.com/SAP/sap-btp-service-operator/blob/main/README.md). +The SAP BTP service operator enables provisioning and managing service instances and service bindings of SAP BTP services. Consequently, your Kubernetes-native applications can access and use the services from your cluster. ## Features The SAP BTP Operator module provides the following features: -* [Credentials and access preconfiguration](03-10-preconfigured-secret.md): Your Secret is provided on Kyma runtime creation. -* [Multitenancy](03-20-multitenancy.md): You can configure multiple subaccounts in a single cluster. -* [Lifecycle management of service instances and service bindings](03-30-management-of-service-instances-and-bindings.md): You can create and delete service instances and service bindings. -* [Service binding rotation](03-40-service-binding-rotation.md): You can enhance security by automatically rotating the credentials associated with your service bindings. -* [Service binding Secret formatting](03-50-formatting-service-binding-secret.md): You can use different attributes in your ServiceBinding resource to generate different formats of your Secret resources. + +* Credentials and access preconfiguration: Your Secret is provided on Kyma runtime creation. See [Preconfigured Credentials and Access](03-10-preconfigured-secret.md). +* Multitenancy: You can configure multiple subaccounts in a single cluster. See [Working with Multiple Subaccounts](03-20-multitenancy.md). +* Lifecycle management of service instances and service bindings: You can create and delete service instances and service bindings. See [Create Service Instances and Service Bindings](03-30-create-instances-and-bindings.md) and [Delete Service Bindings and Service Instances](03-70-delete-bindings-and-instances.md). +* Service binding rotation: You can enhance security by automatically rotating the credentials associated with your service bindings. See [Rotating Service Bindings](03-40-service-binding-rotation.md). +* Service binding Secret formatting: You can use different attributes in your ServiceBinding resource to generate different formats of your Secret resources. See [Formatting Service Binding Secrets](03-50-formatting-service-binding-secret.md). ## Scope -By default, the scope of the SAP BTP Operator module is your Kyma runtime, which consumes SAP BTP services from the subaccount in which you created it. You can extend the module's scope by adding more subaccounts and consuming services from them in one cluster. The scope can range from one to multiple subaccounts depending on the number of configured Secrets. +By default, the SAP BTP Operator module consumes SAP BTP services from the subaccount in which you created it. To consume the services from multiple subaccounts in a single Kyma cluster, configure a dedicated Secret for each additional subaccount. ## Architecture @@ -27,7 +28,7 @@ The SAP BTP Operator module provides and retrieves the initial credentials that ![SAP BTP Operator architecture](../assets/module_architecture.drawio.svg) -SAP BTP Operator can have access to multiple subaccounts within your cluster depending on the number of configured Secrets. +Depending on the number of configured Secrets, SAP BTP Operator can have access to multiple subaccounts within your cluster. ![Access configuration](../assets/access_configuration.drawio.svg) @@ -41,19 +42,21 @@ SAP BTP, Kyma runtime runs on a Kubernetes cluster and wraps the SAP BTP Operato BTP Manager is an operator based on the [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) framework. It extends the Kubernetes API by providing the [BtpOperator Custom Resource Definition (CRD)](https://github.com/kyma-project/btp-manager/blob/main/config/crd/bases/operator.kyma-project.io_btpoperators.yaml). BTP Manager performs the following operations: -* Manages the lifecycle of the SAP BTP service operator, including provisioning of the latest version, updating, and deprovisioning -* Configures the SAP BTP service operator + +* Manages the lifecycle of the SAP BTP service operator, including provisioning of the latest version, updating, and deprovisioning. +* Configures the SAP BTP service operator. ### SAP BTP Service Operator -The SAP BTP service operator is an open-source component that connects SAP BTP services to your cluster and manages them using Kubernetes-native tools. It is responsible for communicating with SAP Service Manager. The operator's resources (service instances and service bindings) come from the `services.cloud.sap.com` API group. +The SAP BTP service operator is an open-source component that allows you to connect SAP BTP services to your cluster and manage them using Kubernetes-native tools. It is responsible for communicating with SAP Service Manager. The operator's resources (service instances and service bindings) come from the `services.cloud.sap.com` API group. ### SAP Service Manager [SAP Service Manager](https://help.sap.com/docs/service-manager/sap-service-manager/sap-service-manager?locale=en-US) is the central registry for service brokers and platforms in SAP BTP, which enables you to: -* Consume platform services in any connected runtime environment -* Track the creation and management of service instances -* Share services and service instances between different runtimes + +* Consume platform services in any connected runtime environment. +* Track the creation and management of service instances. +* Share services and service instances between different runtimes. SAP Service Manager uses [Open Service Broker API](https://www.openservicebrokerapi.org/) (OSB API) to communicate with service brokers. @@ -66,9 +69,10 @@ Service brokers manage the lifecycle of services. SAP Service Manager interacts The `btpoperators.operator.kyma-project.io` Custom Resource Definition (CRD) describes the kind and the data format that SAP BTP Operator uses to configure resources. See the documentation related to the BtpOperator custom resource (CR): -* [SAP BTP Operator](./resources/02-10-sap-btp-operator-cr.md) -* [Service instance](./resources/02-20-service-instance-cr.md) -* [Service binding](./resources/02-30-service-binding-cr.md) + +* [SAP BTP Operator Custom Resource](./resources/02-10-sap-btp-operator-cr.md) +* [Service Instance Custom Resource](./resources/02-20-service-instance-cr.md) +* [Service Binding Custom Resource](./resources/02-30-service-binding-cr.md) ## Resource Consumption diff --git a/docs/user/_sidebar.md b/docs/user/_sidebar.md index c16e572bc..2c10d9a93 100644 --- a/docs/user/_sidebar.md +++ b/docs/user/_sidebar.md @@ -4,12 +4,14 @@ * [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) -* [Management of the Service Instances and Service Bindings Lifecycle](/btp-manager/user/03-30-management-of-service-instances-and-bindings.md) +* [Create Service Instances and Service Bindings](/btp-manager/user/03-30-create-services-and-bindings.md) * [Working with Multiple Subaccounts](/btp-manager/user/03-20-multitenancy.md) * [Instance-Level Mapping](/btp-manager/user/03-21-instance-level-mapping.md) * [Namespace-Level Mapping](/btp-manager/user/03-22-namespace-level-mapping.md) -* [Service Binding Rotation](/btp-manager/user/03-40-service-binding-rotation.md) +* [Pass Parameters](/btp-manager/user/03-60-pass-parameters.md) +* [Rotate Service Bindings](/btp-manager/user/03-40-service-binding-rotation.md) * [Formats of Service Binding Secrets](/btp-manager/user/03-50-formatting-service-binding-secret.md) +* [Delete Service Bindigs and Service Instances](/btp-manager/user/03-70-delete-bindings-and-instances.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)