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. 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.
When configuring an entity, you can't add archived teams as owners or archived entities as dependencies, parents, or children.
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
From the main sidebar, expand Catalogs, then select All entities.
In the upper-right corner, click Import entities.
Select Import discovered entities.
Select the integration to import from. The Select entities to import page is displayed.
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.
In the bottom-right corner, click Next step. The Edit details page is displayed.
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.).From the Type drop-down menu, select Domain.
In the Details section:
Below Entity name, enter a name for the entity (required).
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.Below Description, enter a description of the entity to help others understand its purpose.
From the Groups drop-down menu, select a group or groups to segment the entity.
In the Repository section:
From the Provider drop-down menu, select the repo provider.
From the Alias drop-down menu, select the alias of the connected provider account that has access to the repository.
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.
Below Basepath, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
In the Owners section, define ownership 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. 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.
In the Links section, click Add to add links to external documentation, such as runbooks, docs, logs, or custom categories.
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.
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.
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.
If you selected more than one entity, click Next entity in the bottom-right corner of the page.
Click Confirm import. The entity is imported into Cortex.
Manually adding domains
From the main sidebar, expand Catalogs, then select All entities.
In the upper-right corner, click Import entities.
Select Create entities manually. The Edit details page is displayed.
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.).From the Type drop-down menu, select Domain.
In the Details section:
Below Entity name, enter a name for the entity (required).
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.Below Description, enter a description of the entity to help others understand its purpose.
From the Groups drop-down menu, select a group or groups to segment the entity.
In the Repository section:
From the Provider drop-down menu, select the repo provider.
From the Alias drop-down menu, select the alias of the connected provider account that has access to the repository.
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.
Below Basepath, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.
In the Owners section, define ownership 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. 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.
In the Links section, click Add to add links to external documentation, such as runbooks, docs, logs, or custom categories.
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.
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.
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.
Optionally, if you'd like to add another entity, click Add entity in the upper-right corner of the page.
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:
Domain hierarchies
Hierarchies can be defined in two directions:
Top-down (from the parent) - Use the
x-cortex-childrentag in the parent entity YAML to list its children.Bottom-up (from the child) - Use the
x-cortex-parentstag 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:
Parent entities must be of type domain.
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:
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:
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
The YAML definition for a domain entity can take file names other than cortex.yaml or cortex.yml; see the GitOps example repository structure.
Adding a domain via the Cortex API
You can create, update, and delete domains using the Cortex API. See Catalog entities 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.
From the main sidebar, expand Catalogs, then select Domains.
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.
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 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.
From the main sidebar, expand Catalogs, then select Domains.
Click Display at the top of the domains list.
Toggle on Display hierarchy.
Click Done.
You can also view the hierarchy for a given domain on its entity details page.
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:
From the main sidebar, expand Catalogs, then select Domains.
Click Display at the top of the domains list.
Select the entity whose relationship graph you want to view.
In the entity sidebar, select Relationships.
Do any of the following:
Click the Archive icon to show or hide archived relationships.
Click the Filter icon to narrow the scope of the graph.
By default, the domain hierarchy is displayed as a graph. Click the Table mode icon to switch to a tabular view.
Click Configure in the upper-right corner to configure the relationship type and its associated entities.
See Relationship graph 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.
Navigate to the entity's page.
In the upper-right corner, click Configure entity. The entity details page opens.
In the upper-right corner, select either UI editor or YAML editor.
Make your changes. Note that the Cortex tag is uneditable.
Click Save changes. The domain entity is updated.
It's possible to change the entity type via the Cortex YAML. See Changing an entity's type for more information.
Last updated
Was this helpful?