Skip to content

Register a Component

Preface

This how-to will take you through the steps of registering a Component with the developer portal using one of the Git discovery locations.

Get a Repository

To begin, you will need to create or clone a repository in or from one of the Git discovery locations, such that they are available to entity ingress.

Discovery Locations

  • github.com/DiamondLightSource
    • Entity descriptors at /catalog-info.yaml
  • gitlab.diamond.ac.uk
    • Entity descriptors at /catalog-info.yaml

Create an Entity Descriptor

Firstly, we must create the entity descriptor file, please reference the Discovery Locations above for the appropriate location - this is typically catalog-info.yaml at the root of the repository.

Entity Definition

To begin, we will specify the apiVersion to be backstage.io/v1alpha1 and the kind as Component.

Example

apiVersion: backstage.io/v1alpha1
kind: Component

Metadata

Next, we will fill out the metadata, this is common to all entity types. Only the name field is required with numerous other optional fields available. It is recommended that you enter a title and a description. Complete field descriptions are available in the metadata reference.

Example

metadata:
  name: developer-portal-backend
  title: Developer Portal Backend
  description: A node application performing discovery and providing the developer portal REST API.

Component Spec

Finally, we will fill out the spec. Only the type field is required with numerous other optional fields available. It is recommended that you enter a lifecycle and an owner. Complete field descriptions are available in the Component spec reference.

Example

spec:
  type: service
  lifecycle: experimental
  owner: user:enu43627

Example Complete Descriptor

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
    name: developer-portal-backend
    title: Developer Portal Backend
    description: A node application performing discovery and providing the developer portal REST API.
spec:
    type: website
    lifecycle: experimental
    system: developer-portal
    owner: user:enu43627
    dependsOn:
        - component:developer-guide
    providesApis:
        - developer-portal-backend-rest

Push & Wait

Now we have created our entity decriptor in the form of a catalog-info.yaml we can push it to one of the discovery locations and wait for the developer portal to discover it - be aware that this may take a while depending on the schedule of the discovery provider.