[IDP] Feature - Custom user group Entity

docs/internal-developer-portal/catalog/catalog-yaml.md

@@ -121,6 +121,32 @@ metadata:
 ```
 </details>
 
+<details>
+<summary>User Group YAML Example</summary>
+
+```yaml
+apiVersion: harness.io/v1
+kind: Group
+type: engineering
+name: Cloud Infrastructure Team
+identifier: cloud_infrastructure_team
+spec:
+  members:
+    - user:account/[email protected]
+    - user:account/[email protected]
+  parent: group:account/idp_team
+  profile:
+    email: [email protected]
+metadata:
+  description: User Group responsible for building and maintaining the company’s core cloud infrastructure.
+  teamLead: Jane Doe
+  region: US West
+  tags:
+    - cloud
+    - engineering
+```
+</details>
+
 :::info
 Please ensure that **no entity YAML files** are stored in **Git in IDP 2.0** until the [Git Experience](/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md#native-harness-git-experience) feature is released. You can track its release and other updates in the **[IDP 2.0 Features Status](/docs/internal-developer-portal/idp-2o-overview/2-0-overview-and-upgrade-path.md)** table
 :::
@@ -205,6 +231,7 @@ With **IDP 2.0**, you can define the following `kind` types in your Catalog YAML
 * `kind: Resource`
 * `kind: Workflow`
 * `kind: System`
+* `kind: Group`
 
 Each kind represents a different type of entity within the Harness-native data model.
 [Read more about the different entity kinds here.](/docs/internal-developer-portal/catalog/catalog-yaml.md#entity-kinds)
@@ -507,6 +534,56 @@ metadata:
 
 ---
 
+### Kind: Group
+**Group** entities allow organizations to model their team structure directly within the IDP catalog. Custom User Groups extend the catalog model to include organizational teams and hierarchies as first-class entities, representing real-world structures such as teams, departments, or cross-functional squads.
+
+Unlike platform user groups which are synchronized from an identity provider (LDAP, SCIM, SSO), custom user groups are created and managed entirely within IDP, allowing for richer metadata and context.
+
+#### Entity Structure
+All the fields mentioned below are the parameters required to define a Group:
+
+| **Field** | **Value** |
+| --------- | --------- |
+| `apiVersion` | **harness.io/v1** |
+| `kind` | **Group** |
+| `name` | Human-readable name for the group |
+| `identifier` | Unique identifier for the group |
+| `type` | Common values include `department`, `engineering` |
+
+#### Special Spec Fields
+
+| **Field** | **Description** |
+| --------- | --------------- |
+| `spec.members` | List of users belonging to the group |
+| `spec.parent` | Reference to a parent group, enabling hierarchy |
+| `spec.profile` | Additional profile information like email |
+
+#### Example YAML
+```yaml
+apiVersion: harness.io/v1
+kind: Group
+type: engineering
+name: Cloud Infrastructure Team
+identifier: cloud_infrastructure_team
+spec:
+  members:
+    - user:account/[email protected]
+    - user:account/[email protected]
+  lifecycle: active
+  parent: group:account/idp_team
+  profile:
+    email: [email protected]
+metadata:
+  description: Cloud Infrastructure Team for building and maintaining the company’s core cloud infrastructure.
+  teamLead: Jane Doe
+  region: US West
+  tags:
+    - cloud
+    - engineering
+```
+
+---
+
 ### Kind: Workflow  
 **Workflows** enable developer self-service by automating manual tasks and processes. Platform engineering teams can use workflows to:
 - Automate new service onboarding
@@ -1047,7 +1124,12 @@ The current set of well-known and common values for this field is:
 
 #### Spec owner
 
-In the Harness Internal Developer Portal, the owner of a component is identified by the [Harness User Group ID](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups). This User Group ID represents the collective entity that holds ultimate responsibility for the component and possesses the authority and capability to develop and maintain it. Should any issues arise or if there are requests for features, this User Group will serve as the primary point of contact. The primary purpose of this field in the Harness IDP is for display, ensuring that individuals accessing catalog items can easily identify the responsible User Group for a given component.
+In the Harness Internal Developer Portal, the owner of a component can be identified by either:
+
+* **Platform User Group ID**: The [Harness User Group ID](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups) for groups synced from identity providers
+* **Custom User Group** [IDP 2.0]: A [Custom User Group](/docs/internal-developer-portal/catalog/user-group) created directly within IDP as a first-class catalog entity
+
+In both cases, this User Group represents the collective entity that holds ultimate responsibility for the component and possesses the authority and capability to develop and maintain it. Should any issues arise or if there are requests for features, this User Group will serve as the primary point of contact. The primary purpose of this field in the Harness IDP is for display, ensuring that individuals accessing catalog items can easily identify the responsible User Group for a given component.
 
 <details>
 <summary>How to get the Harness User Group ID</summary>

docs/internal-developer-portal/catalog/add-user-groups-in-catalog.md → docs/internal-developer-portal/catalog/content/user-group/user-group-idp-1.md

@@ -1,32 +1,17 @@
----
-title: How to Add User Groups Directly in the Catalog
-description: Detailed instructions on how to add user groups directly into the IDP Catalog   
-sidebar_label: Ingest User Groups in Catalog
-sidebar_position: 10
-redirect_from:
-  - docs/internal-developer-portal/catalog/add-users-in-catalog
----
-
-:::info
-This feature is **only available in IDP 1.0**. Custom user groups will be available soon in IDP 2.0. 
-:::
+## Add User Groups Directly in the Catalog
 
 The Catalog in Harness IDP also supports addition of [organizational entities](https://backstage.io/docs/features/software-catalog/system-model#organizational-entities) like **user groups** directly, independent of their presence on the Harness Platform. These entities can be registered as `kind: Group` in the catalog as an YAML. Note that our recommendation is to use the [Harness Platform Access Control](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups/) for ingesting Users and User Groups into Harness IDP.
 
 :::info
-
 The User Groups registered as entities in Catalog directly are not synced back with Harness Platform. The User Groups you add in IDP won't be available as a [Harness Platform User Group](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups). However, the opposite is true - any user group created in the Harness Platform at the Account level scope will be available in the IDP Catalog as well.
-
 :::
 
 ## Kind: Group
 
 A group describes an organizational entity, such as a team, a business unit, or a loose collection of people in an interest group. Members of these groups are modeled in the catalog as User. 
 
 :::info
-
 You can not add Users directly into the catalog as Users are linked with authentication. You can [add users](https://developer.harness.io/docs/platform/role-based-access-control/add-users/#add-users-manually) on the Harness platform at the Account level.
-
 :::
 
 Descriptor files for this kind may look as follows, where `apiVersion`, `kind`, `spec.type` and `spec.children` are **required** fields. 
@@ -44,10 +29,9 @@ spec:
     email: [email protected]
     picture: https://example.com/groups/bu-infrastructure.jpeg
   parent: ops
-  children: [backstage, other]
-  members: [jdoe]
+  children: [infra-devops, infra-devsecops]
+  members: [mira.rosen, lee.coleman]
 ```
-
 In the above example, `children` represent other user-groups and `members` represent the users under this user group. 
 
 At present we sync all your [user-groups](https://developer.harness.io/docs/platform/role-based-access-control/add-user-groups/) added in Harness Platform to IDP and you could find them under catalog page. 
@@ -64,7 +48,7 @@ In case there's a user-group already present with the same `metadata.name` while
 
 ![](./static/team.png)
 
-### When to ingest groups directly into the Catalog rather than creating a Harness Platform User Group at the account level?
+#### When to ingest groups directly into the Catalog rather than creating a Harness Platform User Group at the account level?
 
 - If you need to represent a Group of Groups kind of hierarchy e.g. Org -> Department -> Team
 - If you would like the Groups definition to support annotations and tags to be consumed by plugins on the Groups page in Catalog.