diff --git a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc index 9780be0abb..ac161d1628 100644 --- a/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc +++ b/assemblies/configure_configuring-rhdh/assembly-rhdh-default-configuration.adoc @@ -16,6 +16,16 @@ include::../modules/configure_configuring-rhdh/con-automated-operator-features.a include::../modules/configure_configuring-rhdh/ref-time-syntax-in-rhdh.adoc[leveloffset=+1] +include::../modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc[leveloffset=+1] + +include::../modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc[leveloffset=+1] + +include::../modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc[leveloffset=+1] + +include::../modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc[leveloffset=+1] + +include::../modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc[leveloffset=+1] + :context: {previouscontext} :!previouscontext: diff --git a/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc new file mode 100644 index 0000000000..9c0e52b11a --- /dev/null +++ b/modules/configure_configuring-rhdh/proc-define-apis-in-the-catalog.adoc @@ -0,0 +1,37 @@ +:_mod-docs-content-type: PROCEDURE + +[id="define-apis-in-the-catalog_{context}"] += Define APIs in the catalog + +[role="_abstract"] +Expose your interfaces for consumption within the hub by registering an API entity. + +.Procedure + +. Create a YAML file named `catalog-info.yaml` in your repository. + +. Add the following API schema configuration to the file: ++ +[source,yaml] +---- +apiVersion: backstage.io/v1alpha1 +kind: API +metadata: + name: example-api +spec: + type: openapi + lifecycle: production + owner: group:example-team + definition: | + openapi: "3.0.0" + info: + title: Example API + version: "1.0.0" + paths: {} +---- + +. Save and commit the file to your Git repository. + +.Verification + +* Navigate to the *Catalog* page in the UI, filter by *API*, and verify your endpoint definition is visible. \ No newline at end of file diff --git a/modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc new file mode 100644 index 0000000000..77797874af --- /dev/null +++ b/modules/configure_configuring-rhdh/proc-define-locations-in-the-catalog.adoc @@ -0,0 +1,42 @@ +:_mod-docs-content-type: PROCEDURE + +[id="define-locations-in-the-catalog_{context}"] += Define locations in the catalog + +[role="_abstract"] +Import multiple entity descriptors into the software catalog by creating a YAML descriptor file that defines a location entity. + +.Prerequisites + +* You have an active {product-title} instance. +* You have access to a Git repository to host your catalog descriptor files. + +.Procedure + +. Create a YAML file named `catalog-info.yaml` in your centralized repository folder. + +. Add the location configuration to the file, using the `spec.targets` array to point to your individual target configurations: ++ +[source,yaml] +---- +apiVersion: backstage.io/v1alpha1 +kind: Location +metadata: + name: example-location +spec: + type: url + targets: + - https://github.com/example-org/example-repo/blob/main/catalog-info.yaml +---- + +. Save the file and commit it to your Git repository. + +.Verification + +. Log in to your {product-title} instance web console. + +. Navigate to the *Catalog* page using the left sidebar menu. + +. Locate the *Filters* panel on the left side of the catalog view and click *Location*. + +. Confirm that your newly defined location entity appears in the list and that the target data components are successfully discovered without validation errors. \ No newline at end of file diff --git a/modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc new file mode 100644 index 0000000000..cc561c84e8 --- /dev/null +++ b/modules/configure_configuring-rhdh/proc-define-resources-in-the-catalog.adoc @@ -0,0 +1,41 @@ +:_mod-docs-content-type: PROCEDURE + +[id="define-resources-in-the-catalog_{context}"] += Define resources in the catalog + +[role="_abstract"] +Track infrastructure dependencies by creating a YAML descriptor file to register a resource entity in the software catalog. + +.Prerequisites + +* You have an active {product-title} instance. +* You have access to a Git repository to host your catalog descriptor files. + +.Procedure + +. Create a YAML file named `catalog-info.yaml` in your project or infrastructure repository directory. + +. Add the following resource configuration to the file: ++ +[source,yaml] +---- +apiVersion: backstage.io/v1alpha1 +kind: Resource +metadata: + name: example-database +spec: + type: database + owner: group:example-team +---- + +. Save the file and commit it to your Git repository. + +.Verification + +. Log in to your {product-title} instance web console. + +. Navigate to the *Catalog* page using the left sidebar menu. + +. Locate the *Filters* panel on the left side of the catalog view and click *Resource*. + +. Confirm that your newly defined resource appears in the filtered list. \ No newline at end of file diff --git a/modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc b/modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc new file mode 100644 index 0000000000..37dffcb2a9 --- /dev/null +++ b/modules/configure_configuring-rhdh/proc-define-software-components-in-the-catalog.adoc @@ -0,0 +1,35 @@ +:_mod-docs-content-type: PROCEDURE + +[id="define-software-components-in-the-catalog_{context}"] += Define software components in the catalog + +[role="_abstract"] +Populate your software catalog by creating and configuring a YAML descriptor file that defines your application or service. + +.Prerequisites + +* You have access to a Git repository to host your catalog files. + +.Procedure + +. Create a YAML file named `catalog-info.yaml` in the root directory of your repository. + +. Add the following component configuration to the file: ++ +[source,yaml] +---- +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: example-service +spec: + type: service + lifecycle: production + owner: group:example-team +---- + +. Save and commit the file to your Git repository. + +.Verification + +* Navigate to the *Catalog* page in the UI, filter by *Component*, and verify your service is visible. diff --git a/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc new file mode 100644 index 0000000000..82cc543440 --- /dev/null +++ b/modules/configure_configuring-rhdh/ref-catalog-entity-descriptor-reference.adoc @@ -0,0 +1,94 @@ +:_mod-docs-content-type: REFERENCE + +[id="catalog-entity-descriptor-reference_{context}"] += Catalog entity descriptor reference + +[role="_abstract"] +Use these reference tables to identify required YAML attributes and mandatory fields for registering components in the {product} catalog. + + + + + + + + + + +== Mandatory fields for catalog entities + +The following table lists the fields required for each entity kind supported by {product-title}. If you do not provide a mandatory field, the catalog processor fails to validate the entity and throws a `TypeError`. + +== Mandatory fields by entity kind +[cols="1,2,2", options="header"] +|=== +| Entity Kind | Mandatory Fields | Practical Usage and Optional Fields + +| **Component** +| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.lifecycle`, `spec.owner` +| — + +| **Template** +| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.parameters`, `spec.steps` +| — + +| **API** +| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.lifecycle`, `spec.owner`, `spec.definition` +| — + +| **Group** +| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.children` (can be empty) +| — + +| **User** +| `apiVersion`, `kind`, `metadata.name`, `spec.memberOf` (can be empty) +| — + +| **Resource** +| `apiVersion`, `kind`, `metadata.name`, `spec.type`, `spec.owner` +| — + +| **System** +| `apiVersion`, `kind`, `metadata.name`, `spec.owner` +| — + +| **Domain** +| `apiVersion`, `kind`, `metadata.name`, `spec.owner` +| — + +| **Location** +| `apiVersion`, `kind`, `metadata.name`, `spec` +| While `spec` can technically be empty (`{}`), practical usage requires pointing to target definitions using these optional fields: + +* `spec.type`: The location type, such as `url` or `file`. +* `spec.target`: A single string pointer to a target configuration. +* `spec.targets`: An array of one or more string pointers to target configurations. +* `spec.presence`: Specifies whether the target must exist (`required`) or can be missing (`optional`). +|=== + +== Conditional UI behavior for component entities + +The visibility of navigation tabs in the {product-title} interface is determined by the `spec.type` attribute or specific metadata annotations within the component descriptor. + +== Component UI behavior mapping +[cols="1,1,2", options="header"] +|=== +| Field or Annotation | Setting | UI Change + +| `spec.type` +| `service` +| The **API** tab is visible in the component interface. + +| `spec.type` +| `website` or `library` +| The **API** tab is hidden, but provided and consumed APIs remain visible under the **Dependencies** tab. + +| `metadata.annotations` +| `backstage.io/techdocs-ref` +| The **Docs** tab is visible, providing access to TechDocs documentation. +|=== + +[NOTE] +==== +For the *Docs* tab to successfully render technical documentation, the TechDocs plugin must be configured correctly in your instance. +==== \ No newline at end of file