Service Catalog
Service Catalog
Service Catalog groups reusable integrated services from Service Brokers registered in Kyma. Its purpose is to provide you with an easy way to access services that the Service Brokers manage and use them in your application. For example, you can easily consume services provided by third-party cloud platforms, such as Azure, AWS, or GCP.
Due to the fact that Kyma runs on Kubernetes, you can easily instantiate a service provided and maintained by a third party. You can consume it without extensive knowledge on clustering of such a service, and without worrying about its upgrades and maintenance. You can also easily provision an instance of the software offering exposed by a Service Broker registered in Kyma and bind it to an application running in the Kyma cluster.
Using the Service Catalog, you can perform the following operations:
- Expose consumable services by listing them with all their details, including documentation and consumption plans.
- Consume services by provisioning them in a given Namespace.
- Bind services to applications.
NOTE: Service Catalog used in Kyma is based on the Service Catalog provided by Kubernetes.
Service Brokers
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:
You can also use Helm Broker addons to install these third-party brokers:
- Azure Service Broker
- AWS Service Broker
- GCP Service Broker
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.
Architecture
Resources
Service Catalog uses a set of custom resources provided either by Kubernetes or by Kyma itself. These are the native Kubernetes resources that Service Catalog uses:
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 a cluster user creates 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.
These are the Service Catalog resources that Kyma provides:
ServiceBindingUsage is a Kyma custom resource that allows Secret injection into a given application.
UsageKind is a Kyma custom resource that defines which resources you can bind to the ServiceBinding and how to bind them.
Basic architecture
The diagram describes the Service Catalog workflow and the roles of specific cluster and Namespace-scoped resources in this process:
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.
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.
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.
The Kyma user creates bindings to the ServiceInstances so that the given applications can access the provisioned services.
Details
Provisioning and binding flow
The diagram shows an overview of interactions between all resources related to the processes of provisioning and binding:
Provision a service
Provisioning a service means creating an instance of a service. To provision a service, create a ServiceInstance custom resource. During this process, the Service Broker creates a new instance of a service. The form and scope of this instance depends on the Service Broker.
Bind a service
Binding is a process of connecting a ServiceInstance and an application. The binding process consists of two parts:
- User creates a ServiceBinding. When you create a ServiceBinding, the Service Catalog creates a Secret with credentials needed to access the application.
- User creates a ServiceBindingUsage. After creating this custom resource, ServiceBindingUsage uses the PodPreset to inject credentials into the application, which allows you to consume the service.
TIP: You can create the ServiceBinding and ServiceBindingUsage resources at the same time.
By default, you can bind a ServiceInstance either to a Deployment or to a Function. Additionally, Kyma provides the UsageKind custom resource, which is a cluster-wide custom resource that allows you to bind a ServiceInstance to any kind of resource. You can add more UsageKinds if you want to bind your ServiceInstance to other types of resources. UsageKind contains information on how the binding to these custom resources is conducted. ServiceBindingUsage uses this information to inject Secrets to the Application.
Unbinding and deprovisioning flow
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.
Configuration
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:
Parameter | Description | Default value |
---|---|---|
controllerManager.resources.requests.cpu | Defines requests for CPU resources. | 100m |
controllerManager.resources.requests.memory | Defines requests for memory resources. | 20Mi |
controllerManager.resources.limits.cpu | Defines limits for CPU resources. | 100m |
controllerManager.resources.limits.memory | Defines limits for memory resources. | 30Mi |
controllerManager.verbosity | Defines log severity level. The possible values range from 0-10. | 10 |
webhook.resources.requests.cpu | Defines requests for CPU resources. | 100m |
webhook.resources.requests.memory | Defines requests for memory resources. | 20Mi |
webhook.resources.limits.cpu | Defines limits for CPU resources. | 100m |
webhook.resources.limits.memory | Defines limits for memory resources. | 30Mi |
webhook.verbosity | Defines log severity level. The possible values range from 0-10. | 10 |
controllerManager.brokerRelistIntervalActivated | Specifies 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.brokerRelistInterval | Specifies how often the controller relists the catalogs of ready brokers. The duration format is 20m, 1h, etc. | 24h |
originatingIdentityEnabled | Enables 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 |
asyncBindingOperationsEnabled | Enables support for asynchronous binding operations. | true |
namespacedServiceBrokerDisabled | Disables support for Namespace-scoped brokers. | false |
securityContext | Gives the opportunity to run container as non-root by setting a securityContext. For example: securityContext: { runAsUser: 1001 } | {} |
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:
Parameter | Description | Default value |
---|---|---|
controller.enabled | Enables the controller-manager which restarts Deployments whenever the PodPreset changes. | false |
webhook.verbosity | Defines log severity level. The possible values range from 0-10. | 6 |
Custom Resource
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:
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. Specify 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 to look like
pref1_var1
, set thepref1_
prefix.
apiVersion: servicecatalog.kyma-project.io/v1alpha1kind: ServiceBindingUsagemetadata: 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
When the ServiceBinding injection fails, the status.conditions.status field is set to False
and the message and reason fields appear. See the example:
- lastTransitionTime: 2018-06-22T17:27:17ZlastUpdateTime: 2018-06-22T17:27:22Zmessage: 'while getting ServiceBinding "redis-instance-credential" from namespace "default": servicebinding.servicecatalog.k8s.io "redis-instance-credential" not found'reason: ServiceBindingGetErrorstatus: "False"type: Ready
The UsageKind that corresponds to this example looks as follows:
apiVersion: servicecatalog.kyma-project.io/v1alpha1kind: UsageKindmetadata: name: deploymentspec: displayName: Deployment resource: group: apps kind: deployment version: v1beta1 labelsPath: spec.template.metadata.labels
NOTE: For more information, see the description of the UsageKind custom resource.
Custom resource parameters
This table lists all the possible parameters of a given resource together with their descriptions:
Parameter | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. |
metadata.namespace | Yes | Specifies the Namespace in which the CR is created. |
metadata.ownerReferences | Yes | Contains the ownerReference to the ServiceBinding specified in the spec.serviceBindingRef.name field, if the binding exists. |
spec.serviceBindingRef.name | Yes | Specifies the name of the ServiceBinding. |
spec.usedBy | Yes | Specifies the application into which the Secret is injected. |
spec.usedBy.kind | Yes | Specifies the name of the corresponding UsageKind custom resource. |
spec.usedBy.name | Yes | Specifies the name of the application into which the Secret is injected. |
spec.parameters.envPrefix | No | Adds a prefix to environment variables injected from the given Secret. The prefixing is disabled by default. |
spec.parameters.envPrefix.name | Yes | Defines the value of the prefix. This field is mandatory if envPrefix is specified. |
status.conditions | No | Defines the status of the ServiceBindingUsage. |
status.conditions.lastTransitionTime | No | Specifies the date when the ServiceBindingUsage Controller processed the ServiceBindingUsage for the first time or when the status.conditions.status field changed. |
status.conditions.lastUpdateTime | No | Specifies the date of the last ServiceBindingUsage condition update. |
status.conditions.status | No | Specifies whether the ServiceBinding injection is successful. |
status.conditions.type | No | Defines the type of the condition. The value of this field is always ready . |
message | No | Provides a human-readable description why the ServiceBinding injection failed. |
reason | No | Specifies a unique, one-word reason for the ServiceBinding injection failure. See the complete list of reasons for more details. |
Related resources and components
These are the resources related to this CR:
Custom resource | Description |
---|---|
UsageKind | Provides information on where to inject Secrets. |
ServiceBinding | Provides Secrets to inject. |
These components use this CR:
Component | Description |
---|---|
ServiceBindingUsage Controller | Reacts to every action of creating, updating, and deleting ServiceBindingUsage resources in all Namespaces and uses ServiceBindingUsage data to inject the binding. |
Console Backend Service | Exposes 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 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/v1alpha1kind: UsageKindmetadata: name: functionspec: 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:
Parameter | Required | Description |
---|---|---|
metadata.name | Yes | Specifies the name of the CR. |
spec.displayName | Yes | Provides a human-readable name of the UsageKind. |
spec.resource | Yes | Specifies a resource which is bound with the ServiceBinding. The target resource is specified by its resource group, kind, and version. |
spec.resource.group | Yes | Specifies the group of the resource. |
spec.resource.kind | Yes | Specifies the kind of the resource. |
spec.resource.version | Yes | Specifies the version of the resource. |
spec.labelsPath | Yes | Specifies a path to the key that contains labels which are later injected into Pods. |
Related resources and components
These are the resources related to this CR:
Custom resource | Description |
---|---|
ServiceBindingUsage | Contains the reference to the UsageKind. |
These components use this CR:
Component | Description |
---|---|
ServiceBindingUsage Controller | Uses the UsageKind spec.resource and spec.labelsPath parameters to find a resource and path to which it should inject Secrets. |
Console Backend Service | Exposes the given CR to the Console UI. |
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"]
Tutorials
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
Clone the
service-catalog
repository:Click to copygit clone https://github.com/kubernetes-incubator/service-catalog.gitCheck out one of the official tags. For example:
Click to copygit fetch --all --tags --prunegit checkout tags/v0.1.39 -b v0.1.39Create the
ups-broker
Namespace:Click to copykubectl create namespace ups-brokerRun this command to install the chart with the
ups-broker
name in theups-broker
Namespace:Click to copyhelm install ups-broker ./charts/ups-broker --namespace ups-brokerRegister a broker:
- Run this command to register a ClusterServiceBroker:Click to copykubectl create -f ./contrib/examples/walkthrough/ups-clusterservicebroker.yaml
- To register the UPS Broker as a ServiceBroker in the
ups-broker
Namespace, run:After you successfully register your ServiceBroker or ClusterServiceBroker, the Service Catalog periodically fetches services from this broker and creates ServiceClasses or ClusterServiceClasses from them.Click to copykubectl create -f ./contrib/examples/walkthrough/ups-servicebroker.yaml -n ups-broker
- Check the status of your broker:
- To check the status of your ClusterServiceBroker, run:Click to copykubectl get clusterservicebrokers ups-broker -o jsonpath="{.status.conditions}"
To check the status of the ServiceBroker, run:
Click to copykubectl 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"}
- View ServiceClasses that this broker provides:
- To check the ClusterServiceClasses, run:Click to copykubectl get clusterserviceclasses
To check the ServiceClasses, run:
Click to copykubectl get serviceclasses -n ups-brokerThese are the UPS Broker ServiceClasses:
Click to copyNAME EXTERNAL NAME4f6e6cf6-ffdd-425f-a2c7-3c9258ad2468 user-provided-service5f6e6cf6-ffdd-425f-a2c7-3c9258ad2468 user-provided-service-single-plan8a6229d4-239e-4790-ba1f-8367004d0473 user-provided-service-with-schemas
Console UI Views
UI Contracts
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 ServiceClass that has only the mandatory fields. However, it is recommended to provide more detailed ServiceClass 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:
Number | OSBA field | Fallbacks | Description |
---|---|---|---|
(1) | metadata.displayName | name*, id* | If metadata.displayName, name, or id fields are not present, a given ServiceClass 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.
Catalog Details page
These are the OSBA fields used in the detailed ServiceClass view:
Number | OSBA field | Fallbacks | Description |
---|---|---|---|
(1) | metadata.displayName | name*, 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.longDescription | description* | If not provided, the General Information panel does not appear. |
(8) | not related to OSBA | - | - |
*Fields with an asterisk are required OSBA attributes.
Add to Namespace
These are the OSBA fields used in the Add to Namespace window:
Number | OSBA field | Fallbacks | Description |
---|---|---|---|
(1) | plan.metadata.displayName | plan.name*, plan.id* | |
(2) | not related to OSBA | - | |
(3) | not related to OSBA | - |
*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.
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:
Number | OSBA field | Fallbacks | Description | |
---|---|---|---|---|
(1) | not related to OSBA | - | It is the name of the Service Instance, created during service provisioning. | |
(2) | metadata.displayName | name*, id* | If not provided, UI does not display this information. | |
(3) | plan.metadata.displayName | plan.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.
Service Instance Details page
These are the OSBA fields used in the detailed Service Instance view:
Number | OSBA field | Fallbacks | Description |
---|---|---|---|
(1) | metadata.displayName | name*, id* | - |
(2) | plan.metadata.displayName | plan.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.
Specifications in the Console UI
Documentation for ServiceClasses is rendered in both Service Catalog and Instances views. It includes the following specification types:
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 sametype
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:
- Metadata source
- Service Catalog UI preview
NOTE: A document with the Overview
title
always displays as the first tab. Markdown files withtitle
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:
Linking - link between documents in the same topic or in different topics using metadata.
- Source
- Preview
Documentation toggles - render several versions of a given section in one document or have several versions of one document.
- Source
- Preview
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.