System Entity

Learn how to define, manage, and use System entities.

A System in Harness Internal Developer Portal (IDP) is a high-level catalog entity used to logically group related software components, APIs, and infrastructure resources. It represents a functional or domain-specific boundary such as a module, platform area, or business unit, and enables teams to organize and manage complex software ecosystems more effectively.

While Projects and Organizations help separate teams structurally, they often fall short in large environments where multiple teams share the same project. Systems provide an additional layer of organization by allowing you to group related entities based on ownership or functionality. You can define a System at the Project, Organization, or Account level, and assign catalog entities to one or more Systems for better clarity and governance.

You can also use Systems to power views in the Catalog, run scorecards at a system level, and improve how teams discover and manage services. Whether your teams are structured around modules or shared platforms, Systems help bring clarity to how services are grouped and owned.

Use Systems to:

Group services owned by the same team or module
Provide a top-down view of related entities
Assign team ownership and operational responsibility
Enable scorecard and plugin targeting at a System level

Create a system entity

In Harness IDP, a System represents a logical grouping of related services, APIs, and resources. Systems help improve catalog visibility, support governance across scopes, and make it easier for teams to discover and manage what they own.

Systems can be created through:

The Harness UI or YAML view
The Create Entity API by mentioning the kind: System

They can exist at Project, Organization, or Account scope, based on how broadly you want to apply grouping logic.

Create via the IDP UI

To create a System from the IDP UI:

Go to Catalog, click Create.
Select System as the entity kind
Provide:
- Name
- Identifier
- Owner
- Optional: tags and description
Save the entity

The System will appear in the Catalog and can be used to group other entities either visually or programmatically.

Example: System entity YAML

apiVersion: harness.io/v1
kind: System
name: Payment System
identifier: paymentsystem
type: system
owner: team-payment
spec:
  lifecycle: ""
metadata:
  description: This system groups services and libraries related to payment processing.
  tags:
    - rest
    - java

Systems in Harness IDP are standalone entities visible in the Software Catalog, similar to services or APIs. Unlike traditional scopes that are tightly bound to Projects or Organizations, Systems can be defined at any level, Account, Org, or Project, giving teams flexibility based on how they work.

Configure the system layout in catalog entities

After defining a System Entity in Harness IDP, you can configure how its details appear in the Software Catalog.

For newly created accounts, the default System layout is automatically applied. This layout includes tabs such as Overview, Entities, Scorecard, and Diagram, along with a structured arrangement of key catalog components.

We can edit the System Layout under Configure → Layout → Catalog Entities → System. The layout determines the tabs, cards, and views shown when viewing a System in the UI.

The configuration is defined in YAML, for example:

page:
  name: EntityLayout
  tabs:
    - name: Overview
      path: /
      title: Overview
      contents:
        - component: EntityOrphanWarning
        - component: EntityProcessingErrorsPanel
        - component: EntityAboutCard
          specs:
            props:
              variant: gridItem
            gridProps:
              md: 6
              // highlight-start
        - component: EntityCatalogGraphCard
          specs:
            props:
              variant: gridItem
              height: 400
            gridProps:
              md: 6
              xs: 12
        // highlight-end
        - component: EntityScoreCard
          specs:
            gridProps:
              md: 6
        - component: EntityLinksCard
          specs:
            props:
              variant: gridItem
              item: 400
            gridProps:
              md: 6
              xs: 12
        - component: CatalogTable
          specs:
            props:
              variant: gridItem
              height: 600
            gridProps:
              md: 12
              xs: 12
    // highlight-start
    - name: Entities
      path: /entities
      title: Entities
      contents:
        - component: CatalogTable
        // highlight-end
    - name: Scorecard
      path: /scorecard
      title: Scorecard
      contents:
        - component: EntityScorecardContent
    - name: Diagram
      path: /diagram
      title: Diagram
      contents:
        - component: EntityCatalogGraphCard
          specs:
            props:
              variant: gridItem
              title: System Diagram
              height: 700
              unidirectional: false
              relations:
                - partOf
                - hasPart
                - apiConsumedBy
                - apiProvidedBy
                - consumesApi
                - providesApi
                - dependencyOf
                - dependsOn

Existing customers can update their System layout by applying the above YAML in the System section under Catalog Entities - Layout. This ensures the same structured layout and features available to new accounts.

Understand the entities tab in system layout

The Entities tab provides a comprehensive view of all components, APIs, resources, and other entities that belong to a System. This tab is configured in the layout as follows:

- name: Entities
  path: /entities
  title: Entities
  contents:
    - component: CatalogTable

The CatalogTable component renders a filterable, sortable table showing all entities associated with the System. This powerful table offers several key features:

Filtering: Users can filter entities by type (Component, API, Resource), owner, lifecycle stage, and other metadata
Custom columns: Administrators can configure which columns appear in the table
Search: Full-text search across all entity metadata
Pagination: For Systems with many entities, the table automatically paginates results
Quick access: Direct links to each entity's detail page

The Entities tab serves as the primary navigation hub for exploring all components that belong to a System. This view is particularly valuable for platform teams and system owners who need to maintain an overview of all services, APIs, and resources within their domain.

Associate entities with a system

In Harness IDP, once a System is defined, you can associate services, APIs, and other catalog entities with that System by updating their YAML definitions. This helps structure the catalog meaningfully and improves visibility, especially in large organizations with many components.

Systems support many-to-many relationships:

A single service can be part of multiple Systems
A System can include multiple Components, APIs, or Resources

To associate an entity with a System:

Use the system field in the entity's YAML
Optionally use the partOf field if you want to express semantic relationships across systems or domains

Example: Component associated with multiple systems

apiVersion: harness.io/v1
kind: Component
name: Payment Processing Service
identifier: payment_processing_service
type: component
owner: group:account/platform_team
spec:
  lifecycle: production
  partOf:
    - system:account/payment_platform
    - system:account/checkout_system
    - system:account/financial_services
    - system:account/customer_billing
    - system:account/order_management
  system:
    - system:account/payment_platform
    - system:account/checkout_system
    - system:account/financial_services
    - system:account/customer_billing
    - system:account/order_management
  ownedBy:
    - group:account/platform_team
metadata:
  tags:
    - microservice
    - java
    - payment

To establish relationships between catalog entities and Systems in Harness IDP, core entities such as Components, APIs, or Resources can include the spec.system field in their YAML definitions. This allows a single entity to be associated with one or more Systems.

These associations form declarative relationships:

Component → partOf → System
System → hasPart → Component

Once a System is defined, you do not need to modify the System's YAML to reflect every associated Component. When a Component's YAML includes the spec.system field, the Harness IDP Catalog automatically updates the System's relations metadata to reflect this link. This keeps System definitions clean while ensuring accurate relationship visibility within the Catalog.

Only the systems created at the scope of the entity can be chosen.

Entity part of systems

When viewing an Entity (such as a Component, API, or Resource) in the Catalog, the UI highlights which System(s) this Entity is a part of. The diagram above shows this relationship: the Entity detail page features a section that lists all Systems the Entity belongs to. Each System is typically presented as a clickable link or chip, enabling users to quickly navigate to the System's overview. This helps users understand the broader context, governance, and ownership of the Entity within the organization's architecture.

Systems part of entities

When viewing a System in the Catalog, the UI displays all Entities (Components, APIs, Resources) that are part of that System. The diagram above illustrates this scenario: the System detail page includes a section or tab that lists all associated Entities, usually grouped by type and shown as cards and in a table. System-Entity Relations This allows users to see the complete scope of the System, explore its composition, and easily access each Entity's details. This view is valuable for understanding system boundaries, identifying missing or orphaned Entities, and managing ownership at scale.

PreviousData Model Overview

NextUnderstand Catalog YAML

Last updated 3 days ago

Was this helpful?