Skip to content

Latest commit

 

History

History
216 lines (164 loc) · 8.07 KB

catalog-operations.md

File metadata and controls

216 lines (164 loc) · 8.07 KB
Raw

Catalog operations

The software catalog setup procedures in this topic make use of Backstage. For more information about Backstage, see the Backstage documentation.

Adding catalog entities

This section describes how you can format your own catalog. Creating catalogs consists of building meta data YAML files stored together with the code. This information is read from a Git-compatible repository consisting of these YAML catalog definition files. Changes made to the catalog definitions on your Git infrastructure are automatically reflected every 200 seconds or when manually registered. For each catalog entity kind you create, there is a file format you must follow. Below is an overview of a few core entities, here are details about all types of entities. You can use the example Blank Catalog to create user, group, system, and main component YAML files.

Relationship Diagram: Tanzu Application Platform GUI Relationships

Users and groups

A User entity describes a specific person and is used for identity purposes. A Group entity describes an organizational team or unit. Users are members of one or more Groups.

The descriptor files for both require values for apiVersion, kind, metadata.name. Users also require spec.memberOf. Groups require spec.type and spec.children, where spec.children is another Group. To link a logged in user to a user entity, include the optional spec.profile.email field.

Sample user entities:

apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: default-user
spec:
  profile:
    displayName: Default User
    email: guest@example.com
    picture: https://avatars.dicebear.com/api/avataaars/guest@example.com.svg?background=%23fff
  memberOf: [default-team]

Sample group entities:

apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: default-team
  description: Default Team
spec:
  type: team
  profile:
    displayName: Default Team
    email: team-a@example.com
    picture: https://avatars.dicebear.com/api/identicon/team-a@example.com.svg?background=%23fff
  parent: default-org
  children: []

More information about user entities and group entities is available in Backstage documentation.

Systems

A System entity is a collection of resources and components. System descriptor files require values for apiVersion, kind, metadata.name, and spec.owner, where spec.owner is a User or Group. A system has components belonging to it when that component specifies the System name in the field spec.system.

Sample system entity

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: backstage
  description: Tanzu Application Platform GUI System
spec:
  owner: default-team

More information about system entities is available in Backstage documentation.

Components

A Component describes a software component, or a "unit of software". Component descriptor files require values for apiVersion, kind, metadata.name, spec.type, spec.lifecycle, and spec.owner. Some useful optional fields are spec.system and spec.subcomponentOf, both of which links a Component to an entity it is a part of.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: backstage-component
  description: Tanzu Application Platform GUI Component
  annotations:
    'backstage.io/kubernetes-label-selector': 'app=backstage' #Identifies the Kubernetes objects that make up this component
    'backstage.io/techdocs-ref': dir:. #TechDocs label
spec:
  type: service
  lifecycle: alpha
  owner: default-team
  system: backstage

More information about component entities is available in Backstage documentation.

Update software catalogs

The following procedures cover updating software catalogs.

Register components

You can update your software catalog with new entities without re-deploying the entire tap-gui package. To do so: ​

  1. Navigate to your Software Catalog page.
  2. Click the Register Entity on the top-right of the page.
  3. Link to an existing entity file to start tracking your entity by entering the full path.
  4. Import the entities and view them in your Software Catalog page. ​

Deregister components

To deregister an entity, follow these steps:

  1. Navigate to your Software Catalog page.
  2. Select the entity to deregister, such as component, group, or user.
  3. Click the three dots at the top-right of the page and then click Unregister....

Add or change organization catalog locations

  1. Use static configuration to add or change catalog locations:

    • To update components, change the catalog location in either the app_config section of tap-gui-values.yaml or the custom values file you used when installing. For example:

      catalog:
  locations:
    - type: url
      target: UPDATED-CATALOG-LOCATION

    • To register components, add the new catalog's location in either the app_config section of tap-gui-values.yaml or the custom values file you used when installing. For example:

      catalog:
  locations:
    - type: url
      target: EXISTING-CATALOG-LOCATION
    - type: url
      target: EXTRA-CATALOG-LOCATION

    When targeting GitHub, don't write the raw URL. Instead, use the URL that you see when you navigate to the file in the browser, otherwise the catalog processor is unable to properly set up the files.

    For example:

    • Raw URL: https://raw.githubusercontent.com/user/repo/catalog.yaml
    • Target URL: https://github.com/user/repo/blob/main/catalog.yaml

    For more information about static catalog configuration, see the Backstage documentation.

  2. Update the package to include the catalog by running:

    tanzu package installed update backstage \
  --version PACKAGE-VERSION \
  -f VALUES-FILE

  3. Check the status of this update by running:

    tanzu package installed list

Installing demo apps and their catalogs

To set up one of our demos, you can choose between a blank or a sample catalog.

Yelb system

The Yelb demo catalog in Github includes all the components that make up the Yelb system and the default Backstage components.

Install Yelb

  1. Download the appropriate file for running the Yelb application itself from Github.
  2. Install the application on the Kubernetes cluster that you've used for Tanzu Application Platform. It's important to preserve the metadata labels on the Yelb application's objects.

Install Yelb catalog

  1. Save the Tanzu Application Platform GUI Yelb Catalog from the Tanzu Network's Tanzu Application Platform downloads under the Tap-GUI-Catalogs folder.
  2. Use the steps for Adding an Additional Catalog Location to add the catalog-info.yaml.