Register a Resource

Preface

This how-to will take you through the steps of registering a Resource 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 Resource.

Example

apiVersion: backstage.io/v1alpha1
kind: Resource

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-make-believe-database
    title: Developer Portal Make Believe Database
    description: A database that I just made up to use as an example, it probably contains things.

Resource Spec

Finally, we will fill out the spec. The type and owner fields are required with numerous other optional fields available. Complete field descriptions are available in the Resource spec reference.

Example

spec:
  type: database
  owner: user:enu43627

Example Complete Descriptor

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
    name: developer-portal-make-believe-database
    title: Developer Portal Make Believe Database
    description: A database that I just made up to use as an example, it probably contains things.
spec:
    type: database
    system: developer-portal
    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.