1. Documentation
×

Service Catalog

Overview

When developing microservices-based applications to run on cloud native platforms, there are many ways to provision different resources and share their coordinates, credentials, and configuration, depending on the service provider and the platform.

To give developers a more seamless experience, OKD includes a service catalog, an implementation of the Open Service Broker API (OSB API) for Kubernetes. This allows users to connect any of their applications deployed in OKD to a wide variety of service brokers.

The service catalog allows cluster administrators to integrate multiple platforms using a single API specification. The OKD web console displays the cluster service classes offered by service brokers in the service catalog, allowing users to discover and instantiate those services for use with their applications.

As a result, service users benefit from ease and consistency of use across different types of services from different providers, while service providers benefit from having one integration point that gives them access to multiple platforms.

Design

The design of the service catalog follows this basic workflow:

New terms in the following are defined further in Concepts and Terminology.
Service Catalog Architecture
1 A cluster administrator registers one or more cluster service brokers with their OKD cluster. This can be done automatically during installation for some default-provided service brokers or manually.
2 Each service broker specifies a set of cluster service classes and variations of those services (service plans) to OKD that should be made available to users.
3 Using the OKD web console or CLI, users discover the services that are available. For example, a cluster service class may be available that is a database-as-a-service called BestDataBase.
4 A user chooses a cluster service class and requests a new instance of their own. For example, a service instance may be a BestDataBase instance named my_db.
5 A user links, or binds, their service instance to a set of pods (their application). For example, the my_db service instance may be bound to the user’s application called my_app.

When a user makes a request to provision or deprovision a resource, the request is made to the service catalog, which then sends a request to the appropriate cluster service broker. With some services, some operations such as provision, deprovision, and update are expected to take some time to fulfill. If the cluster service broker is unavailable, the service catalog will continue to retry the operation.

This infrastructure allows a loose coupling between applications running in OKD and the services they use. This allows the application that uses those services to focus on its own business logic while leaving the management of these services to the provider.

Deleting Resources

When a user is done with a service (or perhaps no longer wishes to be billed), the service instance can be deleted. In order to delete the service instance, the service bindings must be removed first. Deleting the service bindings is known as unbinding. Part of the deletion process includes deleting the secret that references the service binding being deleted.

Once all the service bindings are removed, the service instance may be deleted. Deleting the service instance is known as deprovisioning.

If a project or namespace containing service bindings and service instances is deleted, the service catalog must first request the cluster service broker to delete the associated instances and bindings. This is expected to delay the actual deletion of the project or namespace since the service catalog must communicate with cluster service brokers and wait for them to perform their deprovisioning work. In normal circumstances, this may take several minutes or longer depending on the service.

If you delete a service binding used by a deployment, you must also remove any references to the binding secret from the deployment. Otherwise, the next rollout will fail.

Concepts and Terminology

Cluster Service Broker

A cluster service broker is a server that conforms to the OSB API specification and manages a set of one or more services. The software could be hosted within your own OKD cluster or elsewhere.

Cluster administrators can create ClusterServiceBroker API resources representing cluster service brokers and register them with their OKD cluster. This allows cluster administrators to make new types of managed services using that cluster service broker available within their cluster.

A ClusterServiceBroker resource specifies connection details for a cluster service broker and the set of services (and variations of those services) to OKD that should then be made available to users. Of special note is the authInfo section, which contains the data used to authenticate with the cluster service broker.

Example ClusterServiceBroker Resource
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ClusterServiceBroker
metadata:
  name: BestCompanySaaS
spec:
  url: http://bestdatabase.example.com
  authInfo:
    basic:
      secretRef:
        namespace: test-ns
        name: secret-name
Cluster Service Class

Also synonymous with "service" in the context of the service catalog, a cluster service class is a type of managed service offered by a particular cluster service broker. Each time a new cluster service broker resource is added to the cluster, the service catalog controller connects to the corresponding cluster service broker to obtain a list of service offerings. A new ClusterServiceClass resource is automatically created for each.

OKD also has a core concept called services, which are separate Kubernetes resources related to internal load balancing. These resources are not to be confused with how the term is used in the context of the service catalog and OSB API.
Example ClusterServiceClass Resource
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ClusterServiceClass
metadata:
  name: smallDB
  brokerName: BestDataBase
  plans: [...]
Cluster Service Plan

A cluster service plan represents tiers of a cluster service class. For example, a cluster service class may expose a set of plans that offer varying degrees of quality-of-service (QoS), each with a different cost associated with it.

Service Instance

A service instance is a provisioned instance of a cluster service class. When a user wants to use the capability provided by a service class, they can create a new service instance.

When a new ServiceInstance resource is created, the service catalog controller connects to the appropriate cluster service broker and instructs it to provision the service instance.

Example ServiceInstance Resource
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceInstance
metadata:
  name: my_db
  namespace: test-ns
spec:
  externalClusterServiceClassName: smallDB
  externalClusterServicePlanName: default
Application

The term application refers to the OKD deployment artifacts, for example pods running in a user’s project, that will use a service instance.

Credentials

Credentials are information needed by an application to communicate with a service instance.

Service Binding

A service binding is a link between a service instance and an application. These are created by cluster users who wish for their applications to reference and use a service instance.

Upon creation, the service catalog controller creates a Kubernetes secret containing connection details and credentials for the service instance. Such secrets can be mounted into pods as usual.

Example ServiceBinding Resource
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceBinding
metadata:
  name: myBinding
  namespace: test-ns
spec:
  instanceRef:
    name: my_db
  parameters:
    securityLevel: confidential
  secretName: mySecret

Users should not use the web console to change the prefix of environment variables for instantiated instances, as it can cause application routes to become inaccessible.
Parameters

A parameter is a special field available to pass additional data to the cluster service broker when using either service bindings or service instances. The only formatting requirement is for the parameters to be valid YAML (or JSON). In the above example, a security level parameter is passed to the cluster service broker in the service binding request. For parameters that need more security, place them in a secret and reference them using parametersFrom.

Example Service Binding Resource Referencing a Secret
apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceBinding
metadata:
  name: myBinding
  namespace: test-ns
spec:
  instanceRef:
    name: my_db
  parametersFrom:
    - secretKeyRef:
        name: securityLevel
        key: myKey
  secretName: mySecret

Provided Cluster Service Brokers

OKD provides the following cluster service brokers for use with the service catalog.