catalog

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 15, 2024 License: MIT Imports: 11 Imported by: 2

Documentation

Overview

Package catalog provides primitives for the Backstage Software Catalog API.

Index

Examples

Constants

View Source 
const (
	// LocationPresenceRequired describes a location that is required to exist.
	LocationPresenceRequired = "required"
	// LocationPresenceOptional describes a location that is not required to exist.
	LocationPresenceOptional = "optional"
)

Known LocationPresence values.

Variables

This section is empty.

Functions

This section is empty.

Types

type APISpec 

type APISpec struct {
	// The type of API. This field is required.
	Type string `json:"type"`
	// The lifecycle state of the API. This field is required.
	Lifecycle string `json:"lifecycle"`
	// An entity reference to the owner of the API. This field is required.
	Owner string `json:"owner"`
	// An entity reference to the system that the component belongs to.
	System string `json:"system,omitempty"`
	// The definition of the API, based on the format defined by [APISpec.Type]. This field is required.
	Definition string `json:"definition"`
}

APISpec contains the API standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format/#kind-api

type BatchGetEntitiesByRefsRequest 

type BatchGetEntitiesByRefsRequest struct {
	// EntityRefs to fetch.
	// See: https://backstage.io/docs/features/software-catalog/references
	EntityRefs []string `json:"entityRefs"`

	// Fields to fetch.
	Fields []string `json:"fields,omitempty"`
}

BatchGetEntitiesByRefsRequest is the request to the Client.BatchGetEntitiesByRefs method.

type BatchGetEntitiesByRefsResponse 

type BatchGetEntitiesByRefsResponse struct {
	// Entities returned.
	// Has the same length and the same order as the input entityRefs array.
	Entities []*Entity
}

BatchGetEntitiesByRefsResponse is the response from the Client.BatchGetEntitiesByRefs method.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client to the Backstage Catalog API.

Example 
package main

import (
	"context"
	"fmt"

	"go.einride.tech/backstage/catalog"
)

func main() {
	ctx := context.Background()
	// Create a Software Catalog API client.
	client := catalog.NewClient(
		catalog.WithBaseURL("https://your-backstage-instance.example.com"),
		catalog.WithToken("YOUR_API_AUTH_TOKEN"),
	)
	// List component entities.
	response, err := client.ListEntities(ctx, &catalog.ListEntitiesRequest{
		Filters: []string{"kind=Component"},
	})
	if err != nil {
		panic(err)
	}
	for _, entity := range response.Entities {
		// Standard fields are parsed into Go structs.
		fmt.Println(entity.Metadata.Name)
		// Standard fields on specs can be parsed into Go structs.
		spec, err := entity.ComponentSpec()
		if err != nil {
			panic(err)
		}
		fmt.Println(spec.Lifecycle)
		// Custom fields can be accessed via raw JSON.
		fmt.Println(string(entity.Raw))
	}
}

Output:

func NewClient 

func NewClient(options ...ClientOption) *Client

NewClient creates a new catalog API Client.

func (*Client) BatchGetEntitiesByRefs 

func (c *Client) BatchGetEntitiesByRefs(
	ctx context.Context,
	request *BatchGetEntitiesByRefsRequest,
) (*BatchGetEntitiesByRefsResponse, error)

BatchGetEntitiesByRefs gets an entity by its kind, namespace and name. See: https://backstage.io/docs/features/software-catalog/software-catalog-api#post-entitiesby-refs

func (*Client) DeleteEntityByUID 

func (c *Client) DeleteEntityByUID(ctx context.Context, request *DeleteEntityByUIDRequest) error

DeleteEntityByUID deletes an entity by its UID.

See: https://backstage.io/docs/features/software-catalog/software-catalog-api/#delete-entitiesby-uiduid

func (*Client) GetEntityByName 

func (c *Client) GetEntityByName(ctx context.Context, request *GetEntityByNameRequest) (*Entity, error)

GetEntityByName gets an entity by its kind, namespace and name.

See: https://backstage.io/docs/features/software-catalog/software-catalog-api/#get-entitiesby-namekindnamespacename

func (*Client) GetEntityByUID 

func (c *Client) GetEntityByUID(ctx context.Context, request *GetEntityByUIDRequest) (*Entity, error)

GetEntityByUID gets an entity by its kind, namespace and name.

See: https://backstage.io/docs/features/software-catalog/software-catalog-api/#get-entitiesby-uiduid

func (*Client) ListEntities 

func (c *Client) ListEntities(ctx context.Context, request *ListEntitiesRequest) (*ListEntitiesResponse, error)

ListEntities lists entities in the catalog.

See: https://backstage.io/docs/features/software-catalog/software-catalog-api/#get-entities

type ClientOption 

type ClientOption func(*clientConfig)

ClientOption configures a Client.

func WithBaseURL 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets the backend base URL.

func WithToken 

func WithToken(token string) ClientOption

WithToken sets the bearer token to use for authentication.

type ComponentSpec 

type ComponentSpec struct {
	// The type of component. This field is required.
	Type string `json:"type"`
	// The lifecycle state of the component. This field is required.
	Lifecycle string `json:"lifecycle"`
	// An entity reference to the owner of the component. This field is required.
	Owner string `json:"owner"`
	// An entity reference to the system that the component belongs to.
	System string `json:"system,omitempty"`
	// An entity reference to another component of which the component is a part.
	SubcomponentOf string `json:"subcomponentOf,omitempty"`
	// An array of entity references to the APIs that are provided by the component.
	ProvidesAPIs []string `json:"providesApis,omitempty"`
	// An array of entity references to the APIs that are consumed by the component.
	ConsumesAPIs []string `json:"consumesApis,omitempty"`
	// An array of entity references to the components and resources that the component depends on.
	DependsOn []string `json:"dependsOn,omitempty"`
}

ComponentSpec contains the Component standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-component

type DeleteEntityByUIDRequest 

type DeleteEntityByUIDRequest struct {
	// UID of the entity to get.
	UID string
}

DeleteEntityByUIDRequest is the request to the Client.DeleteEntityByUID method.

type DomainSpec 

type DomainSpec struct {
	// An entity reference to the owner of the domain. This field is required.
	Owner string `json:"owner"`
}

DomainSpec contains the Domain standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-domain

type Entity 

type Entity struct {
	// APIVersion is the version of specification format for this particular entity.
	APIVersion string

	// Kind is the high-level entity type.
	Kind EntityKind

	// Metadata related to the entity.
	Metadata EntityMetadata

	// Relations that this entity has with other entities.
	Relations []EntityRelation

	// Raw entity JSON message.
	Raw json.RawMessage
}

An Entity in the software catalog.

func (*Entity) APISpec 

func (e *Entity) APISpec() (*APISpec, error)

APISpec decodes the entity's spec as a APISpec.

func (*Entity) ComponentSpec 

func (e *Entity) ComponentSpec() (*ComponentSpec, error)

ComponentSpec decodes the entity's spec as a ComponentSpec.

func (*Entity) DomainSpec 

func (e *Entity) DomainSpec() (*DomainSpec, error)

DomainSpec decodes the entity's spec as a DomainSpec.

func (*Entity) GroupSpec 

func (e *Entity) GroupSpec() (*GroupSpec, error)

GroupSpec decodes the entity's spec as a GroupSpec.

func (*Entity) LocationSpec 

func (e *Entity) LocationSpec() (*LocationSpec, error)

LocationSpec decodes the entity's spec as a LocationSpec.

func (*Entity) ResourceSpec 

func (e *Entity) ResourceSpec() (*ResourceSpec, error)

ResourceSpec decodes the entity's spec as a ResourceSpec.

func (*Entity) SystemSpec 

func (e *Entity) SystemSpec() (*SystemSpec, error)

SystemSpec decodes the entity's spec as a SystemSpec.

func (*Entity) TemplateSpec 

func (e *Entity) TemplateSpec() (*TemplateSpec, error)

TemplateSpec decodes the entity's spec as a TemplateSpec.

func (*Entity) UnmarshalJSON added in v0.5.0 

func (e *Entity) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Entity) UserSpec 

func (e *Entity) UserSpec() (*UserSpec, error)

UserSpec decodes the entity's spec as a UserSpec.

type EntityKind 

type EntityKind string

EntityKind represents a known entity kind. 

const (
	// EntityKindComponent represents a Component entity kind.
	EntityKindComponent EntityKind = "Component"

	// EntityKindSystem represents a System entity kind.
	EntityKindSystem EntityKind = "System"

	// EntityKindDomain represents a Domain entity kind.
	EntityKindDomain EntityKind = "Domain"

	// EntityKindUser represents a User entity kind.
	EntityKindUser EntityKind = "User"

	// EntityKindAPI represents an API entity kind.
	EntityKindAPI EntityKind = "API"

	// EntityKindResource represents a Resource entity kind.
	EntityKindResource EntityKind = "Resource"

	// EntityKindLocation represents a Location entity kind.
	EntityKindLocation EntityKind = "Location"

	// EntityKindTemplate represents a Template entity kind.
	EntityKindTemplate EntityKind = "Template"

	// EntityKindGroup represents a Group entity kind.
	EntityKindGroup EntityKind = "Group"
)

Known entity kinds. 

type EntityLink struct {
	// URL to the external site, document, etc.
	URL string `json:"url"`

	// Title is an optional descriptive title for the link.
	Title string `json:"title,omitempty"`

	// Icon is an optional semantic key that represents a visual icon.
	Icon string `json:"icon,omitempty"`

	// Type is an optional value to categorize links into specific groups.
	Type string `json:"type,omitempty"`
}

EntityLink is a link to external information that is related to the entity.

type EntityMetadata 

type EntityMetadata struct {
	// The Name of the entity.
	//
	// Must be unique within the catalog at any given point in time, for any
	// given namespace + kind pair. This value is part of the technical
	// identifier of the entity, and as such it will appear in URLs, database
	// tables, entity references, and similar. It is subject to restrictions
	// regarding what characters are allowed.
	//
	// If you want to use a different, more human-readable string with fewer
	// restrictions on it in user interfaces, see the `title` field below.
	Name string `json:"name"`

	// UID is a globally unique ID for the entity.
	//
	// This field can not be set by the user at creation time, and the server
	// will reject an attempt to do so. The field will be populated in read
	// operations. The field can (optionally) be specified when performing
	// update or delete operations, but the server is free to reject requests
	// that do so in such a way that it breaks semantics.
	UID string `json:"uid,omitempty"`

	// ETag is an opaque string that changes for each update operation to any part of
	// the entity, including metadata.
	//
	// This field can not be set by the user at creation time, and the server
	// will reject an attempt to do so. The field will be populated in read
	// operations. The field can (optionally) be specified when performing
	// update or delete operations, and the server will then reject the
	// operation if it does not match the current stored value.
	ETag string `json:"etag,omitempty"`

	// The Namespace that the entity belongs to.
	Namespace string `json:"namespace,omitempty"`

	// Title is a display name of the entity, to be presented in user interfaces instead
	// of the `name` property above, when available.
	//
	// This field is sometimes useful when the `name` is cumbersome or ends up
	// being perceived as overly technical. The title generally does not have
	// as stringent format requirements on it, so it may contain special
	// characters and be more explanatory. Do keep it very short though, and
	// avoid situations where a title can be confused with the name of another
	// entity, or where two entities share a title.
	//
	// Note that this is only for display purposes, and may be ignored by some
	// parts of the code. Entity references still always make use of the `name`
	// property, not the title.
	Title string `json:"title,omitempty"`

	// Description is a short (typically relatively few words, on one line) description of the entity.
	Description string `json:"description,omitempty"`

	// Labels contains key/value pairs of identifying information attached to the entity.
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations contains key/value pairs of non-identifying auxiliary information attached to the entity.
	Annotations map[string]string `json:"annotations,omitempty"`

	// Tags is a list of single-valued strings, to for example classify catalog entities in various ways.
	Tags []string `json:"tags,omitempty"`

	// Links is a list of external hyperlinks related to the entity.
	Links []EntityLink `json:"links,omitempty"`
}

EntityMetadata contains fields common to all versions/kinds of entity.

See also:

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/

type EntityRelation 

type EntityRelation struct {
	// The type of the relation.
	Type string `json:"type"`

	// The entity ref of the target of this relation.
	TargetRef string `json:"targetRef"`
}

EntityRelation is a relation of a specific type to another entity in the catalog.

type GetEntityByNameRequest 

type GetEntityByNameRequest struct {
	// Kind of the entity to get.
	Kind string
	// Namespace of the entity to get.
	Namespace string
	// Name of the entity to get.
	Name string
}

GetEntityByNameRequest is the request to the Client.GetEntityByName method.

type GetEntityByUIDRequest 

type GetEntityByUIDRequest struct {
	// UID of the entity to get.
	UID string
}

GetEntityByUIDRequest is the request to the Client.GetEntityByUID method.

type GroupSpec 

type GroupSpec struct {
	// The type of group. This field is required.
	//
	// There is currently no enforced set of values for this field,
	// so it is left up to the adopting organization to choose a nomenclature
	// that matches their org hierarchy.
	Type string `json:"type"`
	// Profile information about the group, mainly for display purposes.
	Profile Profile `json:"profile,omitempty"`
	// Parent group in the hierarchy, if any.
	Parent string `json:"parent,omitempty"`
	// Child groups of this group in the hierarchy (whose parent field points to this group).
	// The items are not guaranteed to be ordered in any particular way.
	Children []string `json:"children"`
	// Members are the users that are direct members of this group.
	// The items are not guaranteed to be ordered in any particular way.
	Members []string `json:"members,omitempty"`
}

GroupSpec contains the Group standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-group

type ListEntitiesRequest 

type ListEntitiesRequest struct {
	// Filters for selecting only a subset of all entities.
	Filters []string
	// Fields for selecting only parts of the full data structure of each entity.
	Fields []string
	// Offset for pagination.
	Offset int64
	// Limit for pagination.
	Limit int64
	// After for returning the next page after the provided cursor.
	After string
}

ListEntitiesRequest is the request to the Client.ListEntities method.

type ListEntitiesResponse 

type ListEntitiesResponse struct {
	// Entities in the response.
	Entities []*Entity
	// NextPageToken contains the next page token.
	NextPageToken string
}

ListEntitiesResponse is the response from the Client.ListEntities method.

type LocationPresence 

type LocationPresence string

LocationPresence represents a location presence.

type LocationSpec 

type LocationSpec struct {
	// Type is the single location type, that's common to the targets specified in the spec.
	//
	// If it is left out, it is inherited from the location type that originally read the
	// entity data.
	//
	// For example, if you have a URL type location, that when read results in a Location kind
	// entity with no spec.type, then the referenced targets in the entity will implicitly also
	// be of url type.
	//
	// This is useful because you can define a hierarchy of things in a directory structure
	// using relative target paths (see below), and it will work out no matter if it's consumed
	// locally on disk from a file location, or as uploaded on a VCS.
	Type string `json:"type,omitempty"`

	// Target as a string.
	//
	// Can be either an absolute path/URL (depending on the type), or a relative path
	// such as ./details/catalog-info.yaml which is resolved relative to the location of
	// the Location entity itself.
	Target string `json:"target,omitempty"`

	// Targets as strings.
	//
	// They can all be either absolute paths/URLs (depending on the type), or relative paths
	// such as ./details/catalog-info.yaml which are resolved relative to the location of
	// the Location entity itself.
	Targets []string `json:"targets,omitempty"`

	// Describes whether the target of a location is required to exist or not.
	// It defaults to 'required' if not specified, can also be 'optional'.
	Presence LocationPresence `json:"presence,omitempty"`
}

LocationSpec contains the Location standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-location

type Ordering 

type Ordering struct {
	Field string
	Desc  bool
}

Ordering configuration for a field.

type Profile 

type Profile struct {
	// DisplayName of the profile.
	DisplayName string `json:"displayName,omitempty"`
	// Email of the profile.
	Email string `json:"email,omitempty"`
	// Picture URL of the profile.
	Picture string `json:"picture,omitempty"`
}

Profile represents a user or group profile.

type ResourceSpec 

type ResourceSpec struct {
	// The type of resource. This field is required.
	Type string `json:"type"`
	// An entity reference to the owner of the resource. This field is required.
	Owner string `json:"owner"`
	// An entity reference to the system that the resource belongs to.
	System string `json:"system,omitempty"`
	// An array of entity references to the resources and resources that the resource depends on.
	DependsOn []string `json:"dependsOn,omitempty"`
	// An array of entity references to the components and resources that the resource is a dependency of.
	DependencyOf []string `json:"dependencyOf,omitempty"`
}

ResourceSpec contains the Resource standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-resource

type StatusError 

type StatusError struct {
	// Status of the error.
	Status string
	// StatusCode of the error.
	StatusCode int
}

StatusError represents an HTTP status error.

func (*StatusError) Error 

func (s *StatusError) Error() string

Error implements error.

type SystemSpec 

type SystemSpec struct {
	// An entity reference to the owner of the system. This field is required.
	Owner string `json:"owner"`
	// An entity reference to the domain that the system belongs to.
	Domain string `json:"domain,omitempty"`
}

SystemSpec contains the System standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-system

type TemplateSpec 

type TemplateSpec struct {
	// The type of component created by the template, e.g. website.
	// This is used for filtering templates, and should ideally match the Component spec.type created by the template.
	Type string `json:"type"`

	// An entity reference to the owner of the template.
	Owner string `json:"owner,omitempty"`

	// RawParameters contains the parameter specs.
	RawParameters []json.RawMessage `json:"parameters"`

	// RawSteps contains the step specs.
	RawSteps []json.RawMessage `json:"steps"`
}

TemplateSpec contains the Template standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-template

type UserSpec 

type UserSpec struct {
	// Profile information about the user, mainly for display purposes.
	Profile Profile `json:"profile,omitempty"`
	// MemberOf is the list of groups that the user is a direct member of.
	MemberOf []string `json:"memberOf"`
}

UserSpec contains the User standard spec fields.

See: https://backstage.io/docs/features/software-catalog/descriptor-format#kind-user

type WellKnownAnnotations added in v0.7.0 

type WellKnownAnnotations struct {
	// BackstageManagedByLocation is a so-called location reference string.
	//
	// It points to the source from which the entity was originally fetched.
	//
	// This annotation is added automatically by the catalog as it fetches the
	// data from a registered location, and is not meant to normally be written
	// by humans.
	//
	// The annotation may point to any type of generic location that the catalog
	// supports, so it cannot be relied on to always be specifically of type url,
	// nor that it even represents a single file. Note also that a single
	// location can be the source of many entities, so it represents a
	// many-to-one relationship.
	//
	//
	// The format of the value is <type>:<target>.
	//
	// Note that the target may also contain colons, so it is not advisable to
	// naively split the value on : and expecting a two-item array out of it. The
	// format of the target part is type-dependent and could conceivably even be
	// an empty string, but the separator colon is always present.
	BackstageManagedByLocation string `json:"backstage.io/managed-by-location,omitempty"`

	// BackstageManagedByOriginLocation is a location reference string (see above).
	//
	// It points to the location, whose registration lead to the creation of the
	// entity.
	//
	// In most cases, the backstage.io/managed-by-location and
	// backstage.io/managed-by-origin-location will be equal. They will be
	// different if the original location delegates to another location.
	//
	// A common case is, that a location is registered as bootstrap:bootstrap
	// which means that it is part of the app-config.yaml of a Backstage
	// installation.
	BackstageManagedByOriginLocation string `json:"backstage.io/managed-by-origin-location,omitempty"`

	// BackstageOrphan is either absent, or present with the exact string value "true".
	//
	// It should never be added manually. Instead, the catalog itself injects the
	// annotation as part of its processing loops, on entities that are found to
	// have no registered locations or config locations that keep them "active" /
	// "alive".
	//
	// For example, suppose that the user first registers a location URL pointing
	// to a Location kind entity, which in turn refers to two Component kind
	// entities in two other files nearby. The end result is that the catalog
	// contains those three entities. Now suppose that the user edits the original
	// Location entity to only refer to the first of the Component kind entities.
	// This will intentionally not lead to the other Component entity to be removed
	// from the catalog (for safety reasons). Instead, it gains this orphan marker
	// annotation, to make it clear that user action is required to completely
	// remove it, if desired.
	BackstageOrphan string `json:"backstage.io/orphan,omitempty"`

	// BackstageTechDocsRef informs where TechDocs source content is stored so
	// that it can be read and docs can be generated from it.
	//
	// Most commonly, it's written as a path, relative to the location of the
	// catalog-info.yaml itself, where the associated mkdocs.yml file can be
	// found.
	//
	// In unusual situations where the documentation for a catalog entity does
	// not live alongside the entity's source code, the value of this annotation
	// can point to an absolute URL, matching the location reference string
	// format outlined above, for example:
	// url:https://github.com/backstage/backstage/tree/master
	BackstageTechDocsRef string `json:"backstage.io/techdocs-ref,omitempty"`

	// BackstageViewURL allows customizing links from the catalog pages.
	//
	// The view URL should point to the canonical metadata YAML that governs this entity.
	BackstageViewURL string `json:"backstage.io/view-url,omitempty"`

	// BackstageEditURL allows customizing links from the catalog pages.
	//
	// The edit URL should point to the source file for the metadata.
	BackstageEditURL string `json:"backstage.io/edit-url,omitempty"`

	// BackstageSourceLocation is a Location reference that points to the source
	// code of the entity (typically a Component).
	//
	// Useful when catalog files do not get ingested from the source code
	// repository itself.
	//
	// If the URL points to a folder, it is important that it is suffixed with a
	// '/' in order for relative path resolution to work consistently.
	BackstageSourceLocation string `json:"backstage.io/source-location,omitempty"`

	// GitHubProjectSlug is the so-called slug that identifies a repository on
	// GitHub that is related to this entity.
	//
	// It is on the format <organization or owner>/<repository>, and is the same
	// as can be seen in the URL location bar of the browser when viewing that
	// repository.
	//
	// Specifying this annotation will enable GitHub related features in
	// Backstage for that entity.
	GitHubProjectSlug string `json:"github.com/project-slug,omitempty"`

	// GitHubTeamSlug is the so-called slug that identifies a team on GitHub that is
	// related to this entity.
	//
	// It is on the format <organization>/<team>, and is the same as can be seen
	// in the URL location bar of the browser when viewing that team.
	//
	// This annotation can be used on a Group entity to note that it originated
	// from that team on GitHub.
	GitHubTeamSlug string `json:"github.com/team-slug,omitempty"`

	// GitHubUserLogin is the so-called login that identifies a user on GitHub
	// that is related to this entity.
	//
	// It is on the format <username>, and is the same as can be seen in the URL
	// location bar of the browser when viewing that user.
	//
	// This annotation can be used on a User entity to note that it originated
	// from that user on GitHub.
	GitHubUserLogin string `json:"github.com/user-login,omitempty"`
}

WellKnownAnnotations contains a number of well-known annotations with defined semantics. They can be attached to catalog entities and consumed by plugins as needed.

See: https://backstage.io/docs/features/software-catalog/well-known-annotations

func (*WellKnownAnnotations) UnmarshalAnnotations added in v0.7.0 

func (w *WellKnownAnnotations) UnmarshalAnnotations(annotations map[string]string)

UnmarshalAnnotations sets the wll-known annotations from a map of annotations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.