Grouping entities

Groups are a tagging system that can be used to group a set of entities together, enabling a variety of use cases including:

• Tagging

  • Use groups to segment entities.

  • For example, you could segment by tiers (tier-0 to indicate high priority), type (backend, frontend, library, API), or language (Python, Java).

• Filtering throughout Cortex

  • Use groups to include or exclude certain entities from Scorecards, catalogs, CQL reports, and more.

  • For example, you may want a Scorecard to only apply to Python services or a catalog that only shows tier-0 services.

• Reporting

  • You could aggregate Scorecard scores by a specific group, such as a tier.

  • For example, viewing a Production Readiness Scorecard broken down by tier.

While viewing an entity, its groups are listed at the top of the page:

Groups appear in entity detail pages.

Click the group name to view a list of all other entities that are tagged with this group.

How to define groups

You can define groups via an entity's YAML, directly in the Cortex UI, or via the API.

Note the following considerations:

• If a group has been set in the entity descriptor YAML, an API call will not overwrite the existing value.

• Groups created via the API will not appear in the entity descriptor YAML.

• Groups created via the API cannot be removed via the Cortex UI.

Cortex UI

To create a group in the UI:

1. Navigate to the entity that you want to apply a group to.

   • Click the magnifying glass icon at the bottom of the main nav, or click Catalogs > All entities and search for the entity from that page.

2. In the upper right corner of the entity page, click Configure entity.

3. Click into the Groups field.

   • To apply an existing group, type to search then click on the group.

   • To create a new group, type the group name into the field, then click the group name in the dropdown. The group will be created and applied to the entity.

4. At the bottom of the page, click Save.

Entity descriptor

Groups are defined as a list of tags.

```yaml
x-cortex-groups:
    - tier0
    - language:kotlin
```

Groups may not contain whitespace characters.

API

You can use the API to add groups to an entity. See the API documentation for groups here.

FAQ and troubleshooting

When should I use groups instead of custom data?

To determine whether or not to use groups or custom data, consider whether your use case would be considered "tagging" with a definite enum of values (backend vs frontend), or more freeform metadata availability-zones: [east, west].