Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 83 additions & 1 deletion docs/internal-developer-portal/catalog/catalog-yaml.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
:::
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down
Loading