A Service Broker is a server compatible with the Open Service Broker API specification. Each Service Broker registered in Kyma presents the services it offers to the Service Catalog and manages their lifecycle.

The Service Catalog lists all services that Service Brokers offer. Use the Service Brokers to:

• Provision and deprovision an instance of a service.
• Create and delete a ServiceBinding to link a ServiceInstance to an application.

Each of the Service Brokers available in Kyma performs these operations in a different way. See the documentation of a given Service Broker to learn how it operates. The Service Catalog provided by Kyma is currently integrated with the following Service Brokers:

• Application Broker
• Helm Broker

You can also use Helm Broker addons to install these third-party brokers:

To get the addons that the Helm Broker provides, go to the addons repository. To build your own Service Broker, follow the Open Service Broker API specification. For details on how to register a sample Service Broker in the Service Catalog, go to the Tutorials section.

NOTE: The Service Catalog has the Istio sidecar injected. To enable the communication between the Service Catalog and Service Brokers, either inject Istio sidecar into all brokers or disable mutual TLS authentication.

The diagram describes the Service Catalog workflow and the roles of specific cluster and Namespace-scoped resources in this process:

1. The Kyma installation results in the registration of the default Service Brokers in the Kyma cluster. The Kyma administrator can manually register other ClusterServiceBrokers in the Kyma cluster. The Kyma user can also register a Service Broker in a given Namespace.

2. Inside the cluster, each ClusterServiceBroker exposes services that are ClusterServiceClasses in their different variations called ClusterServicePlans. Similarly, the ServiceBroker registered in a given Namespace exposes ServiceClasses and ServicePlans only in this specific Namespace.

3. Using the Console UI or CLI, the Kyma user lists all exposed cluster-wide and Namespace-specific services and requests to create instances of those services in the Namespace.

4. The Kyma user creates bindings to the ServiceInstances so that the given applications can access the provisioned services.

Unbinding and deprovisioning are processes reverse to provisioning and binding. The diagram shows an overview of interactions between all resources related to the processes of unbinding and deprovisioning a service:

Unbind a service

You can unbind a service in two ways:

• Delete a ServiceBindingUsage. During this process, the Secret injection is deleted, but the Secret itself still exists in the Namespace.
• Delete a ServiceBinding. It deletes the Secret and triggers the deletion of all related ServiceBindingUsage custom resources.

Deprovision a service

To deprovision a given service, delete the ServiceInstance custom resource. During this operation, a Service Broker deletes all custom resources created during the provisioning process. When the process is complete, the service becomes unavailable.

TIP: Deleting a ServiceInstance deletes all related ServiceBinding and ServiceBindingUsage custom resources. If you want to deprovision a service completely, skip the unbinding process and simply delete the ServiceInstance.

To configure the PodPreset sub-chart, override the default values of its values.yaml file. This document describes parameters that you can configure.

TIP: To learn more about how to use overrides in Kyma, see the following documents:

• Helm overrides for Kyma installation
• Sub-charts overrides

Configurable parameters

This table lists the configurable parameters, their descriptions, and default values:

The usagekinds.servicecatalog.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to define what kind of resources can be bound with the ServiceBinding and how to bind them. To get the up-to-date CRD and show the output in the YAML format, run this command:

kubectl get crd usagekinds.servicecatalog.kyma-project.io -o yaml

Sample custom resource

This is a sample resource that allows you to bind a given resource with the ServiceBinding. This example has a resource section specified as function. You can adjust this section to point to any other kind of resource.

apiVersion: servicecatalog.kyma-project.io/v1alpha1
kind: UsageKind
metadata:
  name: function
spec:
  displayName: Function
  resource:
    group: serving.knative.dev
    kind: service
    version: v1
  labelsPath: spec.template.metadata.labels

The binding process modifies the target resource by adding labels to the Pod. The UsageKind specifies the field which contains labels added to the Pod, as well as the resource type defined by the group, kind, and version fields.

The ServiceBindingUsage Controller takes the value from the spec.usedBy.kind field of the ServiceBindingUsage custom resource and looks for the corresponding UsageKind which contains information about the resource to be bound. The ServiceBindingUsage Controller handles resources even if the specified labelsPath field does not exist.

Finalizer

Every UsageKind contains a finalizer which prevents deletion of the UsageKind in use. The ServiceBindingUsage Controller removes the finalizer only when the UsageKind is not used by any ServiceBindingUsage.

Custom resource parameters

This table lists all the possible parameters of a given resource together with their descriptions:

Related resources and components

These are the resources related to this CR:

These components use this CR:

RBAC settings

The administrator who adds the UsageKind must take care of the RBAC settings. The ServiceBindingUsage Controller and Console Backend Service must be allowed to perform required operations on the resources, with the type defined in the UsageKind object.

See the example of the RBAC Rule for the ServiceBindingUsage Controller:

- apiGroups: ["serving.knative.dev"]
  resources: ["services"]
  verbs: ["get", "list", "watch", "patch", "update"]

Here is the example for the Console Backend Service:

- apiGroups: ["serving.knative.dev"]
  resources: ["services"]
  verbs: ["get", "list", "watch"]

This document describes the mapping of OSBA service objects, plan objects, and conventions in the Kyma Console Catalog view.

Catalog page

These are the OSBA fields used in the main Catalog page:

*Fields with an asterisk are required OSBA attributes.

**metadata.labels is the custom object that is not defined in the OSBA metadata convention.

Catalog Details page

These are the OSBA fields used in the detailed ServiceClass view:

*Fields with an asterisk are required OSBA attributes.

Add to Namespace

These are the OSBA fields used in the Add to Namespace window:

*Fields with an asterisk are required OSBA attributes.

Plan schema

A plan object in the OSBA can have the schemas field. Schema is used to generate a form which enables provisioning of the ServiceClass.

See the sample schema:

{
          "$schema": "http://json-schema.org/draft-04/schema#",
          "properties": {
            "imagePullPolicy": {
              "default": "IfNotPresent",
              "enum": [
                "Always",
                "IfNotPresent",
                "Never"
              ],
              "title": "Image pull policy",
              "type": "string"
            },
            "redisPassword": {
              "default": "",
              "format": "password",
              "description": "Redis password. Defaults to a random 10-character alphanumeric string.",
              "title": "Password (Defaults to a random 10-character alphanumeric string)",
              "type": "string"
            }
          },
          "type": "object"
        }

This sample renders in the following way:

Follow these rules when you design schema objects:

• If the field has limited possible values, use the enum field. It renders as a dropdown menu, so it prevents the user from making mistakes.
• If the field is required for the ServiceClass, mark it as required. UI blocks provisioning if you do not fill in the required fields.
• Fill the default value for a field whenever possible, it makes the provisioning faster.
• If the field, such as the password field, must be starred, use the format key with the password value.

This document describes the mapping of OSBA service objects, plan objects, and conventions in the Kyma Console Instances view.

Service Instances page

These are the OSBA fields used in the main Instances page:

*Fields with an asterisk are required OSBA attributes.

Service Instance Details page

These are the OSBA fields used in the detailed Service Instance view:

*Fields with an asterisk are required OSBA attributes.

Documentation for ServiceClasses is rendered in both Service Catalog and Instances views. It includes the following specification types:

• Markdown
• OpenAPI
• AsyncAPI
• OData

This document explains how and where these specifications are rendered in the Console UI. It also describes the structure of the Markdown documents, their obligatory metadata, and optional features in the content body.

Tabs

Depending on the type of the input files, the Console UI renders specifications under different tabs in Service Catalog and Instances views:

• Markdown under the Documentation tab.
• OpenAPI under the Console tab.
• AsyncAPI under the Events tab.
• OData under the OData tab.

See the tabs overview:

NOTE: OpenAPI, OData, and AsyncAPI specifications rendered in the Console UI follow the Fiori 3 Fundamentals styling standards.

Markdown documents

AssetGroup and ClusterAssetGroup custom resources that orchestrate documentation in the Console UI support various documentation formats, including Markdown (.md) documents. Each .md file must consist of two parts: metadata and content. The following example illustrates the required structure:

---
metadata: {value or text string}
another_metadata: {value or text string}
---
{The content of your document in **Markdown**.}

Metadata

Each Markdown document displayed in the Kyma Console requires metadata in a specific format called front matter.

Structure

When you create a Markdown document, define its title and type. Place the metadata at the top of your .md file, and separate it with three dashes.

---
title: {Document title}
type: {Document type}
---

• The title metadata defines the title of your document. If you want the title or its part to render inside quotation marks, place it between additional, single quotation marks or use a backslash (/) before the quoted word. See the following examples:

  ✅ title: '"Transport is closing" error'

  ✅ title: "\"Transport is closing\" error"

  ⛔️ title: "Transport is closing" error

• The type metadata groups single documents together. Multiple documents that use the same type generate a grouping. For example, if you have multiple tutorials, you can group them under a navigation node called Tutorials.

NOTE: If there is only one document of a certain type, remove the type metadata, so that the document displays well in the UI.

Display

In the Service Catalog and Instances views, which contain ServiceClasses documentation, Markdown documents are displayed in the Documentation tab. The title and type metadata create the right-side navigation. A document with the Overview title always displays on top while other documents follow in alphabetical order. If you don't provide title and type, these UIs display the file name as a fallback. See the following example:

NOTE: A document with the Overview title always displays as the first tab. Markdown files with title other than Overview appear in an alphanumeric order.

Content

Content is the body of your document. Write content in Markdown which is a simplified markup language.

In Kyma, to make documentation more reader-friendly, some Markdown features are customized. See the following examples:

1. Linking - link between documents in the same topic or in different topics using metadata.

   • Source
   • Preview

2. Documentation toggles - render several versions of a given section in one document or have several versions of one document.

   • Source
   • Preview

3. Panels - use colorful containers that call out important or additional information within a topic.

   • Source
   • Preview

Read the Content Guidelines to learn more about the customized Markdown features and other rules of writing content in Kyma.

CAUTION: Markdown customized in a different way than in Kyma may not render properly in the Console UI.