Headless CMS

Overview

The Headless CMS is a new breed of traditional Content Management Systems (CMS) that provides a way of storing and managing raw content, and exposing it through an API. It allows you to pull the content into your own application and tailor it to your needs, delivering it in any format, on any device. Contrary to the traditional CMS, such as WordPress, the Headless CMS does not provide a display layer and ready-to-use templates. Instead, it only ensures a database backend. It gives flexibility on the choice of the frontend, thus cutting the default "head" off the traditional CMS solutions.

Headless CMS in Kyma

Kyma provides a Kubernetes-based solution that relies on the custom resource (CR) extensibility feature and the Asset Store as a backend mechanism. The Headless CMS in Kyma allows you to upload multiple and grouped data for a given documentation topic and store them as Asset CRs in Minio buckets. All you need to do is to specify all topic details, such as documentation sources, in a DocsTopic CR or a ClusterDocsTopic CR and apply it to a given Namespace or a cluster. The CR supports various documentation formats, including images, Markdown documents, AsyncAPI, OData, and OpenAPI specification files. You can upload them as single (direct file URLs) and packed assets (ZIP or TAR).

Benefits

The Headless CMS brings a number of benefits:

  • It provides a unified way of uploading different document types to a Kyma cluster.
  • It fits into the Kyma modularity concept as you load onto a cluster only documentation for the installed components. This is possible as the DocsTopic CR and the code for a given component are located in the same place in the kyma repository.
  • It supports baked-in documentation. Apart from the default documentation, you can add your own and group it as you like, the same way you use micro frontends to personalize views in the Console UI. For example, you can add contextual help for a given Service Broker in the Service Catalog.

Architecture

Resources

The Headless CMS in Kyma consists of these components:

  • DocsTopic custom resource (CR) orchestrates the creation of multiple Asset CRs for a specific documentation topic in a given Namespace. It has a cluster-wide counterpart called ClusterDocsTopic CR.

  • DocsTopic Controller creates Asset custom resources (CRs) based on the DocsTopic CR definition. If the DocsTopic CR defines two sources of documentation topics, such as asyncapi and markdown, the DocsTopic Controller creates two Asset CRs. The DocsTopic Controller also monitors the status of the Asset CR and updates the status of the DocsTopic CR accordingly.

Headless CMS flow

See the diagram for an overview of the basic Headless CMS workflow.

NOTE: This flow also applies to the ClusterDocsTopic CR.

  1. The Kyma user creates a DocsTopic CR in a given Namespace.
  2. The DocsTopic Controller reads the DocsTopic CR definition.
  3. The DocsTopic Controller checks if the Bucket CR already exists in this Namespace. If it does not exist yet, the DocsTopic Controller creates a new Bucket CR with the cms-public-{suffix} name, where {suffix} is a randomly generated string.
  4. The DocsTopic Controller creates Asset CRs in the number corresponding to the number of sources specified in the DocsTopic CR. It adds cms.kyma-project.io/type and cms.kyma-project.io/docs-topic labels to every Asset CR definition. It also adds the bucket name under the bucketRef field to every Asset CR definition.
  5. The DocsTopic Controller verifies if the Asset CRs are in the Ready phase and updates the status of the DocsTopic CR accordingly.

Details

Headless CMS in the Console

Headless CMS in Kyma is a separate component and does not provide templates or a standalone UI to display content from the CMS. Still, the Console UI displays some of the assets in the Docs view (generic and component-related documentation) and the Service Catalog views (API specifications).

Add a new documentation topic to the Console UI by creating a CR, while the Asset Store handles the rest. Define the location, grouping, and order of the documents through DocsTopic and ClusterDocsTopic labels that you add to the custom resource definition. You can create your own labels and follow your own naming convention, but cms.kyma-project.io/{label-name} applies to the Console UI.

Use these labels to mark and filter assets in the Console UI:

  • cms.kyma-project.io/view-context specifies the location in the Console UI to render the given asset. This can be either docs-ui or service-catalog.
  • cms.kyma-project.io/group-name defines the group, such as components, under which you want to render the given asset under the docs-ui view in the Console UI. The value cannot include spaces.
  • cms.kyma-project.io/order specifies the position of the DocsTopic and ClusterDocsTopic in relation to other DocsTopics under the docs-ui view in the Console UI. For example, this can be 4.

DocsTopic custom resource lifecycle

NOTE: This lifecycle also applies to the ClusterDocsTopic CR.

Asset CR manual changes

The DocsTopic custom resource (CR) coordinates Asset CR creation, deletion, and modifications. The DocsTopic Controller verifies DocsTopic definition on a regular basis and creates, deletes, or modifies Assets CRs accordingly.

The DocsTopic CR acts as the only source of truth for the Asset CRs it orchestrates. If you modify or remove any of them manually, DocsTopic Controller automatically overwrites such an Asset CR or updates it based on the DocsTopic CR definition.

DocsTopic CR and Asset CR dependencies

Asset CRs and DocsTopic CRs are also interdependent in terms of names, definitions, and statuses.

Names

The name of every Asset CR created by the DocsTopic Controller consists of these three elements:

  • The name of the DocsTopic CR, such as service-catalog.
  • The source type of the given asset in the DocsTopic CR, such as asyncapi.
  • A randomly generated string, such as 1b38grj5vcu1l.

The full name of such an Asset CR that follows the {docsTopic-name}-{asset-source}-{suffix} pattern is service-catalog-asyncapi-1b38grj5vcu1l.

Labels

There are two labels in every Asset CR created from DocsTopic CRs. Both of them are based on DocsTopic CRs definitions:

  • cms.kyma-project.io/type equals a given type parameter from the DocsTopic CR, such as asyncapi.

  • cms.kyma-project.io/docs-topic equals the name metadata from the DocsTopic CR, such as service-catalog.

Statuses

The status of the DocsTopic CR depends heavily on the status phase of all Asset CRs it creates. It is:

  • Ready when all related Asset CRs are already in the Ready phase.
  • Pending when it awaits the confirmation that all related Asset CRs are in the Ready phase. If any Asset CR is in the Failed phase, the status of the DocsTopic CR remains Pending.
  • Failed when processing of the DocsTopic CR fails. For example, the DocsTopic CR can fail if you provide incorrect or duplicated data in its specification.

Custom Resource

DocsTopic

The docstopics.cms.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to define an orchestrator that creates Asset CRs for a specific asset type. To get the up-to-date CRD and show the output in the yaml format, run this command:

Click to copy
kubectl get crd docstopics.cms.kyma-project.io -o yaml

Sample custom resource

This is a sample DocsTopic custom resource (CR) that provides details of the Asset CRs for the markdown, asyncapi, and openapi source types.

Click to copy
apiVersion: cms.kyma-project.io/v1alpha1
kind: DocsTopic
metadata:
name: slack
labels:
cms.kyma-project.io/view-context: service-catalog
spec:
displayName: Slack
description: "Slack documentation"
sources:
- type: markdown
name: markdown-slack
mode: single
url: https://raw.githubusercontent.com/slackapi/slack-api-specs/master/README.md
- type: asyncapi
name: asyncapi-slack
mode: single
url: https://raw.githubusercontent.com/slackapi/slack-api-specs/master/events-api/slack_events_api_async_v1.json
- type: openapi
name: openapi-slack
mode: single
url: https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json
status:
lastHeartbeatTime: "2019-03-18T13:42:55Z"
message: Assets are ready to use
phase: Ready
reason: AssetsReady

Custom resource parameters

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

ParameterMandatoryDescription
metadata.nameYESSpecifies the name of the CR. It also defines the cms.kyma-project.io/docs-topic label added to the Asset CR that the DocsTopic CR defines. Because of label name limitations, DocsTopic CR names can have a maximum length of 63 characters.
metadata.labelsNOSpecifies how to filter and group Asset CRs that the DocsTopic CR defines. See this document for more details.
spec.displaynameYESSpecifies a human-readable name of the DocsTopic CR.
spec.descriptionYESProvides more details on the purpose of the DocsTopic CR.
spec.sourcesYESDefines the type of the asset and the cms.kyma-project.io/type label added to the Asset CR.
spec.sources.typeYESSpecifies the type of assets included in the DocsTopic CR.
spec.sources.nameYESDefines an identifier of a given asset. It must be unique if there is more than one asset of a given type in a DocsTopic CR.
spec.sources.modeYESSpecifies if the asset consists of one file or a set of compressed files in the ZIP or TAR format. Use single for one file and package for a set of files.
spec.sources.urlYESSpecifies the location of a single file or a package.
spec.sources.filterNOSpecifies a set of assets from the package to upload. The regex used in the filter must be RE2-compliant.
status.lastheartbeattimeNot applicableProvides the last time when the DocsTopic Controller processed the DocsTopic CR.
status.messageNot applicableDescribes a human-readable message on the CR processing progress, success, or failure.
status.phaseNot applicableThe DocsTopic Controller adds it to the DocsTopic CR. It describes the status of processing the DocsTopic CR by the DocsTopic Controller. It can be Ready, Pending, or Failed.
status.reasonNot applicableProvides the reason why the DocsTopic CR processing succeeded, is pending, or failed.

NOTE: The DocsTopic Controller automatically adds all parameters marked as Not applicable to the DocsTopic CR.

These are the resources related to this CR:

Custom resourceDescription
AssetThe DocsTopic CR orchestrates the creation of the Asset CR and defines its content.

These components use this CR:

ComponentDescription
Asset StoreManages Asset CRs created based on the definition in the DocsTopic CR.

ClusterDocsTopic

The clusterdocstopics.cms.kyma-project.io CustomResourceDefinition (CRD) is a detailed description of the kind of data and the format used to define an orchestrator that creates ClusterAsset CRs for a specific asset type. To get the up-to-date CRD and show the output in the yaml format, run this command:

Click to copy
kubectl get crd clusterdocstopics.cms.kyma-project.io -o yaml

Sample custom resource

This is a sample ClusterDocsTopic custom resource (CR) that provides details of the ClusterAsset CR for the markdown source type.

Click to copy
apiVersion: cms.kyma-project.io/v1alpha1
kind: ClusterDocsTopic
metadata:
name: service-mesh
labels:
cms.kyma-project.io/view-context: docs-ui
cms.kyma-project.io/group-name: components
cms.kyma-project.io/order: "6"
spec:
displayName: "Service Mesh"
description: "Overall documentation for Service Mesh"
sources:
- type: markdown
name: docs
mode: package
url: https://github.com/kyma-project/kyma/archive/master.zip
filter: /docs/service-mesh/docs/
status:
lastHeartbeatTime: "2019-03-18T13:42:55Z"
message: Assets are ready to use
phase: Ready
reason: AssetsReady

Custom resource parameters

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

ParameterMandatoryDescription
metadata.nameYESSpecifies the name of the CR. It also defines the cms.kyma-project.io/docs-topic label added to the ClusterAsset CR that the ClusterDocsTopic CR defines. Because of label name limitations, ClusterDocsTopic CR names can have a maximum length of 63 characters.
metadata.labelsNOSpecifies how to filter and group ClusterAsset CRs that the ClusterDocsTopic CR defines. See this document for more details.
spec.displaynameYESSpecifies a human-readable name of the ClusterDocsTopic CR.
spec.descriptionYESProvides more details on the purpose of the ClusterDocsTopic CR.
spec.sourcesYESDefines the type of the asset and the cms.kyma-project.io/type label added to the ClusterAsset CR.
spec.sources.typeYESSpecifies the type of assets included in the ClusterDocsTopic CR.
spec.sources.nameYESDefines a unique identifier of a given asset. It must be unique if there is more than one asset of a given type in a ClusterDocsTopic CR.
spec.sources.modeYESSpecifies if the asset consists of one file or a set of compressed files in the ZIP or TAR format. Use single for one file and package for a set of files.
spec.sources.urlYESSpecifies the location of a single file or a package.
spec.sources.filterNOSpecifies a set of assets from the package to upload. The regex used in the filter must be RE2-compliant.
status.lastheartbeattimeNot applicableProvides the last time when the DocsTopic Controller processed the ClusterDocsTopic CR.
status.messageNot applicableDescribes a human-readable message on the CR processing progress, success, or failure.
status.phaseNot applicableThe DocsTopic Controller adds it to the ClusterDocsTopic CR. It describes the status of processing the ClusterDocsTopic CR by the DocsTopic Controller. It can be Ready, Pending, or Failed.
status.reasonNot applicableProvides the reason why the ClusterDocsTopic CR processing succeeded, is pending, or failed.

NOTE: The DocsTopic Controller automatically adds all parameters marked as Not applicable to the ClusterDocsTopic CR.

These are the resources related to this CR:

Custom resourceDescription
ClusterAssetThe ClusterDocsTopic CR orchestrates the creation of the ClusterAsset CR and defines its content.

These components use this CR:

ComponentDescription
Asset StoreManages ClusterAsset CRs created based on the definition in the ClusterDocsTopic CR.