orkungedik/SAP-basis-dataset huggingface dataset:
## 4.3.1.2.1 Using a Short Host Name
Learn how to expose a Service instance using a short host name instead of the full domain name.
## Prerequisites
- You have the Istio and API Gateway modules added. See Adding and Deleting a Kyma Module [page 3157].
- You have installed curl and kubectl . Y ou have configured kubectl to communicate with your Kyma runtime instance. See Access a Kyma Instance Using kubectl [page 2018].
- You have a deployed workload.
##  Note
To expose a workload using APIRule in version v2 , the workload must be a part of the Istio service mesh. See Enabling Istio Sidecar Proxy Injection [page 1783].
- You have set up your custom domain . Alternatively, you can use the default domain of your Kyma cluster and the default Gateway kyma-system/kyma-gateway .
##  Note
Because the default Kyma domain is a wildcard domain, which uses a simple TLS Gateway, it is recommended that you set up your custom domain for use in a production environment.
```
 Tip To learn what the default domain of your Kyma cluster is, run the following command: kubectl get gateway -n kyma-system kyma-gateway -o jsonpath='{.spec.servers[0].hosts}
```
## Context
Using a short host makes it simpler to apply an APIRule custom resource (CR) because the domain name is automatically retrieved from the referenced Gateway, and you don't have to manually set it in each APIRule. This might be particularly useful when reconfiguring resources in a new cluster, as it reduces the risk of errors and streamlines the process.
## Procedure
1. To expose your workload using a short host, create an APIRule CR and define only a subdomain in the hosts field. See the following example:
2. Send a GET request to the exposed workload:
```
cat <<EOF | kubectl apply -f apiVersion: gateway.kyma-project.io/v2alpha1 kind: APIRule metadata: name: {APIRULE_NAME} namespace: {APIRULE_NAMESPACE} spec: hosts: - {SUBDOMAIN} service: name: {SERVICE_NAME} namespace: {SERVICE_NAMESPACE} port: {SERVICE_PORT} gateway: {NAMESPACE/GATEWAY} rules: - path: /* methods: ["GET"] noAuth: true - path: /post methods: ["POST"] noAuth: true EOF
```
```
curl -ik -X GET https://{SUBDOMAIN}.{DOMAIN_NAME}/ip
```
If successful, the call returns the 200 OK response code.
3. Send a POST request to the exposed workload:
```
curl -ik -X POST https://{SUBDOMAIN}.{DOMAIN_NAME}/post -d "test data" If successful, the call returns the 200 OK response code.
```
## 4.3.1.2.4 APIRule Migration
APIRule custom resource (CR) v1beta1 has been deprecated and scheduled for deletion. You must migrate all your APIRule CRs to version v2 . Learn more about the timeline and see how to perform the migration.
## How to Migrate APIRules to Version v2
To migrate to version v2 , follow the steps:
1. To identify which APIRules must be migrated, run the following command:
2. To retrieve the complete spec with the rules field of an APIRule in version v1beta1 , see Retrieving the Complete spec of an APIRule in Version v1beta1 [page 1854].
3. To migrate an APIRule from version v1beta1 to version v2 , follow the relevant guide:
- Migrating APIRule v1beta1 of Type jwt to Version v2 [page 1857]
- Migrating APIRule v1beta1 of Type noop, allow, or no\_auth to Version v2 [page 1861]
- Migrating APIRule v1beta1 of type oauth2\_introspection to version v2 [page 1865]
```
kubectl get apirules.gateway.kyma-project.io -A-o json | jq '.items[] | select(.metadata.annotations["gateway.kyma-project.io/original-version"] == "v1beta1") | {namespace: .metadata.namespace, name: .metadata.name}'
```
For more information about APIRule v2 , see also APIRule v2 Custom Resource and Changes Introduced in APIRule v2 [page 1851].
## APIRule v1beta1 Migration Timeline
The following timeline outlines the steps we will take to phase out version v1beta1 :
1. Kyma dashboard won't display APIRule CRs in version v1beta1. All APIRules v1beta1 will be fully operational from the command line, and you will still be able to manage them using kubectl. This change will not affect any pipelines that manage APIRules using Kubernetes utilities such as kubectl or helm.
- Fast channel release date: August 18, 2025
- Regular channel release date: September 1, 2025
2. You won't be able to create APIRule CRs v1beta1 in new clusters. In existing clusters, you will still be able to create and modify APIRule CRs v1beta1 .
- Fast channel release date: End of October, 2025
- Regular channel release date: Mid-November, 2025
3. You won't be able to create APIRule CRs v1beta1 in new and existing clusters, modify existing APIRule CRs v1beta1 , or delete them. All APIRule v1beta1 configurations set up prior to this restriction will remain active and continue to function as expected. The API Gateway module will manage and reconcile resources based on the existing APIRule settings.
- Fast channel release date: Mid-November, 2025
- Regular channel release date: End of the year 2025
<!-- image -->
## 4.3.1.2.5 Troubleshooting for the API Gateway Module
Troubleshoot problems related to the API Gateway module.
Issues when Creating APIRule CRs [page 1870]
Certificate Management: Issuer Not Created [page 1874]
Kyma Gateway Not Reachable [page 1874]
401 Unauthorized or 403 Forbidden [page 1875]
Connection Refused or Timeout [page 1875]
Blocked In-Cluster Communication [page 1876]
APIRule v2 Doesn't Contain Rules [page 1878]
APIRule v2alpha1 Doesn't Contain Rules [page 1879]
APIRule v2 Contains a Changed Status Schema [page 1880]
APIRules Are Missing from Kyma Dashboard [page 1881]
If you created APIRules using version v1beta1 , and you have not yet migrated them to version v2 , they are not displayed in Kyma dashboard's API Rules view. T o display APIRules in Kyma dashboard, you must migrate them to version v2 .
## 4.3.1.2.5.2  Certificate Management: Issuer Not Created
## Symptom
When you try to create an Issuer custom resource (CR) using cert.gardener.cloud/v1alpha1 , the resource is not created. There are no logs in the cert-management controller.
## Cause
The cert-management controller does not watch the namespace in which you created the Issuesr CR. By default, cert-management watches the default namespace for all Issuer CRs.
## Solution
To make sure that you created the Issuer CR in the default namespace, run: kubectl get issuers -A . If you want to create the Issuer CR in a different namespace, adjust cert-management settings during the installation.
## 4.3.1.2.5.3  Kyma Gateway Not Reachable
## Symptom
You cannot access Services or Functions exposed using APIRules. Kyma Gateway refuses the connection.
## Cause
The issue occurs when the default kyma-gateway is either renamed or duplicated. Once you have multiple Gateway resources pointing to the same host, the Gateway CR created first takes precedence over the others.
## Solution
Having two Gateway resources pointing to the same host is not recommended. To resolve the issue, make sure the default kyma-gateway exists and is not renamed or duplicated. If there are multiple Gateway resources
pointing to the same host, delete the duplicated Gateway. To delete the Gateway resource, run: kubectl -n kyma-system delete gateway {DUPLICATED\_GATEWAY\_NAME} .
## 4.3.1.2.5.4  401 Unauthorized or 403 Forbidden
## Symptom
When you try to reach a service, you get 401 Unauthorized or 403 Forbidden in response.
## Cause
The error 401 Unauthorized occurs when you try to access a Service that requires authentication, and the appropriate credentials were not provided or were incorrect. You get the error 403 Forbidden when you try to access a Service or perform an action for which you lack permission.
## Solution
Make sure that you are using an active JSON Web Token (JWT) with proper scopes.
1. Decode the JWT.
2. Check the validity and scopes of the JWT:
3. Generate a new JWT if needed.
```
{ "sub": ********, "scp": "test", "aud": ********, "iss": ******, "exp": 1697120462, "iat": ******, "jti": ******, }
```
## 4.3.1.2.5.5  Connection Refused or Timeout
## Symptom
After you have finished all the steps required to set up your custom domain, you receive the connection refused or connection timeout error when you try to expose a Service. It shows up when you call the Service endpoint by sending a GET request. The error looks as follows:
```
curl: (7) Failed to connect to httpbin.mydomain.com port 443: Connection refused
```
## Cause
DNS resolves to an incorrect IP address.
## Solution
Check if the IP address provided as the value of the spec.targets parameter of the DNSEntry custom resource is the IP address of the Ingress Gateway you are using. To check the Ingress Gateway IP, run:
```
kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```
In addition, ensure that your OS resolves the target host name to the same Ingress Gateway IP address. Run:
```
host {YOUR_SUBDOMAIN}
```
##  Note
YOUR\_SUBDOMAIN specifies the name of your subdomain, for example, httpbin.mydomain.com .
## 4.3.1.2.5.7  APIRule v2 Doesn't Contain Rules
## Symptom
An APIRule custom resource (CR) does not contain the rules field, for example:
```
kubectl get apirules.gateway.kyma-project.io -n $NAMESPACE $APIRULE_NAME -o yaml apiVersion: gateway.kyma-project.io/v2
```
```
kind: APIRule metadata: name: httpbin namespace: test spec: gateway: kyma-system/kyma-gateway hosts: - httpbin.local.kyma.dev service: name: httpbin namespace: test port: 8000 status: lastProcessedTime: "2025-04-25T11:16:11Z" state: Ready
```
## Cause
The APIRule was originally created using version v1beta1 , and you haven't yet migrated it to version v2 . Since the latest stable version of the APIRule in the Kubernetes API is now v2 , running the kubectl get command without specifying a version of APIRule assumes version v2 .
To display the resource in version v2 , a conversion from v1beta1 to v2 is performed. This conversion only affects the displayed resource's textual format and does not modify the resource in the cluster. If the full conversion is possible, the rules field is presented in the output. However, if the conversion cannot be completed, the rules are missing, and the original rules are stored in the resource's annotations.
## Solution
Specify explicitly v1beta1 version when requesting the APIRule resource:
kubectl get apirules.v1beta1.gateway.kyma-project.io -n $NAMESPACE $APIRULE\_NAME -o yaml
## 4.3.1.2.5.8  APIRule v2alpha1 Doesn't Contain Rules
## Symptom
An APIRule custom resource (CR) does not contain the rules field, for example:
```
kubectl get apirules.v2alpha1.gateway.kyma-project.io -n $NAMESPACE $APIRULE_NAME -o yaml apiVersion: gateway.kyma-project.io/v2alpha1 kind: APIRule metadata: name: httpbin namespace: test
```
```
spec: gateway: kyma-system/kyma-gateway hosts: - httpbin.local.kyma.dev service: name: httpbin namespace: test port: 8000 status: lastProcessedTime: "2025-04-25T11:16:11Z" state: Ready
```
## Cause
The APIRule was originally created using version v1beta1 , and you haven't yet migrated it to version v2 .
To display the resource in version v2alpha1 , a conversion from v1beta1 to v2alpha1 is performed. This conversion only affects the displayed resource's textual format and does not modify the resource in the cluster. If the full conversion is possible, the rules field is presented in the output. However, if the conversion cannot be completed, the rules are missing, and the original rules are stored in the resource's annotations.
## Solution
Specify explicitly v1beta1 version when requesting the APIRule resource:
```
kubectl get apirules.v1beta1.gateway.kyma-project.io -n $NAMESPACE $APIRULE_NAME -o yaml
```
## 4.3.1.2.5.9  APIRule v2 Contains a Changed Status Schema
## Symptom
There is a changed status schema in an APIRule custom resource (CR), for example:
```
kubectl get apirules.gateway.kyma-project.io -n $NAMESPACE $APIRULE_NAME -o yaml
```
```
... status: lastProcessedTime: "2025-04-25T11:16v:11Z" state: Ready
```
## Cause
The schema of the status.state field in the v2 APIRule CR introduces a unified approach, similar to the one used in the API Gateway CR. The possible states of the status.state field are Ready , Warning , Error , Processing , or Deleting .
## Solution
To get the APIRule in its original version, run:
kubectl get apirules.v1beta1.gateway.kyma-project.io -n $NAMESPACE $APIRULE\_NAME -o yaml
You get an output similar to this one:
```
... status: APIRuleStatus: code: OK accessRuleStatus: code: OK lastProcessedTime: "2025-04-25T11:16:11Z" observedGeneration: 1 virtualServiceStatus: code: OK
```
## 4.3.1.2.5.10  APIRules Are Missing from Kyma Dashboard
If you created APIRules using version v1beta1 , and you have not yet migrated them to version v2 , they are not displayed in Kyma dashboard's API Rules view. T o display APIRules in Kyma dashboard, you must migrate them to version v2 .
## Symptom
Kyma dashboard's API Rules view does not display APIRules created in version v1beta1 . T o check if the APIRules are present in the cluster, run the following command:
```
kubectl get apirules.v2.gateway.kyma-project.io -A
```
This command lists all APIRules available in your Kyma cluster, regardless of their original version. To get a specific APIRule and check the version in which it was created, run the following command:
```
kubectl get apirules.v2.gateway.kyma-project.io -n $NAMESPACE $APIRULE_NAME -o yaml
```
If the APIRule was created using version v1beta1 , the output contains the annotation gateway.kymaproject.io/original-version: v1beta1 .
See the following example:
```
apiVersion: gateway.kyma-project.io/v2 kind: APIRule metadata: annotations: gateway.kyma-project.io/original-version: v1beta1 name: httpbin namespace: test spec: gateway: kyma-system/kyma-gateway hosts: - httpbin.local.kyma.dev service: name: httpbin namespace: test port: 8000 status: lastProcessedTime: "2025-04-25T11:16:11Z" state: Warning
```
## Cause
APIRules that are not displayed in Kyma dashboard were originally created using version v1beta1 , and you haven't yet migrated them to version v2 . The APIRule v1beta1 API is no longer available via Kyma dashboard.
## Solution
To make sure that support for your APIRules is maintained, you must migrate them to version v2 . T o learn how to do this, see APIRule Migration [page 1850].
## 4.3.1.2.6 Default Configuration and Limitations of the API Gateway Module
## APIRule Controller Limitations
APIRule Controller relies on Istio and Ory custom resources (CRs) to provide routing capabilities. In terms of persistence, the controller depends only on APIRules stored in the Kubernetes cluster. In terms of the resource configuration, the following requirements are set on APIGateway Controller:
- CPU Requests: 10 m
- CPU Limits: 100 m
- Memory Requests: 64 Mi
- Memory Limits: 128 Mi
You can create an unlimited number of APIRule CRs.
## Ory Resources' Configuration
The configuration of Ory resources depends on the cluster capabilities. If your cluster has fewer than 5 total virtual CPU cores or its total memory capacity is less than 10 gigabytes, the default setup for resources is lighter. If your cluster exceeds both of these thresholds, the higher resource configuration is applied.
The default configuration for larger clusters includes the following settings for the Ory components' resources:
Ory Resources' Configuration
| Component          | CPU Requests   | CPU Limits   | Memory Requests   | Memory Limits   |
|--------------------|----------------|--------------|-------------------|-----------------|
| Oathkeeper         | 100m           | 10000m       | 64 Mi             | 512 Mi          |
| Oathkeeper Maester | 10m            | 400m         | 32 Mi             | 1 Gi            |
The default configuration for smaller clusters includes the following settings for the Ory components' resources:
Ory Resources' Configuration
| Component          | CPU Requests   | CPU Limits   | Memory Requests   | Memory Limits   |
|--------------------|----------------|--------------|-------------------|-----------------|
| Oathkeeper         | 10m            | 100m         | 64 Mi             | 128 Mi          |
| Oathkeeper Maester | 10m            | 100m         | 20 Mi             | 50 Mi           |
## Autoscaling Configuration
The default configuration in terms of autoscaling of Ory components is as follows:
Ory Resources' Configuration
| Component          |   Min Replicas |   Max Replicas |
|--------------------|----------------|----------------|
| Oathkeeper         |              3 |             10 |
| Oathkeeper Maester |              3 |             10 |
Oathkeeper Maester is a separate container running in the same Pod as Oathkeeper. Because of that, the autoscaling configuration of the Oathkeeper and Oathkeeper Master components is similar. The autoscaling configuration is based on CPU utilization, with HorizontalPodAutoscaler set up for 80% average CPU request utilization.
## 4.3.1.3.2 Customizing the Default Credentials and Access
You can customize the sap-btp-manager Secret and manage your own default configuration of the SAP BTP Operator module.
## Prerequisites
You have the SAP BTP Operator module added. See Adding and Deleting a Kyma Module [page 3157].
## Context
When you create SAP BTP, Kyma runtime, the sap-btp-manager Secret is automatically created as the default Secret managing the SAP BTP Operator's resources. Because of Kyma's automatic reconciliation, any changes to the Secret are reverted, and the previous settings are restored within 24 hours. See Preconfigured Credentials and Access [page 1887].
To customize the sap-btp-manager Secret and prevent your changes from being reverted, you must stop the Secret's reconciliation. With the customized Secret, you can perform the following actions:
- Manage your own default configuration of SAP BTP Operator
- Migrate the service instances you created outside of the Kyma environment to your Kyma cluster
## Procedure
To customize the sap-btp-manager Secret, modify the credentials in the following way:
- Label the Secret with kyma-project.io/skip-reconciliation: 'true' .
- Provide the following credentials from your SAP Service Manager instance: clientid , clientsecret , sm\_url , and tokenurl .
- Optionally, provide your cluster\_id . Otherwise, the default generated one is used.
- Optionally, add the credentials\_namespace parameter and provide the name of your existing custom namespace for Secrets with credentials to communicate with the SAP Service Manager.
##  Note
Setting the credentials\_namespace parameter changes the values of MANAGEMENT\_NAMESPACE and RELEASE\_NAMESPACE keys in the sap-btp-operator-config ConfigMap. The custom namespace replaces the default kyma-system namespace for sap-btp-service-operator and sap-btp-operator-clusterid Secrets. BTP Manager deletes the Secrets from the default kymasystem namespace and creates them in the custom namespace.
See the following example:
apiVersion: v1
```
kind: Secret type: Opaque metadata: name: sap-btp-manager namespace: kyma-system labels: app.kubernetes.io/managed-by: kcp-kyma-environment-broker kyma-project.io/skip-reconciliation: "true" data: clientid: {CLIENT_ID} clientsecret: {CLIENT_SECRET} sm_url: {SM_URL} tokenurl: {AUTH_URL} cluster_id: {CLUSTER_ID} credentials_namespace: {CREDENTIALS_NAMESPACE}
```
## Results
Your customized sap-btp-manager Secret is now the default Secret of the SAP BTP Operator module. It generates the SAP BTP service operator's resources, as shown in the following diagram:
<!-- image -->
The reconciliation of the Secret stops and your changes are not reverted.
##  Caution
If you delete the customized sap-btp-manager Secret or remove the kyma-project.io/skipreconciliation: 'true' label from it, the reconciliation starts again, and the preconfigured default sap-btp-manager Secret is recreated for your Kyma instance within 24 hours. See Preconfigured Credentials and Access [page 1887].
## 4.3.1.3.3 Creating 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
- You have the SAP BTP Operator module added. For instructions on adding modules, see Adding and Deleting a Kyma Module [page 3157].
- For CLI interactions: kubectl configured to communicate with your Kyma instance. See Access a Kyma Instance Using kubectl [page 2018].
- •
- For an enterprise account, you have added quotas to the services you purchased in your subaccount. Otherwise, only default free-of-charge services are listed in the service marketplace. Quotas are automatically assigned to the resources available in trial accounts. For more information, see Configure Entitlements and Quotas for Subaccounts.
- You know the service offering name and service plan name for the SAP BTP service you want to connect to your Kyma cluster.
 Tip
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 .
## 4.3.1.3.3.1  Creating a Service Instance
To create a service instance, use either Kyma dashboard or kubectl.
## Use Kyma Dashboard
Kyma dashboard is a web-based UI providing a graphical overview of your cluster and all its resources. To access Kyma dashboard, use the link available in the Kyma Environment section of your subaccount Overview .
## Procedure
1. In the navigation area, choose Namespaces , and go to the namespace you want to work in.
2. Go to Service Management Service Instances , and choose Create .
3. Provide the required service details in Form . Alternatively, you can switch to the YAML tab, and edit or upload your file.
4. Choose Create .
You see the status PROVISIONED .
## Use kubectl
## Procedure
1. To create a ServiceInstance custom resource (CR), replace the placeholders and run the following command:
2. To check the service's status in your cluster, run:
```
kubectl create -f - <<EOF apiVersion: services.cloud.sap.com/v1 kind: ServiceInstance metadata: name: {SERVICE_INSTANCE_NAME} namespace: {NAMESPACE} spec: servicePlanName: {SERVICE_PLAN_NAME} externalName: {SERVICE_INSTANCE_NAME} parameters: key1: val1 key2: val2
```
```
serviceOfferingName: {SERVICE_OFFERING_NAME} EOF
```
```
kubectl get serviceinstances.services.cloud.sap.com {SERVICE_INSTANCE_NAME} -n {NAMESPACE}
```
You get an output similar to this one:
```
NAME                      OFFERING PLAN                     STATUS    AGE {SERVICE_INSTANCE_NAME}   {SERVICE_OFFERING_NAME} {SERVICE_PLAN_NAME}      Created   44s
```
## 4.3.1.3.3.2  Creating a Service Binding
To create a service binding, use either Kyma dashboard or kubectl.
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.
## Use Kyma Dashboard
Kyma dashboard is a web-based UI providing a graphical overview of your cluster and all its resources. To access Kyma dashboard, use the link available in the Kyma Environment section of your subaccount Overview .
## Procedure
1. In the navigation area, choose Namespaces , and go to the namespace you want to work in.
2. Go to Service Management Service Bindings , and choose Create .
3. Provide the required details, and choose your service instance name from the dropdown list. Alternatively, you can provide the required details by switching from the Form to YAML tab, and editing or uploading your file.
4. Choose Create .
You see the status PROVISIONED .
## Use kubectl
## Procedure
1. To create a ServiceBinding CR, replace the placeholders and run the following command:
```
kubectl create -f - <<EOF apiVersion: services.cloud.sap.com/v1 kind: ServiceBinding metadata: name: {BINDING_NAME} spec: serviceInstanceName: {SERVICE_INSTANCE_NAME} externalName: {EXTERNAL_NAME} secretName: {SECRET_NAME} parameters: key1: val1 key2: val2 EOF
```
##  Remember
In the serviceInstanceName field of the service binding, enter the name of the ServiceInstance resource you previously created.
2. To check your service binding status, run:
```
kubectl get servicebindings {BINDING_NAME} -n {NAMESPACE}
```
You see the status 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. Run:
```
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.
## 4.3.1.3.4 Updating Service Instances
Use Kyma dashboard or kubectl to update service instances.
## Prerequisites
- You have the SAP BTP Operator module added. For instructions on adding modules, see Adding and Deleting a Kyma Module [page 3157].
- For CLI interactions: kubectl configured to communicate with your Kyma instance. See Access a Kyma Instance Using kubectl [page 2018].
## Context
You are using a service instance in the Kyma environment and want to update the service's plan or other service-specific parameters.
##  Note
You can only update service instances in Kyma using Kyma dashboard or kubectl. You can't perform the operation using the SAP BTP cockpit.
## Procedure
- To update a service instance, use either Kyma dashboard or kubectl. Kyma dashboard is a web-based UI providing a graphical overview of your cluster and all its resources. To access Kyma dashboard, use the link in the Kyma Environment section of your subaccount Overview .
- Use Kyma dashboard.
- a. In the navigation area, choose Namespaces , and go to the namespace with the service instance you want to update.
- b. Go to Service Management Service Instances , and choose the service instance from the list.
- c. Choose Edit .
- d. Update the required service details in Form and save your changes. Alternatively, you can switch to the YAML tab to edit or upload your file, and save your changes.
You see the message confirming the service instance update.
- Use kubectl.
- a. To update a ServiceInstance custom resource (CR), replace the placeholders with the following:
- The name of the service instance you want to update
- The namespace in which the service instance resides
- The name of the service offering you are using
- The name of the service plan associated with the service offering
- Updated or new parameters in the parameters section
Then, run:
```
kubectl apply -f - <<EOF apiVersion: services.cloud.sap.com/v1 kind: ServiceInstance metadata: name: {SERVICE_INSTANCE_NAME} namespace: {NAMESPACE} spec: serviceOfferingName: {SERVICE_OFFERING_NAME} servicePlanName: {SERVICE_PLAN_NAME} externalName: {SERVICE_INSTANCE_NAME} parameters: key1: val1 key2: val2 EOF
```
- b. To check the service's status in your cluster, run:
```
kubectl get serviceinstances.services.cloud.sap.com
```
```
{SERVICE_INSTANCE_NAME} -n {NAMESPACE}
```
You get an output similar to this one:
```
NAME                      OFFERING                  PLAN STATUS    AGE {SERVICE_INSTANCE_NAME}   {SERVICE_OFFERING_NAME}   {SERVICE_PLAN_NAME} UPDATED   30m27s
```
## 4.3.1.3.5 Deleting Service Bindings and Service Instances
Delete service bindings and service instances using Kyma dashboard or kubectl.
## Prerequisites
- You have the SAP BTP Operator module added. For instructions on adding modules, see Adding and Deleting a Kyma Module [page 3157].
- For CLI interactions: kubectl configured to communicate with your Kyma instance. See Access a Kyma Instance Using kubectl [page 2018].
## 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. To delete a service instance, first delete its service bindings.
##  Caution
Once you delete your service instances and service bindings, you cannot revert the operation.
## Procedure
- Use either Kyma dashboard or kubectl to delete a service binding or a service instance. Kyma dashboard is a web-based UI providing a graphical overview of your cluster and all its resources. To access Kyma dashboard, use the link available in the Kyma Environment section of your subaccount Overview .
- Use Kyma dashboard
- a. In the navigation area, choose Namespaces , and go to the namespace you want to delete a service binding/instance from.
- b. Go to Service Management , and then to Service Bindings or Service Instances .
- c. Choose the service binding/instance and delete it.
- Use kubectl
- To delete a service binding, run:
kubectl delete servicebindings.services.cloud.sap.com {BINDING\_NAME}
- To delete a service instance, run:
kubectl delete serviceinstances.services.cloud.sap.com {SERVICE\_INSTANCE\_NAME}
## 4.3.1.3.7 Working with Multiple Subaccounts
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 [page 1887]. 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 [page 1905]: Connect namespaces to separate subaccounts by configuring dedicated credentials for each namespace.
- Instance-level mapping [page 1902]: 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.
## 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
<!-- image -->
## Procedure
- To connect a namespace to a specific subaccount, see Namespace-Level Mapping [page 1905].
- To deploy service instances belonging to different subaccounts within the same namespace, see InstanceLevel Mapping [page 1902].
## 4.3.1.3.7.2  Namespace-Level Mapping
You can map a Kubernetes namespace to an SAP Service Manager instance in a given subaccount. The Service Manager instance is then used to provision all service instances in that namespace.
## Prerequisites
- A subaccount in the SAP BTP cockpit.
- You have the SAP BTP Operator module added. For instructions on adding modules, see Adding and Deleting a Kyma Module [page 3157].
- For CLI interactions: kubectl configured to communicate with your Kyma instance. See Access a Kyma Instance Using kubectl [page 2018].
## Context
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.
## Creating a Namespace-Based Secret
## Procedure
1. In the SAP BTP cockpit, create a new SAP Service Manager service instance with the serviceoperator-access plan. See Creating Instances in Other Environments.
2. Create a service binding to the SAP Service Manager service instance you have created. See Creating Service Bindings in Other Environments.
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, call 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:
curl https://raw.githubusercontent.com/kyma-project/btp-manager/main/hack/ create-secret-file.sh | bash -s operator {NAMESPACE\_NAME}-sap-btp-serviceoperator
The expected result is the btp-access-credentials-secret.yaml file created in your working directory:
```
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 create the Secret, run:
kubectl create -f ./btp-access-credentials-secret.yaml
You see the status Created .
## Creating a Service Instance with a Namespace-Based Secret
## Procedure
1. To create a service instance with a namespace-based Secret, follow the instructions in Creating Service Instances and Service Bindings [page 1892].
2. To verify that 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
Working with Multiple Subaccounts [page 1901] Instance-Level Mapping [page 1902]
## 4.3.1.3.8 Passing 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 one or all 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 JSON for transmission to the broker if the spec field is specified as YAML. All valid YAML or JSON constructs are supported.
- 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 . The ServiceInstance resource can specify multiple related Secrets.
- watchParametersFromChanges : Use this field together with parametersFrom . This field is only relevant for ServiceInstance resources because you cannot update ServiceBinding resources. Set it to true to trigger an automatic update of the ServiceInstance resource with the changes to the Secret values listed in parametersFrom . By default, it is set to false .
If you specify multiple sources in the parameters and parametersFrom fields, the final payload merges all of them at the top level.
To avoid errors, do not use the same top-level parameter name in multiple sources in the parameters and parametersFrom fields. Otherwise, the specification is invalid, and further processing of the ServiceInstance or ServiceBinding resources stops with the status Error .
## Examples
See the following examples:
- The spec format in YAML:
```
spec: ... parameters: name: value parametersFrom:
```
```
- secretKeyRef:
```
```
name: {SECRET_NAME} key: secret-parameter watchParametersFromChanges: true
```
- The spec format in JSON:
- A Secret with the key named secret-parameter :
- The final JSON payload sent to the service broker:
- Multiple parameters in the Secret with key-value pairs separated with commas:
```
{ "spec": { "parameters": { "name": "value" }, "parametersFrom": { "secretKeyRef": { "name": "{SECRET_NAME}", "key": "secret-parameter" } } "watchParametersFromChanges": true } }
```
```
"password": "password"
```
```
apiVersion: v1 kind: Secret metadata: name: {SECRET_NAME} type: Opaque stringData: secret-parameter: '{ }'
```
```
"password": "password"
```
```
{ "name": "value", }
```
```
secret-parameter: "password": "password",
```
```
'{ "key2": "value2", "key3": "value3" }'
```
## 4.3.1.3.11  Troubleshooting for the SAP BTP Operator Module
Troubleshoot problems related to the SAP BTP Operator module.
You Cannot Delete Leftover Service Instances and Bindings [page 1914]
Resource CR Missing from the Cluster [page 1916]
## 4.3.1.3.11.1  Y ou Cannot Delete Leftover Service Instances and Bindings
## Symptom
After your Kyma cluster has become unavailable, some orphaned service instances and service bindings are still present in the SAP Business Technology Platform (BTP).
## Cause
You cannot access your Kyma cluster where the service instances and bindings were created. Without access to the cluster, you cannot use standard deletion methods.
## Solution
##  Caution
This cleanup procedure deletes all service instances and bindings associated with the inaccessible cluster.
1. To access the SAP Service Manager API, perform the following actions:
1. In the SAP BTP cockpit, create an SAP Service Manager service instance with the subaccount-admin plan and its service binding. The service-operator-access plan does not have the necessary access level for performing the cleanup operation. See Creating Instances in Other Environments and Creating Service Bindings in Other Environments.
2. To get an access token, run the following command. Replace the placeholders with the url , clientid , and clientsecret from the service binding you have created.
2. To prepare the DELETE request, identify the following parameters:
- platformID - the ID of the Service Manager instance with the service-operator-access plan.
- clusterID - the ID of your cluster. T o get it , in the SAP BTP cockpit, go to Services Instances and Subscriptions . In the Instances section, copy the cluster ID from the Scope column in the row that provides information about the service instance(s) you want to delete.
3. Send the following request:
4. Monitor the response. You can get one of the following options:
- 202 Accepted - the request is accepted for processing.
- 404 Resource Not Found - platform or cluster not found.
- 429 Too Many Requests - the rate limit exceeded.
5. For the operation status, review the following headers:
- Location - the path provided to monitor the status of the operation. For more information about operations, see Service Manager operation API .
- Retry\_After - indicates the time in seconds after which you can retry the request after hitting rate limits.
```
curl '{url}/oauth/token' -X POST \ -H 'Accept: application/json' \ -d 'grant_type=client_credentials&client_id={clientid}&client_secret={clientse cret}'
```
```
curl -X DELETE '{sm_url}v1/platforms/{platformID}/clusters/{clusterID}' \ -H 'Authorization: Bearer {ACCESS_TOKEN}'
```
## 4.3.1.3.11.2  Resource CR Missing from the Cluster
## Symptom
Your service instance or binding is visible in SAP Business Technology Platform (BTP), but its corresponding custom resource (CR) is missing from your Kyma cluster.
## Cause
The CR representing an SAP BTP service instance or service binding is absent from the Kyma cluster. This happens if the CR was accidentally deleted or if there are issues preventing its synchronization or visibility in the cluster. While the resource still exists, the connection to your Kyma cluster is broken due to the absence of the CR.
## Solution
To address this issue, you can manually recreate the service instance CR or service binding CR using details from SAP BTP to restore the connection with the existing SAP BTP resource. For successful reconnection, ensure that the new CR matches the name, resides in the same namespace, and is linked to the same cluster ID as the original CR. Since the SAP BTP resource maintains its configuration, matching these attributes allows the new CR to reconnect to the existing SAP BTP resource without provisioning a new one.
To restore the CR, follow these steps:
1. Retrieve the following CR details from the service instance or binding:
- The CR name
- The name of the namespace where the CR should reside
2. Create your YAML manifest for the CR, including the exact name and namespace you retrieved from the SAP BTP service instance or binding.
3. To recreate the CR in your Kyma cluster, run:
4. To verify recreation of the CR in your Kyma cluster, replace the placeholders and run:
```
kubectl apply -f {YAML_MANIFEST}
```
kubectl get serviceinstances.services.cloud.sap.com {SERVICE\_INSTANCE\_NAME} -n {NAMESPACE}
Or kubectl get servicebindings.services.cloud.sap.com {BINDING\_NAME} -n {NAMESPACE}
5. Review the service instance or binding in SAP BTP to confirm it recognizes the re-established connection with the CR in your Kyma cluster.
If the connection is not re-established, ensure that your Kyma cluster's ID matches the cluster ID associated with the SAP BTP service instance or binding. To view the cluster ID in the SAP BTP cockpit, go to Services
Instances and Subscriptions . It's under Instances , in the Scope column, in the row that provides information about the service instance. Alternatively, you can view the cluster ID using the SAP BTP command line interface (btp CLI). If you discover mismatched IDs, reconfigure your Kyma cluster with the correct cluster ID.
## 4.3.1.4 Cloud Manager Module
Use the Cloud Manager module to manage infrastructure providers' resources from SAP BTP, Kyma runtime.
## What Is Cloud Manager?
The Cloud Manager module manages access to cloud providers' chosen resources and products. Once you add Cloud Manager to your Kyma cluster, the module securely brings the offered resources. Cloud Manager is strictly coupled with the cloud provider where your Kyma cluster is deployed.
##  Remember
Using certain features of the Cloud Manager module introduces additional costs. For more information, see Calculation with the Cloud Manager Module [page 96].
## Scope
The Cloud Manager module is available on Kyma clusters running on Amazon Web Services, Google Cloud, and Microsoft Azure.
<!-- image -->
##  Restriction
Cloud Manager supports the NFS and VPC peering features of Amazon Web Services and Google Cloud only.
## Features
The Cloud Manager module provides the following features tailored for each of the cloud providers.
- NFS [page 1919]: Network File System (NFS) server that can be used as a ReadWriteMany (RWX) volume in the Kyma cluster.
- VPC Peering [page 1920]: Virtual Private Cloud (VPC) peering between your SAP BTP, Kyma runtime and remote cloud provider's project, account, or subscription.
- Redis [page 1923]: cloud provider-flavored cache that can be used in your Kyma cluster.
## Architecture
Cloud Manager has read and write access to your IpRange, VpcPeering, NfsVolume, and Redis custom resources (CRs) in the Kyma cluster. The module also manages Kyma VPC networks, NFS Volume instances, and Redis instances in your cloud provider landscape in Kyma.
<!-- image -->
## API/Custom Resource Definitions
The cloud-resources.kyma-project.io Custom Resource Definition (CRD) describes the kind and the format of data that Cloud Manager uses to configure resources. For more information, see Cloud Manager Resources [page 1925].
## Related Information
kyma-project.io: Cloud Manager module: Tutorials Calculation with the Cloud Manager Module [page 96]
## 4.3.1.4.1 NFS
Cloud Manager NFS feature enables creation of RWX volumes, allowing multiple workloads to use the same storage.
The Cloud Manager module enables a Network File System (NFS) feature which allows you to create ReadWriteMany (RWX) volumes. While regular persistent disk volumes can't be shared and can be used by only a single workload, RWX volumes can be used by multiple workloads.
##  Remember
Using the Cloud Manager module and enabling NFS storage, introduces additional costs. For more information, see Calculation with the Cloud Manager Module [page 96].
## Cloud Providers
When you create an NFS instance in SAP BTP, Kyma runtime, you depend on the cloud provider of your Kyma cluster. The cloud provider in use determines the exact implementation.
The Cloud Manager module supports the NFS feature of the following cloud providers:
- Amazon Web Services Amazon Elastic File System
- Google Cloud Filestore
To create and configure a Cloud Manager's NFS instance, use a dedicated NFS custom resource (CR) corresponding with the cloud provider for your Kyma cluster, namely AwsNfsVolume CR or GcpNfsVolume CR. For more information, see NFS Resources [page 1925].
## Prerequisites
To instantiate NFS, an IpRange CR must exist in the Kyma cluster. IpRange defines network address space reserved for your cloud provider's NFS resources. If you don't create the IpRange CR manually, Cloud Manager creates a default IpRange CR with the default address space and Classless Inter-Domain Routing (CIDR) selected. For more information, see IP Range [page 1925].
## Lifecycle
AwsNfsVolume and GcpNfsVolume are namespace-level CRs. Once you create a GcpNfsVolume or AwsNfsVolume resource, the following resources are also created automatically:
- IpRange CR
- IpRange is a cluster-level CR.
- Only one IpRange CR can exist per cluster.
- If you don't want the default IpRange to be used, create one manually.
- Persistent Volume (PV)
- PV is a cluster-level piece of storage.
- The PV uses a unique name based on the NFS instance status ID.
- The PV references the instantiated NFS in the respective cloud provider.
- Persistent Volume Claim (PVC)
- PVC is a namespace-level resource created in the same namespace as the IpRange CR.
- By default, the PVC's name is the same as the name of your NFS instance unless you specify a different name.
- The PVC references the automatically created PV.
## Related Information
kyma-project.io: Using NFS in Amazon Web Services kyma-project.io: Using NFS in Google Cloud NFS Resources [page 1925] Calculation with the Cloud Manager Module [page 96]
## 4.3.1.4.2 VPC Peering
VPC Peering in the Cloud Manager module enables peering with remote VPC networks of the same cloud provider.
<!-- image -->
##  Restriction
Cloud Manager supports the VPC peering feature of Amazon Web Services and Google Cloud only.
The Cloud Manager module enables managed Virtual Private Cloud (VPC) peering functionality that allows you to peer the Kyma VPC network with a remote VPC network. Virtual network peering is possible only between networks of the same cloud providers. VPC peering in Kyma is fully automated. It means that Cloud Manager configures the peering on both Kyma's and cloud provider's side.
## Cloud Providers
When you configure VPC peering in SAP BTP, Kyma runtime, you depend on the cloud provider of your Kyma cluster. The cloud provider in use determines the exact implementation.
The Cloud Manager module supports the VPC Peering feature of the following cloud providers:
- Amazon Web Services VPC peering
- Google Cloud VPC Network Peering
You can configure Cloud Manager's VPC peering using a dedicated custom resource (CR) corresponding with the cloud provider for your Kyma cluster, namely:
- AwsVpcPeering CR
- GcpVpcPeering CR
For more information, see VPC Peering Resources [page 1926].
## Prerequisites
Before you initiate VPC peering from a Kyma cluster, you must perform the following actions:
- Authorize Cloud Manager in the remote cloud provider landscape. For more information, see Authorizing Cloud Manager in the Remote Cloud Provider [page 1922].
- Tag the remote network with the Kyma shoot name. For more information, see the following tutorials:
- Allow SAP BTP, Kyma Runtime to Peer with Your Remote Network in Creating Virtual Private Cloud Peering in Amazon Web Services.
- Allow SAP BTP, Kyma Runtime to Peer with Your Remote Network in Creating Virtual Private Cloud Peering in Google Cloud.
## Lifecycle
VPC peering CRs are cluster-level resources. Once one of the VPC peering resources is applied, the status of the VPC peering connection is reflected in that CR. At the same time, Cloud Manager creates a VPC peering connection in the Kyma cluster underlying cloud provider landscape and accepts the VPC peering connection in the remote cloud provider landscape.
When you delete a VPC peering CR, the VPC peering connection in the Kyma cloud provider landscape is deleted automatically. However, the remote VPC peering connection is left hanging, and you must delete it manually.
## Limitations
The limit on the number of VPC peering CRs per Kyma cluster depends on the quotas for each cloud provider.
## Related Information
kyma-project.io: Creating VPC Peering in Amazon Web Services
kyma-project.io: Creating VPC Peering in Google Cloud kyma-project.io: Creating VPC Peering in Microsoft Azure VPC Peering Resources [page 1926]