Hide navigation
Components

Service Catalog

Overview

The Service Catalog groups reusable, integrated services from all Service Brokers registered in Kyma. Its purpose is to provide an easy way for Kyma users to access services that the Service Brokers manage and use them in their applications.

Due to the fact that Kyma runs on Kubernetes, you can easily instantiate a service that a third party provides and maintains, such as a database. You can consume it from Kyma without extensive knowledge about the clustering of such a datastore service and the responsibility for its upgrades and maintenance. You can also easily provision an instance of the software offering that a Service Broker registered in Kyma exposes, and bind it to an application running in the Kyma cluster.

You can perform the following operations in the Service Catalog:

  • Expose the consumable services by listing them with all the details, including the documentation and the consumption plans.
  • Consume the services by provisioning them in a given Namespace.
  • Bind the services to the applications through Secrets.

NOTE: Kyma uses the Service Catalog based on the one provided by Kubernetes. Kyma also supports the experimental version of the Service Catalog without api-server and etcd. Read this document for more information.

Architecture

The diagram and steps describe the Service Catalog workflow and the roles of specific cluster and Namespace-wide resources in this process:

Service Catalog flow

  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. In 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 to allow the given applications to access the provisioned services.

Resources

This document includes an overview of resources that the Kyma Service Catalog provides.

NOTE: The "Cluster" prefix in front of resources means they are cluster-wide. Resources without that prefix refer to the Namespace scope.

  • ClusterServiceBroker is an endpoint for a set of managed services that a third party offers and maintains.

  • ClusterServiceClass is a managed service exposed by a given ClusterServiceBroker. When a cluster administrator registers a new Service Broker in the Service Catalog, the Service Catalog controller obtains new services exposed by the Service Broker and renders them in the cluster as ClusterServiceClasses. A ClusterServiceClass is synonymous with a service in the Service Catalog.

  • ClusterServicePlan is a variation of a ClusterServiceClass that offers different levels of quality, configuration options, and the cost of a given service. Contrary to the ClusterServiceClass, which is purely descriptive, the ClusterServicePlan provides technical information to the ClusterServiceBroker on this part of the service that the ClusterServiceBroker can expose.

  • ServiceBroker is any Service Broker registered in a given Namespace where it exposes ServiceClasses and ServicePlans that are available only in that Namespace.

  • ServiceClass is a Namespace-scoped representation of a ClusterServiceClass. Similarly to the ClusterServiceClass, it is synonymous with a service in the Service Catalog.

  • ServicePlan is a Namespace-scoped representation of a ClusterServicePlan.

  • ServiceInstance is a provisioned instance of a ClusterServiceClass to use in one or more cluster applications.

  • ServiceBinding is a link between a ServiceInstance and an application that cluster users create to request credentials or configuration details for a given ServiceInstance.

  • Secret is a basic resource to transfer credentials or configuration details that the application uses to consume a ServiceInstance. The service binding process leads to the creation of a Secret.

  • ServiceBindingUsage is a Kyma custom resource that allows the ServiceBindingUsage controller to inject Secrets into a given application.

  • UsageKind is a Kyma custom resource that defines which resources can be bound with the ServiceBinding and how to bind them.

Provisioning and binding

Provisioning a service means creating an instance of a service. When you consume a specific ClusterServiceClass or a ServiceClass, and the system provisions a ServiceInstance, you need credentials for this service. To obtain credentials, create a ServiceBinding resource using the Service Catalog API. One instance can have numerous bindings to use in the application. When you raise a binding request, the system returns the credentials in the form of a Secret. The system creates a Secret in a given Namespace.

NOTE: The security in Kyma relies on the Kubernetes concept of a Namespace which is a security boundary. If the Secret exists in the Namespace, the administrator can inject it to any Deployment. The Service Broker cannot prevent other applications from consuming a created Secret. Therefore, to ensure a stronger level of isolation and security, use a dedicated Namespace and request separate bindings for each Deployment.

The Secret allows you to run the service successfully. However, a problem appears each time you need to change the definition of the yaml file in the Deployment to specify the Secrets' usage. The manual process of editing the file is tedious and time-consuming. Kyma handles it by offering a custom resource called ServiceBindingUsage. This custom resource applies the Kubernetes PodPreset resource and allows you to enforce an automated flow in which the Binding Usage Controller injects ServiceBindings into a given Deployment or Function.

Provisioning and binding flow

The diagram shows an overview of interactions between all resources related to Kyma provisioning and binding, and the reverting, deprovisioning, and unbinding operations.

Kyma provisioning and binding

The process of provisioning and binding invokes the creation of three custom resources:

  • ServiceInstance
  • ServiceBinding
  • ServiceBindingUsage

The system allows you to create these custom resources in any order, but within a timeout period.

When you invoke the deprovisioning and unbinding actions, the system deletes all three custom resources. Similar to the creation process dependencies, the system allows you to delete ServiceInstance and ServiceBinding in any order, but within a timeout period. However, before you delete the ServiceBinding, make sure you remove the ServiceBindingUsage first. For more details, see the section on deleting a ServiceBinding.

Provision a service

To provision a service, create a ServiceInstance custom resource. Generally speaking, provisioning is a process in which the Service Broker creates a new instance of a service. The form and scope of this instance depends on the Service Broker.

Kyma provisioning

Create a ServiceBinding

Kyma binding operation consists of two phases:

  1. The system gathers the information necessary to connect to the ServiceInstance and authenticate it. The Service Catalog handles this phase directly, without the use of any additional Kyma custom resources.
  2. The system must make the information it collected available to the application. Since the Service Catalog does not provide this functionality, you must create a ServiceBindingUsage custom resource.

Kyma binding

TIP: You can create the ServiceBinding and ServiceBindingUsage resources at the same time.

Define other types of resources

The UsageKind is a cluster-wide custom resource which allows you to bind a ServiceInstance to any kind of resource. By default, Kyma provides two UsageKinds which enable binding either to a Deployment or Function. You can add more UsageKinds if you want to bind your ServiceInstance to other types of resources. The UsageKind contains information on how the binding to these custom resources is conducted. The ServiceBindingUsage uses this information to inject Secrets to the application.

Kyma UsageKind

Delete a ServiceBinding

Kyma unbinding can be achieved in two ways:

  • Delete the ServiceBindingUsage. The Service Binding Usage Controller deletes the Secret injection, but the Secret itself still exists in the Namespace.
  • Delete the ServiceBinding. It deletes the Secret and triggers the deletion of all related ServiceBindingUsages.

Kyma unbinding

Deprovision a service

To deprovision a given service, delete the ServiceInstance custom resource. As part of this operation, the Service Broker deletes any resource created during the provisioning. When the process completes, the service becomes unavailable.

Kyma deprovisioning

NOTE: You can deprovision a service only if no corresponding ServiceBinding for a given ServiceInstance exists.

Experimental features

The Service Catalog requires its own instance of api-server and etcd, which increases the complexity of the cluster configuration and maintenance costs. In case of api-server downtime, all Service Catalog resources are unavailable. For this reason, Kyma developers contribute to the Service Catalog project to remove the dependency on these external components and replace them with a native Kubernetes solution - CustomResourceDefinitions (CRDs).

Enable CRDs

To enable the CRDs feature in the Service Catalog, override the global.serviceCatalogApiserver.enabled and global.serviceCatalogCrds.enabled parameters in the installation file:

  • For the local installation, modify the installation-config-overrides ConfigMap in the installer-config-local.yaml file:
    Click to copy
    apiVersion: v1
    kind: ConfigMap
    metadata:
    name: installation-config-overrides
    namespace: kyma-installer
    labels:
    installer: overrides
    kyma-project.io/installation: ""
    data:
    global.isLocalEnv: "true"
    global.domainName: "kyma.local"
    global.adminPassword: ""
    nginx-ingress.controller.service.loadBalancerIP: ""
    global.serviceCatalogApiserver.enabled: "true"
    global.serviceCatalogCrds.enabled: "false"
  • For the cluster installation, add the service-catalog-versions-overrides ConfigMap to the cluster before the installation starts. Run:
    Click to copy
    kubectl create configmap service-catalog-overrides-versions -n kyma-installer --from-literal=global.serviceCatalogApiserver.enabled=false --from-literal=global.serviceCatalogCrds.enabled=true \
    && kubectl label configmap service-catalog-overrides-versions -n kyma-installer installer=overrides

Service Catalog chart

To configure the Service Catalog 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:

Configurable parameters

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

ParameterDescriptionDefault value
etcd-stateful.replicaCountSpecifies the number of members in an etcd cluster.3
etcd-stateful.etcd.resources.limits.memoryDefines limits for memory resources.512Mi

NOTE: Overriding values in this chart has priority over overriding values in the etcd-stateful chart.

ParameterDescriptionDefault value
service-catalog-apiserver.enabledEnables Service Catalog with the Aggregated API Server.true
service-catalog-crds.enabledEnables Service Catalog with the CRDs implementation.false

CAUTION: These values are mutually exclusive and they cannot be both enabled or disabled.

Catalog sub-chart

To configure the Catalog 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:

Configurable parameters

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

ParameterDescriptionDefault value
apiserver.resources.requests.cpuDefines requests for CPU resources.100m
apiserver.resources.requests.memoryDefines requests for memory resources.30Mi
apiserver.resources.limits.cpuDefines limits for CPU resources.100m
apiserver.resources.limits.memoryDefines limits for memory resources.40Mi
apiserver.verbosityDefines log severity level. The possible values range from 0-10.10
controllerManager.resources.requests.cpuDefines requests for CPU resources.100m
controllerManager.resources.requests.memoryDefines requests for memory resources.20Mi
controllerManager.resources.limits.cpuDefines limits for CPU resources.100m
controllerManager.resources.limits.memoryDefines limits for memory resources.30Mi
controllerManager.verbosityDefines log severity level. The possible values range from 0-10.10
controllerManager.brokerRelistIntervalActivatedSpecifies whether or not the controller supports a --broker-relist-interval flag. If this is set to true, brokerRelistInterval will be used as the value for that flag.true
controllerManager.brokerRelistIntervalSpecifies how often the controller relists the catalogs of ready brokers. The duration format is 20m, 1h, etc.24h
originatingIdentityEnabledEnables the OriginatingIdentity feature which controls whether the controller includes originating identity in the header of requests sent to brokers and persisted under a CustomResource.true
asyncBindingOperationsEnabledEnables support for asynchronous binding operations.true
namespacedServiceBrokerDisabledDisables support for Namespace-scoped brokers.false
securityContextGives the opportunity to run container as non-root by setting a securityContext. For example: securityContext: { runAsUser: 1001 }{}

Catalog CRDs sub-chart

To configure the Catalog CRDs 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:

Configurable parameters

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

ParameterDescriptionDefault value
controllerManager.resources.requests.cpuDefines requests for CPU resources.100m
controllerManager.resources.requests.memoryDefines requests for memory resources.20Mi
controllerManager.resources.limits.cpuDefines limits for CPU resources.100m
controllerManager.resources.limits.memoryDefines limits for memory resources.30Mi
controllerManager.verbosityDefines log severity level. The possible values range from 0-10.10
webhook.resources.requests.cpuDefines requests for CPU resources.100m
webhook.resources.requests.memoryDefines requests for memory resources.20Mi
webhook.resources.limits.cpuDefines limits for CPU resources.100m
webhook.resources.limits.memoryDefines limits for memory resources.30Mi
webhook.verbosityDefines log severity level. The possible values range from 0-10.10
controllerManager.brokerRelistIntervalActivatedSpecifies whether or not the controller supports a --broker-relist-interval flag. If this is set to true, brokerRelistInterval will be used as the value for that flag.true
controllerManager.brokerRelistIntervalSpecifies how often the controller relists the catalogs of ready brokers. The duration format is 20m, 1h, etc.24h
originatingIdentityEnabledEnables the OriginatingIdentity feature which controls whether the controller includes originating identity in the header of requests sent to brokers and persisted under a CustomResource.true
asyncBindingOperationsEnabledEnables support for asynchronous binding operations.true
namespacedServiceBrokerDisabledDisables support for Namespace-scoped brokers.false
securityContextGives the opportunity to run container as non-root by setting a securityContext. For example: securityContext: { runAsUser: 1001 }{}

Etcd-stateful sub-chart

To configure the Etcd-stateful 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:

Configurable parameters

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

ParameterDescriptionDefault value
etcd.resources.requests.memoryDefines requests for memory resources.64Mi
etcd.resources.requests.cpuDefines requests for CPU resources.50m
etcd.resources.limits.memoryDefines limits for memory resources.256Mi
etcd.resources.limits.cpuDefines limits for CPU resources.200m

PodPreset sub-chart

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:

Configurable parameters

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

ParameterDescriptionDefault value
controller.enabledEnables the controller-manager which restarts Deployments whenever the PodPreset changes.false
webhook.verbosityDefines log severity level. The possible values range from 0-10.6

ServiceBindingUsage

The servicebindingusages.servicecatalog.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to inject Secrets to an application. To get the up-to-date CRD and show the output in the yaml format, run this command:

Click to copy
kubectl get crd servicebindingusages.servicecatalog.kyma-project.io -o yaml

Sample custom resource

This is a sample resource in which the ServiceBindingUsage injects a Secret associated with the redis-instance-binding ServiceBinding to the redis-client Deployment in the production Namespace. In this example, the status.conditions.status field is set to True, which means that the ServiceBinding injection is successful. If the injection fails, this field is set to False and the message and reason fields appear. This example also has the envPrefix.name field specified, which adds a prefix to all environment variables injected from a given Secret to your Pod. This allows you to separate environment variables injected from different Secrets. By default, the prefixing is disabled. Set the envPrefix.name to enable it.

NOTE: The prefix is not separated from the name of an environment variable by any character. If you want to separate your prefix, add a special character at the end of it. For example, if you want your prefixed variable look like pref1_var1, set the pref1_ prefix.

Click to copy
apiVersion: servicecatalog.kyma-project.io/v1alpha1
kind: ServiceBindingUsage
metadata:
name: redis-client-binding-usage
namespace: production
"ownerReferences": [
{
"apiVersion": "servicecatalog.k8s.io/v1beta1",
"kind": "ServiceBinding",
"name": "redis-instance-binding",
"uid": "65cc140a-db6a-11e8-abe7-0242ac110023"
}
],
spec:
serviceBindingRef:
name: redis-instance-binding
usedBy:
kind: deployment
name: redis-client
parameters:
envPrefix:
name: "pico-bello"
status:
conditions:
- lastTransitionTime: 2018-06-26T10:52:05Z
lastUpdateTime: 2018-06-26T10:52:05Z
status: "True"
type: Ready

Custom resource parameters

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

ParameterRequiredDescription
metadata.nameYESSpecifies the name of the CR.
metadata.namespaceYESSpecifies the Namespace in which the CR is created.
metadata.ownerReferencesYESContains an ownerReference to the binding specified in the spec.serviceBindingRef.name field, if the binding exists.
spec.serviceBindingRef.nameYESSpecifies the name of the ServiceBinding.
spec.usedByYESSpecifies the application into which the Secret is injected.
spec.usedBy.kindYESSpecifies the name of the UsageKind custom resource.
spec.usedBy.nameYESSpecifies the name of the application.
spec.parameters.envPrefixNOAdds a prefix to environment variables injected from the given Secret. The prefixing is disabled by default.
spec.parameters.envPrefix.nameYESDefines the value of the prefix. This field is mandatory if envPrefix is specified.
status.conditionsNODefines the state of the ServiceBindingUsage.
status.conditions.lastTransitionTimeNOSpecifies the first time when the Service Binding Usage Controller processed the ServiceBindingUsage, or the time when the status.conditions.status field changed.
status.conditions.lastUpdateTimeNOSpecifies the time of the last ServiceBindingUsage condition update.
status.conditions.statusNOSpecifies whether the ServiceBinding injection is successful or not.
status.conditions.typeNODefines the type of the condition. The value of this field is always ready.
messageNODescribes in a human-readable way why the ServiceBinding injection failed.
reasonNOSpecifies a unique, one-word, camelCase reason for the ServiceBinding injection failure. See this file for the complete list of reasons.

These are the resources related to this CR:

Custom resourceDescription
UsageKindProvides information on where to inject Secrets.
ServiceBindingProvides Secrets to inject.

These components use this CR:

ComponentDescription
Service Binding Usage ControllerReacts to every action of creating, updating, or deleting ServiceBindingUsages in all Namespaces, and uses ServiceBindingUsage data to inject binding.
Console Backend ServiceExposes the given CR to the Console UI. It also allows you to create and delete a ServiceBindingUsage.

UsageKind

The usagekinds.servicecatalog.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to define which 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:

Click to copy
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.

Click to copy
apiVersion: servicecatalog.kyma-project.io/v1alpha1
kind: UsageKind
metadata:
name: function
spec:
displayName: Function
resource:
group: kubeless.io
kind: function
version: v1beta1
labelsPath: spec.deployment.spec.template.metadata.labels

Custom resource parameters

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

ParameterMandatoryDescription
metadata.nameYESSpecifies the name of the CR.
spec.displayNameYESProvides a human-readable name of the UsageKind.
spec.resourceYESSpecifies a resource which is bound with the ServiceBinding. The target resource is specified by its resource group, kind, and version.
spec.resource.groupYESSpecifies the group of the resource.
spec.resource.kindYESSpecifies the kind of the resource.
spec.resource.versionYESSpecifies the version of the resource.
spec.labelsPathYESSpecifies a path to the key that contains labels which are later injected into Pods.

These are the resources related to this CR:

Custom resourceDescription
ServiceBindingUsageContains the reference to the UsageKind.

These components use this CR:

ComponentDescription
Service Binding Usage ControllerUses the UsageKind spec.resource and spec.labelsPath parameters to find a resource and a path to which it should inject Secrets.
Console Backend ServiceExposes the given CR to the Console UI.

CLI reference

Management of the Service Catalog is based on Kubernetes resources and the custom resources specifically defined for Kyma. Manage all of these resources through kubectl.

Details

This section describes the resource names to use in the kubectl command line, the command syntax, and examples of use.

Resource types

Service Catalog operations use the following resources:

Singular namePlural name
clusterservicebrokerclusterservicebrokers
clusterserviceclassclusterserviceclasses
clusterserviceplanclusterserviceplans
secretsecrets
servicebindingservicebindings
servicebindingusageservicebindingusages
servicebrokerservicebrokers
serviceclassserviceclasses
serviceinstanceserviceinstances
serviceplanserviceplans
Syntax

Follow the kubectl syntax, kubectl {command} {type} {name} {flags}, where:

  • {command} is any command, such as describe.
  • {type} is a resource type, such as clusterserviceclass.
  • {name} is the name of a given resource type. Use {name} to make the command return the details of a given resource.
  • {flags} specifies the scope of the information. For example, use flags to define the Namespace from which to get the information.
Examples

The following examples show how to create a ServiceInstance, how to get a list of ClusterServiceClasses and a list of ClusterServiceClasses with human-readable names, a list of ClusterServicePlans, and a list of all ServiceInstances.

  • Create a ServiceInstance using the example of the Redis ServiceInstance for the 0.1.40 version of the Service Catalog:
Click to copy
cat <<EOF | kubectl create -f -
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceInstance
metadata:
name: my-instance
namespace: stage
spec:
clusterServiceClassExternalName: redis
clusterServicePlanExternalName: micro
parameters:
"imagePullPolicy": "Always"
EOF
  • Get the list of all ClusterServiceClasses:
Click to copy
kubectl get clusterserviceclasses
  • Get the list of all ClusterServiceClasses and their human-readable names:
Click to copy
kubectl get clusterserviceclasses -o=custom-columns=NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName
  • Get the list of all ClusterServicePlans and associated ClusterServiceClasses:
Click to copy
kubectl get clusterserviceplans -o=custom-columns=NAME:.metadata.name,EXTERNAL\ NAME:.spec.externalName,EXTERNAL\ SERVICE\ CLASS:.spec.clusterServiceClassRef
  • Get the list of all ServiceInstances from all Namespaces:
Click to copy
kubectl get serviceinstances --all-namespaces

Register a broker in the Service Catalog

This tutorial shows you how to register a broker in the Service Catalog. The broker can be either a Namespace-scoped ServiceBroker or a cluster-wide ClusterServiceBroker. Follow this guide to register a cluster-wide or Namespace-scoped version of the sample UPS Broker.

Prerequisites

Steps

  1. Clone the service-catalog repository:

    Click to copy
    git clone https://github.com/kubernetes-incubator/service-catalog.git
  2. Check out one of the official tags. For example:

    Click to copy
    git fetch --all --tags --prune
    git checkout tags/v0.1.39 -b v0.1.39
  3. Create the ups-broker Namespace:

    Click to copy
    kubectl create namespace ups-broker
  4. Run this command to install the chart with the ups-broker name in the ups-broker Namespace:

    Click to copy
    helm install ./charts/ups-broker --name ups-broker --namespace ups-broker
  5. Register a broker:

  • Run this command to register a ClusterServiceBroker:
    Click to copy
    kubectl create -f ./contrib/examples/walkthrough/ups-clusterservicebroker.yaml
  • To register the UPS Broker as a ServiceBroker in the ups-broker Namespace, run:
    Click to copy
    kubectl create -f ./contrib/examples/walkthrough/ups-servicebroker.yaml -n ups-broker
    After you successfully register your ServiceBroker or ClusterServiceBroker, the Service Catalog periodically fetches services from this broker and creates ServiceClasses or ClusterServiceClasses from them.
  1. Check the status of your broker:
  • To check the status of your ClusterServiceBroker, run:
    Click to copy
    kubectl get clusterservicebrokers ups-broker -o jsonpath="{.status.conditions}"
  • To check the status of the ServiceBroker, run:

    Click to copy
    kubectl get servicebrokers ups-broker -n ups-broker -o jsonpath="{.status.conditions}"

    The output looks as follows:

    Click to copy
    {
    "lastTransitionTime": "2018-10-26T12:03:32Z",
    "message": "Successfully fetched catalog entries from broker.",
    "reason": "FetchedCatalog",
    "status": "True",
    "type": "Ready"
    }
  1. View Service Classes that this broker provides:
  • To check the ClusterServiceClasses, run:
    Click to copy
    kubectl get clusterserviceclasses
  • To check the ServiceClasses, run:

    Click to copy
    kubectl get serviceclasses -n ups-broker

    These are the UPS Broker Service Classes:

    Click to copy
    NAME EXTERNAL NAME
    4f6e6cf6-ffdd-425f-a2c7-3c9258ad2468 user-provided-service
    5f6e6cf6-ffdd-425f-a2c7-3c9258ad2468 user-provided-service-single-plan
    8a6229d4-239e-4790-ba1f-8367004d0473 user-provided-service-with-schemas

Overview

UI Contracts are contracts between the Service Catalog views in the Kyma Console UI and the Open Service Broker API (OSBA) specification.

There are three types of OSBA fields:

  • Mandatory fields which are crucial to define
  • Optional fields which you can but do not have to define
  • Conventions which are proposed fields that can be passed in the metadata object

The Service Catalog is OSBA-compliant, which means that you can register a Service Class that has only the mandatory fields. However, it is recommended to provide more detailed Service Class definitions for better user experience.

In the Kyma Console UI, there are two types of views:

  • Catalog view
  • Instances view

Read the Catalog view and Instances view documents to:

  • Understand the contract mapping between the Kyma Console UI and the OSBA
  • Learn which fields are primary to define, to provide the best user experience
  • See which fields are used as fallbacks if you do not provide the primary ones

Catalog view

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:

NumberOSBA fieldFallbacksDescription
(1)metadata.displayNamename*, id*If metadata.displayName, name, or id fields are not present, a given Service Class does not appear on the landing page.
(2)metadata.providerDisplayName-If not provided, UI does not display this information.
(3)description*-If not provided, UI does not display this information.
(4)metadata.labels**-If not provided, UI does not display any labels.
(5)metadata.labels.local** and/or metadata.labels.showcase**-If not provided, it is not possible to choose a Basic Filter.
(6)tags-If not provided, it is not possible to filter by Tag.
(7)metadata.labels.connected-app**-If not provided, it is not possible to choose Connected Applications.
(8)metadata.providerDisplayName-If not provided, it is not possible to filter by Provider.

*Fields with an asterisk are required OSBA attributes.

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

alt text

Catalog Details page

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

NumberOSBA fieldFallbacksDescription
(1)metadata.displayNamename*, id*-
(2)metadata.providerDisplayName-If not provided, UI does not display this information.
(3)not related to OSBA--
(4)metadata.documentationUrl-If not provided, the link with documentation does not appear.
(5)metadata.supportUrl-If not provided, the link with support does not appear.
(6)tags-If not provided, UI does not display tags.
(7)metadata.longDescriptiondescription*If not provided, the General Information panel does not appear.
(8)not related to OSBA--

*Fields with an asterisk are required OSBA attributes.

alt text

Add to Namespace

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

NumberOSBA fieldFallbacksDescription
(1)plan.metadata.displayNameplan.name*, plan.id*
(2)not related to OSBA-
(3)not related to OSBA-

*Fields with an asterisk are required OSBA attributes.

alt text

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 Service Class.

See the sample schema:

Click to copy
{
"$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:

alt text

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 Service Class, 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.

Instances View

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:

NumberOSBA fieldFallbacksDescription
(1)not related to OSBA-It is the name of the Service Instance, created during service provisioning.
(2)metadata.displayNamename*, id*If not provided, UI does not display this information.
(3)plan.metadata.displayNameplan.name*, plan.id*If not provided, UI does not display this information.
(4)not related to OSBA-
(5)not related to OSBA-

*Fields with an asterisk are required OSBA attributes.

alt text

Service Instance Details page

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

NumberOSBA fieldFallbacksDescription
(1)metadata.displayNamename*, id*-
(2)plan.metadata.displayNameplan.name*, plan.id*-
(3)metadata.documentationUrl-If not provided, UI does not display this information
(4)metadata.supportUrl-If not provided, UI does not display this information
(5)description*-If not provided, UI does not display this information

*Fields with an asterisk are required OSBA attributes.

alt text

Overview

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 the 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 Kyma Service Catalog is currently integrated with the following Service Brokers:

You can also install these brokers using the Helm Broker's bundles:

To get the bundles that the Helm Broker provides, go to the bundles 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, see this tutorial.

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.

GCP Broker

NOTE: The Google Cloud Platform (GCP) Service Broker is in the experimental phase.

Google Cloud Platform (GCP) Service Broker is an implementation of the Open Service Broker (OSB) API hosted on GCP. It simplifies the delivery of GCP services to applications that run on Kyma. By creating GCP resources and managing their corresponding permissions, the Service Broker makes it easy to consume GCP services from within a Kubernetes cluster.

Kyma provides Namespace-scoped Google Cloud Platform Service Broker. In each Namespace, you can configure the Google Cloud Platform Broker against different Google Cloud Platforms. Install the Google Cloud Platform Service Broker by provisioning the Google Cloud Platform Service Broker class provided by the Helm Broker.

Service Catalog view without GCP Classes

Once you provision the Google Cloud Platform Service Broker class, the Google Cloud Platform Service Broker classes are available in the Service Catalog view in a given Namespace.

Service Catalog view without GCP Classes

For more information about provisioning the Google Cloud Platform Service Broker class, go to the service class overview in the Service Catalog UI.

Azure Service Broker

The Microsoft Azure Service Broker is an open-source, Open Service Broker-compatible API server that provisions managed services in the Microsoft Azure public cloud. Kyma provides Namespace-scoped Azure Service Broker. In each Namespace, you can configure the Azure Service Broker against different subscriptions. Install the Azure Service Broker by provisioning the Azure Service Broker class provided by the Helm Broker.

azure broker class

Once you provision the Azure Service Broker class, the Azure Service Broker classes are available in the Service Catalog view in a given Namespace. The Azure Service Broker provides these Service Classes to use with the Service Catalog:

  • Azure SQL Database
  • Azure Database for MySQL
  • Azure Redis Cache
  • Azure Application Insights
  • Azure CosmosDB
  • Azure Event Hubs
  • Azure IoT Hub
  • Azure Key Vault
  • Azure SQL Database
  • Azure SQL Database Failover Group
  • Azure Service Bus
  • Azure Storage
  • Azure Text Analytics

See the details of each Service Class and its specification in the Service Catalog UI. For more information about the Service Brokers, see this document.

NOTE: Kyma uses the Microsoft Azure Service Broker open source project. To ensure the best performance and stability of the product, Kyma uses a version of the Azure Service Broker that precedes the newest version released by Microsoft.

AWS Service Broker

The AWS Service Broker is an open-source, Open Service Broker-compatible API server that provisions managed services in the AWS public cloud. Kyma provides the Namespace-scoped AWS Service Broker. In each Namespace, you can configure the AWS Service Broker against different subscriptions. Install the AWS Service Broker by provisioning the AWS Service Broker class provided by the Helm Broker.

aws broker class

Once you provision the AWS Service Broker class, the AWS Service Broker classes are available in the Service Catalog view in a given Namespace. The AWS Service Broker provides these Service Classes to use with the Service Catalog:

  • Amazon Athena
  • Amazon EMR
  • Amazon Kinesis
  • Amazon RDS for MariaDB
  • Amazon RDS for PostgreSQL
  • Amazon Translate
  • Amazon KMS
  • Amazon Rekognition
  • Amazon SNS
  • Amazon DynamoDB
  • Amazon Redshift
  • Amazon SQS
  • Amazon Polly
  • Amazon RDS for MySQL
  • Amazon S3
  • Amazon Lex
  • Amazon Route53
  • Amazon ElastiCache

Find the documentation for each Service Class here. You can also see the details and specification of each Service Class in the Service Catalog UI, after provisioning a given class.

For more information about the Service Brokers, see this document.

NOTE: Kyma uses the AWS Service Broker open-source project. To ensure the best performance and stability of the product, Kyma uses a version of the AWS Service Broker that precedes the newest version released by Amazon.