Log in

Onboarding Software to Backstage

45 MINS

Creating a software component

Let’s add an entity of your own to the catalog; preferably an existing service owned by your team.

  1. In the code repository for the service, create a new file catalog-info.yaml at the repository’s root.

  2. Paste the following contents:

<span class="line"><span style="color:#B392F0">apiVersion:</span><span style="color:#9ECBFF"> backstage.io/v1alpha1</span></span>
<span class="line"><span style="color:#B392F0">kind:</span><span style="color:#9ECBFF"> Component</span></span>
<span class="line"><span style="color:#B392F0">metadata:</span></span>
<span class="line"><span style="color:#B392F0">  name:</span><span style="color:#9ECBFF"> replace-me</span></span>
<span class="line"><span style="color:#B392F0">  description:</span><span style="color:#9ECBFF"> Replace</span><span style="color:#9ECBFF"> me</span><span style="color:#9ECBFF"> with</span><span style="color:#9ECBFF"> a</span><span style="color:#9ECBFF"> real</span><span style="color:#9ECBFF"> description.</span></span>
<span class="line"><span style="color:#B392F0">  tags:</span></span>
<span class="line"><span style="color:#B392F0">    -</span><span style="color:#9ECBFF"> go</span></span>
<span class="line"><span style="color:#B392F0">    -</span><span style="color:#9ECBFF"> website</span></span>
<span class="line"><span style="color:#B392F0">spec:</span></span>
<span class="line"><span style="color:#79B8FF">  type</span><span style="color:#9ECBFF">:</span><span style="color:#9ECBFF"> service</span></span>
<span class="line"><span style="color:#B392F0">  lifecycle:</span><span style="color:#9ECBFF"> production</span></span>
<span class="line"><span style="color:#B392F0">  owner:</span><span style="color:#9ECBFF"> your-team</span></span>
<span class="line"></span>

  1. Update metadata.name - with a version of your service’s name that only includes lowercase, alpha-numeric characters and dashes

  2. Update metadata.description - a human-readable description of your service

  3. Update spec.owner - with your team’s name

💡 If your company already has metadata files in a different format, you can write a catalog processor to ingest those and translate to Backstage’s entity format.

  1. Commit and push this file up to your version control system and ensure it’s available in the default branch (e.g. main or master).

  2. Navigate to this catalog-info.yaml file in the web interface of your VCS and copy the URL. e.g. https://github.com/backstage/backstage/blob/master/catalog-info.yaml