Skip to main content

Entities

An entity is an object that represents a software construct. A defined collection of entities is known as a catalog. All entities can be Scorecarded, can exist in a catalog, are represented in YAML, and can pull in data from integrations. Every entity has an overview page in Cortex where you can view more details about it.

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 (stemming from cortex.yaml, the name of the file that powers the GitOps approach.)

Default entity types​

By default, Cortex supports four 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. Infrastructure: An entity representing your infrastructure assets, such as Kafka topics, databases, and storage.
  3. Domains: An entity that allows you to group your services, resources, and other domains into hierarchical, logical units
  4. Teams: An entity to store all of your team data

Custom entity types​

In addition to the built-in entity types listed above, you can also create your own custom entity 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. It is possible to customize the entity tag.

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.

Cortex ID​

A Cortex ID (CID) is a unique, immutable entity ID that can be used outside of Cortex for historical tracking and reporting. It can be used in the API, in CQL queries, and in-app. The ID is automatically generated by Cortex and it is 18 characters in length.

In Cortex, the CID for an entity appears in the URL for an entity and at the top of an entity page: The Cortex ID is in the URL and at the top of the entity page

The CID does not appear in an entity's YAML file, as it cannot be modified.

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.

Editing in the UI or via GitOps​

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.

We 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!

Note that it is not currently supported to include comments in YAML files.

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

Use groups to link your team entity with a team on a different platform that you have integrated with Cortex. You can only link one group to a team entity.

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

Under groups, when you specify okta-security-team, your team will contain all the members from your 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 roles. For example, the following entity includes a member who has the product-manager role and a member who has both the engineering-manager role and manager role:

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
        roles: 
          - tag: product-manager
      - name: Engineering Manager
        email: engineering-manager@cortex.io
        notificationsEnabled: true
        roles: 
          - tag: engineering-manager
          - tag: manager

After specifying the YAML example above, your team now will contain Product Manager and Engineering Manager. 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 (i.e., it would start showing up in their Mine tab in catalogs that contain teams).

Roles must be defined for your workspace in your Entity Settings page, under the "Teams" tab. For more information about adding roles, see Getting Started > Teams.

tip

The role field in member is optional.

caution

In order to be considered valid, a team must have a non-empty group as described in the section above.

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