LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • Viewing domains
  • Display in hierarchy
  • View in relationship graph
  • Creating domains and a hierarchy
  • Edit domains
  • Adjusting domain settings

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex
  2. Managing Entities
  3. Adding entities

Add domains

Last updated 17 days ago

Was this helpful?

Domains offer a way 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 . 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.

Viewing domains

You can view all domains under Catalogs > Domains.

Display in hierarchy

To display domains in a hierarchy:

  1. Click Display at the top of the domains list.

  2. Click Done.

In the entity's side bar, click Relationships, then click the Hierachy tab.

View in relationship graph

Creating domains and a hierarchy

You can create domains:

  • By importing them from a connected integration

  • Manually in the Cortex UI

For simplicity, we recommend adding the highest-level domain first and then selecting it as the parent for subsequent domains. However, you can add parents and children to any domain at any point.

Importing domains

You can import domains directly from third-party integrations:

  1. In Cortex, navigate to Catalogs > All entities, then click Import entities.

  2. Select the integration to import from.

    • If you have a large volume of entites, click Filter in the upper right corner of the results list to select and apply entity type filters.

  3. At the bottom of the page, click Next step.

  4. Edit the details for the entity:

    • Type: Select Domain.

    • Entity name: Enter a human readable name.

    • Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.

    • Description: Enter a description of the entity to help others understand its purpose.

      • 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 will own the domain you are creating, but will not be configured as an appended or a fallback owner.

    • On-call: Configure on-call information.

    • Repository: Select the repository associated with this entity.

    • When you are finished, click Confirm import at the bottom of the page.

  5. Click Confirm import.

Manually creating domains

  1. In the main nav of Cortex, click Catalogs > Domains.

  2. At the top of the Domains page, click +Import entities.

  3. Configure the form:

    • Type: Select Domain.

    • Entity name: Enter a human readable name.

    • Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.

    • Description: Enter a description of the entity to help others understand its purpose.

    • Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.

      • 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 will own the domain you are creating, but will not be configured as an appended or a fallback owner.

    • On-call: Configure on-call information.

    • Repository: Select the repository associated with this entity.

  4. When you are finished, click Confirm import at the bottom of the page.

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:

openapi: 3.0.1
info:
  title: Payments
  description: This is my cool domain.
  x-cortex-tag: payments-domain
  x-cortex-type: domain

Domain hierarchies

These can be defined in two ways:

  • From the parent entity YAML

    • Define children entities using the x-cortex-children tag in the parent entity YAML.

  • From the child entity YAML

    • Define parent entities using the x-cortex-parents tag in the child entity YAML.

While defining these relationships top-down (on the parent entity) or bottom-up (on the child entity) will both result in a hierarchy, you may choose one or the other depending on your workflow. For example, if you are frequently making changes to a group of children domains, it may be more efficient to have the children defined on the parent YAML.

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.

openapi: 3.0.1
info:
  title: Payments
  description: This is my cool 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

Domain parents

Define another entity as the parent for a domain, allowing you to represent a hierachy of how your entities are modeled across your workspace using the x-cortex-parents tag.

openapi: 3.0.1
info:
  title: Payments
  description: This is my cool domain.
  x-cortex-tag: payments-domain
  x-cortex-parents:
  - tag: parent-domain-1
  - tag: parent-domain-2

Note: Parents must be of type domain.

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.

openapi: 3.0.1
info:
  title: Payments
  description: This is my cool 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

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

Creating domains via the API

Edit domains

It is possible to edit entities after creating them:

  1. Navigate to the entity's page.

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

  3. Make any desired changes.

    • Note: The only field you cannot edit is the identifier.

  4. At the bottom of the screen, click Save changes.

Adjusting domain settings

Enable to toggle next to Display hierarchy.

You can also view the hierarchy for a given domain on its . If the domain has parents or children, those will appear on the Relationships page.

At the top of the domain, click View in domains tree to visualize your domain hierarchy in the .

Via the entity descriptor YAML through

Via the

Choose Import discovered entities.

On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.

Groups: Optionally select your entity.

Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes. You may see owners that Cortex . You can accept or reject the recommendations.

Parents and Children: Define parent and children domains. This is where you configure the hierarchy for your domain. These can be visualized in the .

If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.

Choose Create entities manually.

Groups: Optionally select your entity.

Parents and Children: Define parent and children domains. This is where you configure the hierarchy for your domain. These can be visualized in the .

Note: the YAML definition for a domain entity can take file names other than cortex.yaml or cortex.yml; see the .

You can create, update, and delete domains using the .

Under , you can enable automatic import of domains and domain relationships from .

entity details page
relationship graph
GitOps
API
groups to segment
relationship graph
groups to segment
relationship graph
Cortex API
Settings > Entities > Domains
ServiceNow
relationship graph
recommends based on repository activity
GitOps example repository structure
View all domains in the Domains page.
The hierarchy appears in a domain's "Relationships" section.