Your First Service

A “service” in KDP defines a unique Kubernetes API Group and offers a number of resources (types) to use. A service could offer certificate management, databases, cloud infrastructure or any other set of Kubernetes resources.

Services are provided by service owners, who run their own Kubernetes clusters and take care of the maintenance and scaling tasks for the workload provisioned by all users of the service(s) they offer.

A KDP Service should not be confused with a Kubernetes Service. Internally, a KDP Service is ultimately translated into a kcp APIExport with a number of APIResourceSchemas (~ CRDs).

Scope

This document describes the process of setting up a new Service from scratch, from the standpoint of a Service Owner. See Using Services for more information from the standpoint of Service Consumers (i.e. endusers).

Creating Services

Login to the KDP Dashboard and navigate to the organization where the Service should be available (generally, Services can be consumed from any other workspace). Choose the “Create Service” option.

First, choose a title. This is a “human readable” name for your Service and will be shown to potential consumers in the service catalog. Next, choose a unique API group. API groups are DNS-style names, so it is recommended to choose a sub-domain of a DNS name you actually control (e.g. databases.services.kubermatic.com).

You must also choose the location to which the api-syncagent kubeconfig secret is written. This secret is required to set up the api-syncagent later.

The service creation wizard also offers several optional metadata fields that will help service consumers understand what kind of services are offered. You can (optionally) provide a documentation link which will be shown to consumers as a way to discover more information about the service, a logo which will be displayed alongside the service in the service catalog and a markdown-capable description to convey what the service is about.

Via API

It is of course also possible to create services from the kcp API directly via kubectl or similar tools (useful when the service should be managed via GitOps, for example). Here is an example YAML specification:

apiVersion: core.kdp.k8c.io/v1alpha1
kind: Service
metadata:
  name: sample.example.com
spec:
  apiGroup: sample.example.com
  catalogMetadata:
    description: This is a sample service.
    documentationURL: ""
    title: sample-service
  kubeconfig:
    name: sample-api-syncagent-kubeconfig
    namespace: default

This can be applied with kubectl in your organization workspace.

$ kubectl ws :root:my-org       # switch to your workspace
$ kubectl apply -f service.yaml

Use the following command to explore the full schema for Service objects:

$ kubectl explain --api-version=core.kdp.k8c.io/v1alpha1 service

This concludes all required steps to define the new service. Click on the confirm button to create the Service.

Setting up the api-syncagent

Once the service is created, KDP will provision a kubeconfig. This kubeconfig is meant to be used by the api-syncagent, the component installed by service owners into the service cluster.

The generated kubeconfig is available from the service’s context menu in the Dashboard.

Click “kubeconfig” to inspect and download the kubeconfig:

You can also use kubectl to navigate into your workspace and inspect your Service object. In spec.kubeconfig you will find the name of the kubeconfig Secret that you can use for your api-syncagent.

Now switch your focus to your own cluster, where your business logic happens (for example where Crossplane runs). For your Service you need to provide exactly one api-syncagent in one Kubernetes cluster. This agent can have multiple replicas as it uses leader election, but you must not have two or more independent agents processing the same Service. There is currently no mechanism to spread load between multiple Service clusters and two or more agents will most likely conflict with each other.

The api-syncagent comes as a Helm chart. See the kcp chart repository for more information. You basically need to provide the kubeconfig generated by KDP as the “kcp kubeconfig”, the service’s name (not its API Group) and a unique name for the agent itself. Put all the information in a values.yaml and run helm install to deploy your agent.

Once the agent has booted up, it will just sit there and do nothing, waiting for further configuration.

Defining Published Resources

Once the api-syncagent is up and running, you have to create PublishedResource objects on the service cluster. See the documentation for publishing resources for more information.

The agent will automatically react to PublishedResources and begin replicating them into KDP/kcp. This means setting up an APIExport and APIResourceSchemas. Once this is done, the KDP Service can actually be consumed on the platform. See Using Services for more information.