Skip to main content

Entities

The core of Cortex is a catalog. Every entity in your Cortex catalogs is described by a YAML file called the Cortex entity descriptor, also referred to as an entity's Cortex YAML (naturally stemming from cortex.yaml, the name of the file that powers the GitOps approach!).

By default, Cortex supports three distinct types of entities:

  1. Services - the default type and the core of your catalog, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module.
  2. Domains - an entity that allows you to group your services, resources, and other domains into hierarchical, logical units
  3. Teams - an entity to store all of your team data

Cortex also provides built-in types for infrastructure assets including Kafka topics, databases, and storage. Additionally, you can create your own custom types.

Entity tag

You'll see us refer to the "entity tag" throughout the docs. The entity tag is a unique identifier that's used throughout Cortex. For example, the entity tag is used to declare dependencies on other entities or look up information using our Slackbot. The entity tag must be globally unique across all entities.

tip

Any time you see a mention of a entity tag, we're referring the value of x-cortex-tag in the Cortex entity descriptor.

Entity descriptor

Regardless of whether you're using UI editing or GitOps to manage your entities, the definitions are backed by YAML files. Each file is a fully compliant OpenAPI 3 spec file, with our own Cortex-specific extensions.

You can still use Cortex if you don't use OpenAPI/Swagger!

We use the OpenAPI spec as a base for entity metadata, since it's an open spec with official support for extensions. That lets us extend it to be an entity descriptor spec with optional usage of actual OpenAPI fields.

By default, your account is set up to edit entities through our UI. However, if you want to use GitOps to manage your entity YAML files, you can do so by changing the setting in Settings → Workspace → Entities → GitOps → UI Editor. You can choose different editing approaches for different entity types.

UI editing

We highly recommend starting with the UI editor (which includes a built-in YAML editor) and switching over to GitOps when ready for a wider rollout.

Adding more information

Any additional metadata you want to add to your descriptor belongs in the info section. Throughout the docs, you'll see snippets that start with x-cortex-* – make sure to add this to the info section!

Service entities

Service descriptor

A barebones spec file has the OpenAPI version, along with an info section that contains some basic details.

openapi: 3.0.1
info:
title: My Service
description: This is my cool service.
x-cortex-tag: my-service
x-cortex-type: service

The only required fields under info are the title, x-cortex-tag, and x-cortex-type. The description is optional, but we highly recommend adding descriptions to all of your entities.

Example cortex.yaml

openapi: 3.0.1
info:
title: Chat Service
description: Chat service is responsible for handling chat feature.
x-cortex-tag: chat-service
x-cortex-type: service
x-cortex-parents: # parents can be of type domain only
- tag: notifications-domain
- tag: support-domain
x-cortex-groups:
- python
x-cortex-owners:
- type: group
name: Delta
provider: OKTA
description: Delta Team
x-cortex-slack:
channels:
- name: delta-team
notificationsEnabled: true
description: This is a description for the delta-team Slack channel # optional
x-cortex-link:
- name: Chat ServiceAPI Spec
type: OPENAPI
url: ./docs/chat-service-openapi-spec.yaml
x-cortex-custom-metadata:
core-service: true
x-cortex-dependency:
- tag: authentication-service
- tag: chat-database
x-cortex-git:
github:
repository: org/chat-service
x-cortex-oncall:
pagerduty:
id: ASDF1234
type: SCHEDULE
x-cortex-apm:
datadog:
monitors:
- 12345
x-cortex-issues:
jira:
projects:
- CS

Domain entities

Domain entities allow you to group all of your entities into hierarchical, logical units.

For example, you could represent Cortex's Scorecards system in the following hierarchy:

Scorecards [Domain]
└── CQL [Domain]
| ├── Parser [Service]
└── Evaluator [Domain]
| ├── Async Evaluator Service [Service]
| ├── Scorecard Cache [Service]

Domain descriptor

If your entity is a domain, you must also specify x-cortex-type as domain. You can read more about the Domains catalog here.

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

Domain 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 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

This hierarchy is available to look at across catalog pages that contain domains, such as the default Domains catalog. It can also be used to inherit ownership across different levels.

Domain parents

Domain children allow you to define the domain relationship from the top-down, but in some cases it may be easier to define the domain hierarchy from the bottom-up. For these cases, the x-cortex-parents can be added to any entity's YAML to define its parents.

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

One major use-case for domains is defining ownership for the subtree of entities. Instead of defining ownership individually for every single 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.

  • APPEND [Default]: 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.
  • 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; please refer to the Domains catalog for more details.

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

Team entities

Team entities allow you to store all of your team data in Cortex. Your other entities can then interact with your teams by providing a x-cortex-owners field in their entity descriptors.

Team descriptor

If your entity is a team, you must also specify x-cortex-type as team. You can read more about the Teams catalog here.

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

Groups and members in the x-cortex-team section

The x-cortex-team tag has two main sections: groups and members.

Groups

groups can be used to link your team entity with a team on a different platform that you have integrated with Cortex. For example, you can specify:

openapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
groups:
- name: okta-security-team
provider: OKTA

And with specifying that, your team will contain all the members from the okta-security-team! Now, if you specify the okta-security-team in your x-cortex-owners on any of your other entities, they will automatically recognize example-team as a team that owns their entity.

Members

members can be used to add individual members to your team when you have a use case for a team entity that doesn't correspond exactly to a team on one of your integrations. Members support a role so that you can specify if someone is an Engineering Manager, Product Manager, or Designer. For example, you can specify:

openapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
members:
- name: Product Manager
email: product-manager@cortex.io
notificationsEnabled: true
role: product-manager
- name: Engineering Manager
email: engineering-manager@cortex.io
notificationsEnabled: true
role: engineering-manager

And with specifying that, your team now will contain Product Manager and Engineering Manager. Now, if product-manager@cortex.io or engineering-manager@cortex.io were to correspond with the email of an actual account in Cortex, they would start seeing example-team being displayed as a team that they're a part of (e.g. it would start showing up in their Mine tab in catalogs that contain teams).

For consistency, roles must be defined for your workspace under the "team members roles" section in Settings → Entities → Teams.

tip

The role field in member is optional.

caution

In order to be considered valid, a team must either have a non-empty group, described in the section above, or have at least one member with notificationsEnabled: true.

Team children

You can define a list of other teams as children, allowing you to represent a hierarchy of how your teams are modeled across your workspace, using the x-cortex-children tag.

openapi: 3.0.1
info:
title: Payments
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-children:
- tag: child-team-1
- tag: child-team-2

This hierarchy is available to look at in the Teams catalog page.

Team parents

Team children allow you to define the team relationship from the top-down, but in some cases it may be easier to define the team hierarchy from the bottom-up. For these cases, x-cortex-parents can be added to any entity's YAML to define its parents.

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

Example cortex.yaml

Note: the YAML definition for a team entity can take file names other than cortex.yaml or cortex.yml; please refer to the Teams catalog for more details.

openapi: 3.0.1
info:
title: Chat Team
description: Chat team.
x-cortex-tag: chat-team
x-cortex-type: team
x-cortex-team:
groups:
- name: okta-chat-team
provider: OKTA
members:
- name: Product Manager
email: product-manager@cortex.io
notificationsEnabled: true
- name: Engineering Manager
email: engineering-manager@cortex.io
notificationsEnabled: true
x-cortex-children: # children can be of type team
- tag: chat-infra-team
- tag: chat-sre-team
x-cortex-slack:
channels:
- name: chat-team
notificationsEnabled: true
description: This is a description for the chat-team Slack channel # optional
x-cortex-oncall:
pagerduty:
id: ASDF2345
type: SCHEDULE

Other types of entities

Other type descriptor

If your entity is of a different type, you must specify x-cortex-type and x-cortex-definition. The x-cortex-definition field is validated against the entity type definition. If your custom entity type does not have specific requirements, entities of that type still need a non-null definition specified, like x-cortex-definition: {}.

openapi: 3.0.1
info:
title: My Database
description: This is my cool MySQL database.
x-cortex-tag: my-database
x-cortex-type: mysql
x-cortex-definition:
version: 8.0.29
distribution: percona

Example cortex.yaml

Note: the YAML definition for a custom entity can use file names other than cortex.yaml or cortex.yml. Please refer to the entity types for more details.

openapi: 3.0.1
info:
title: Chat Database
description: Chat service's database.
x-cortex-tag: chat-database
x-cortex-type: rds
# x-cortex-definition is required for custom x-cortex-type
x-cortex-parents: # parents can be of type domain only
- tag: notifications-domain
- tag: support-domain
x-cortex-owners:
- type: group
name: CloudOps
provider: OKTA
description: Cloud Operations Team
x-cortex-slack:
channels:
- name: cloudops-team
notificationsEnabled: true
description: This is a description for the cloudops-team Slack channel # optional
x-cortex-oncall:
pagerduty:
id: ASDF2345
type: SCHEDULE
x-cortex-apm:
datadog:
monitors:
- 23456

GitOps

When using GitOps, you can define any number of entities in any repository.

  • Domain definitions should live in the .cortex/domains directory in your repository.
  • Team definitions should live in the .cortex/teams directory in your repository.

You may store all of your entity definitions in a single repository.

.
└── .cortex
├── catalog
│ ├── database.yml
│ ├── s3-bucket.yml
│ ├── auth-service.yml
│ └── billing-service.yml
├── domains
│ ├── billing-domain.yml
│ └── health-domain.yml
├── teams
│ ├── eng-team.yml
│ └── sre-team.yml
└── scorecards
│ ├── service-readiness.yml
│ └── security.yml