Skip to content

Link to Remote Entities

Preface

This how-to will take you through the steps of registering multiple entities in the catalogue, where the entitiy descriptors are remotely located.

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 Referenced Descriptors

It is nessacary to create a number of regular entities (e.g. Components or APIs) before we can register them together. This may be performed as explained in Register a Component or Register a Static API. Instead of their usual locations, these files should be given names and located in directories appropriate to the entity they register. For example, the entity descriptor for my-component may be located at my-component/catalog-info.yamlorcatalog-info/my-component.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.

To begin, we will specify the apiVersion to be backstage.io/v1alpha1 and the kind as Location. E.g.:

Entity Definition

Example

1
2
apiVersion: backstage.io/v1alpha1
kind: Location

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

1
2
3
4
metadata:
name: developer-portal
title: Developer Portal
description: The diamond developer portal.

Location Spec

Finally, we will fill out the spec. Only the targets field is required with numerous other optional fields available. Complete field descriptions are available in the Location spec reference.

Important

The location type is intentionally left blank such that the discovery process is inherited from whichever discovery process indexed this location.

Example

1
2
3
4
5
6
spec:
targets:
    - ./catalog-info/system.yaml
    - ./catalog-info/frontend.yaml
    - ./catalog-info/backend.yaml
    - ./catalog-info/backend-rest.yaml
Example Completed Descriptor 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
    name: developer-portal
    description: A RESTful API exposed by the developer portal backend.
spec:
    targets:
        - ./catalog-info/system.yaml
        - ./catalog-info/frontend.yaml
        - ./catalog-info/backend.yaml
        - ./catalog-info/backend-rest.yaml

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.