# Adding domains
Domains are a default entity type in Cortex used to group entities into hierarchical units. You can group by product area, functionality, systems, business units, or something unique to your organization. With this feature, you can cluster entities into a single, hierarchical domain that can include both parents and children.
You can define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace. This hierarchy is available to view in the Domains catalog, on a domain entity's details page, and in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md). The domain hierarchy can also be used to configure ownership inheritance, helping you keep track of ownership in case of personnel changes at your organization.
## Adding domain entities to Cortex
Users with the `Edit Catalog` and `Edit Domains` permissions can add domain entities to Cortex.
Domains can be added manually, imported, defined in YAML via GitOps, or created via the API.
For simplicity, it's recommended to add the highest-level domain first, then select it as the parent for subsequent domains. However, you can add parents and children to any domain at any point.
### Importing domains from an integration
1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Import discovered entities**.
4. Select the integration to import from.\
The **Select entities to import** page is displayed.
5. A list of entities from the integration are displayed. Select the checkboxes next to the entities you want to import. If you have a large volume of entities, click the **Filter icon** in the upper-right corner of the results list to select and apply entity type filters.
6. In the bottom-right corner, click **Next step**.\
The **Edit details** page is displayed.
7. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
1. From the **Type** drop-down menu, select **Domain.**
2. In the **Details** section**:**
1. Below **Entity name**, enter a name for the entity (required).
2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`.
3. Below **Description**, enter a description of the entity to help others understand its purpose.
4. From the **Groups** drop-down menu**,** select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups.md).
3. In the **Repository** section:
1. From the **Provider** drop-down menu, select the repo provider.
2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
4. Below **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
* Cortex may recommend owners [based on repository activity](/ingesting-data-into-cortex/entities-overview/entities/ownership.md#recommendation). You can accept or reject the recommendations.
* When adding an owner, you can also configure one of the following inheritance options:
* **Append** - Select this option to add your entity as an additional owner to all of its child entities.
* **Fallback** - Select this option to add your entity as an owner to child entities if the child entity has no other valid owners.
* **None** - Select this option if you do not want to configure inheritance. The owner owns the domain you are creating, but will not be configured as an appended or a fallback owner.
5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
8. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
8. If you selected more than one entity, click **Next entity** in the bottom-right corner of the page.
9. Click **Confirm import**.\
The entity is imported into Cortex.
### Manually adding domains
1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. In the upper-right corner, click **Import entities**.
3. Select **Create entities manually**. \
The **Edit details** page is displayed.
4. Configure the following options. The options shown are filtered at runtime based on the `entityType` (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).
1. From the **Type** drop-down menu, select **Domain.**
2. **In the Details section:**
1. Below **Entity name**, enter a name for the entity (required).
2. The **Cortex tag** field is auto-populated based on the name of the entity (required). Its a unique identifier for the entity. This is also known as the `x-cortex-tag`.
3. Below **Description**, enter a description of the entity to help others understand its purpose.
4. From the **Groups** drop-down menu**,** select a group or groups [to segment the entity](/ingesting-data-into-cortex/entities-overview/entities/groups.md).
3. In the **Repository** section:
1. From the **Provider** drop-down menu, select the repo provider.
2. From the **Alias** drop-down menu, select the alias of the connected provider account that has access to the repository.
3. From the **Repository** drop-down menu, select the repo associated with the entity. If you don't see it listed, click **Refresh repositories** to pull in the latest list.
4. Below **Basepath**, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
4. In the **Owners** section, define [ownership](/ingesting-data-into-cortex/entities-overview/entities/ownership.md) for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click **Add** in the **Teams** area. To add an individual user or users, click **Add** in the **Users** area.
* Cortex may recommend owners [based on repository activity](/ingesting-data-into-cortex/entities-overview/entities/ownership.md#recommendation). You can accept or reject the recommendations.
* When adding an owner, you can also configure one of the following inheritance options:
* **Append** - Select this option to add your entity as an additional owner to all of its child entities.
* **Fallback** - Select this option to add your entity as an owner to child entities if the child entity has no other valid owners.
* **None** - Select this option if you do not want to configure inheritance. The owner owns the domain you are creating, but will not be configured as an appended or a fallback owner.
5. In the **Links** section, click **Add** to add links to external documentation, such as runbooks, docs, logs, or custom categories.
6. In the **Slack channels** section, click **Add** to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.
7. In the **Parents** section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
8. In the **Children** section, select children entities. This is where you configure the hierarchy for your entity, which can be visualized in the [relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md).
5. Optionally, if you'd like to add another entity, click **Add entity** in the upper-right corner of the page.
6. Click **Confirm import**.\
The entity is imported into Cortex. If there are any errors, a banner appears at the bottom of the page with the errors that need to be fixed.
### Adding a domain in YAML via GitOps
The hierarchy of entities in Cortex is based on that hierarchy being defined in the entity's YAML file; Cortex does not set hierarchies based on a YAML file's location in your repository.
**Domain entity descriptor**
If your entity is a domain, you must specify `x-cortex-type` as `domain`:
```yaml
openapi: 3.0.1
info:
title: Payments
description: This is a description of the domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
```
**Domain hierarchies**
Hierarchies can be defined in two directions:
* **Top-down** (from the parent) - Use the `x-cortex-children` tag in the parent entity YAML to list its children.
* **Bottom-up** (from the child) - Use the `x-cortex-parents` tag in the child entity YAML to list its parents.
Both approaches produce the same hierarchy; choose whichever fits your workflow. For example, if you frequently update a group of child domains together, defining them on the parent YAML is often more efficient.
**Domain parents**
Define another entity as the parent for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace using the `x-cortex-parents` tag:
```yaml
openapi: 3.0.1
info:
title: Payments
description: This is a description of the domain.
x-cortex-tag: payments-domain
x-cortex-parents:
- tag: parent-domain-1
- tag: parent-domain-2
```
{% hint style="info" %}
Parent entities must be of type `domain`.
{% endhint %}
**Domain children**
Define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace using the `x-cortex-children` tag:
```yaml
openapi: 3.0.1
info:
title: Payments
description: This is a description of the domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-children:
- tag: child-domain-1
- tag: child-service-1
- tag: child-resource-1
```
**Ownership inheritance**
A common use case for domains is defining ownership for the subtree of entities. Instead of defining ownership individually for every entity in your catalog, you can define ownership at the domain level and have that pass down to all of its children:
```yaml
openapi: 3.0.1
info:
title: Payments
description: This is a description of the domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-owners:
- type: GROUP
name: cortexapps/engineering
provider: GITHUB
inheritance: APPEND
```
The `inheritance` type for each owner can be one of `APPEND`, `FALLBACK`, or `NONE`. If not set, inheritance is defaulted to `NONE`.
* `APPEND` - This owner is appended to the list of owners for all child entities.
* `FALLBACK` - In the case where a child has no valid owners, including fallbacks, this fallback will be assigned as the owner. Note that this only applies to a child entity down the hierarchy; it is not the fallback for the parent domain itself.
* `NONE` - This owner owns the domain, but not necessarily any of its children (no inheritance).
**Example cortex.yaml file**
{% hint style="info" %}
The YAML definition for a domain entity can take file names other than `cortex.yaml` or `cortex.yml`; see the [GitOps example repository structure](/configure/gitops.md#how-gitops-works-in-cortex).
{% endhint %}
Expand to see the example YAML
```yaml
openapi: 3.0.1
info:
title: Chat
description: Chat domain.
x-cortex-tag: chat-domain
x-cortex-type: domain
x-cortex-children: # children can be of type service, resource, or domain
- tag: chat-service
- tag: chat-database
x-cortex-parents: # parents can be of type domain only
- tag: payments-domain
- tag: web-domain
x-cortex-owners:
- type: group
name: Support
provider: OKTA
description: Support Team
x-cortex-slack:
channels:
- name: support-team
notificationsEnabled: true
description: This is a description for the support-team Slack channel # optional
x-cortex-oncall:
pagerduty:
id: ASDF2345
type: SCHEDULE
x-cortex-apm:
datadog:
monitors:
- 23456
```
### Adding a domain via the Cortex API
You can create, update, and delete domains using the Cortex API. See [Catalog entities](/api/readme/catalog-entities.md) for more information.
## Viewing domains
The **Domains** page lists every service entity that's been imported into Cortex. To open it, expand **Catalogs** in the main sidebar and select **Domains**. The page opens to the **Mine** tab if you own any domains, and defaults to the **All** tab otherwise. Each row shows the domain's name and tag.
### Searching across and filtering domains
There are several ways to search and filter your domains list.
1. From the main sidebar, expand **Catalogs**, then select **Domains.**
2. Do one of the following:
* Select the **All** tab to search and filter across all of your organization's domains.
* Select the **Mine** tab to search and filter only the domains you own.
3. Do any or all of the following:
* To find specific domains, use the search bar in the upper-right corner of the domains list and type to search.
* Click **Name** to select whether you want to sort by name or identifier, and whether to sort by ascending or descending order.
* Click **Display** to choose whether to show archived domains in the list, and select which columns to display alongside domains. See [Viewing the domain hierarchy](#displaying-domains-in-hierarchy) below.
* Click **Filter** to narrow down your list by domain, entity type, group, owner, or team.
### Viewing the domain hierarchy
Follow the steps below to display domains in hierarchy.
1. From the main sidebar, expand **Catalogs**, then select **Domains.**
2. Click **Display** at the top of the domains list.
3. Toggle on **Display hierarchy**.
4. Click **Done**.
{% hint style="info" %}
You can also view the hierarchy for a given domain on its [entity details page](/ingesting-data-into-cortex/entities-overview/entities/details.md).
{% endhint %}
### Viewing the Relationships page
If the domain has parents or children, those appear on the Relationships page.
To access the Relationships page of an entity:
1. From the main sidebar, expand **Catalogs**, then select **Domains.**
2. Click **Display** at the top of the domains list.
3. Select the entity whose relationship graph you want to view.
4. In the entity sidebar, select **Relationships**.
5. Do any of the following:
1. Click the **Archive icon** to show or hide archived relationships.
2. Click the **Filter icon** to narrow the scope of the graph.
3. By default, the domain hierarchy is displayed as a graph. Click the **Table mode** icon to switch to a tabular view.
4. Click **Configure** in the upper-right corner to configure the relationship type and its associated entities.
See [Relationship graph](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md) for more information.
## Editing a domain entity
Users with the `Edit Catalog` and `Edit Domains` permissions can edit domain entities.
Domain entities can be modified at any time. Follow the steps below to edit a domain entity.
1. Navigate to the entity's page.
2. In the upper-right corner, click **Configure entity**.\
The entity details page opens.
3. In the upper-right corner, select either **UI editor** or **YAML editor**.
4. Make your changes. Note that the Cortex tag is uneditable.
5. Click **Save changes**.\
The domain entity is updated.
{% hint style="info" %}
It's possible to change the entity type via the Cortex YAML. See [Changing an entity's type](/ingesting-data-into-cortex/entities-overview/entities.md#changing-an-entitys-type) for more information.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/domains.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.