Add domains

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. Choose Create entities manually.

4. 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.

   • Groups: Optionally select groups to segment 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.

     • 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.

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

   • On-call: Configure on-call information.

   • Repository: Select the repository associated with this entity.

5. 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

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

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

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