RHDBUGS-2409: Improve Documentation for Entities: Mandatory Fields, Entity Tabs, and Conditional Visibility

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:
 

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.

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.

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.

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.

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.
+====