Register a System

Preface

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

Tip

A lone System entity does not add significant value, therefore it is expected that other entities (e.g. Components or APIs) will be attached to it via their spec.system field.

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 System. E.g.:

Example

apiVersion: backstage.io/v1alpha1
kind: System

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
  title: Developer Portal
  description: The diamond developer portal.

System Spec

Finally, we will fill out the spec. There are no required fields here. However it is recommended that you enter an owner. Complete field descriptions are available in the System spec reference.

Example

spec:
  owner: user:enu43627

Example Completed Descriptor

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
    name: developer-portal
    title: Developer Portal
    description: The diamond developer portal.
spec:
    owner: user:enu43627

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.