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 are represented in YAML, can pull in data from integrations, and can be Scorecarded. Every entity has an overview page in Cortex where you can view more details about it.

Entity types​

You can create your own entity types or use one of the default entity types.

By default, Cortex supports the following entity types:

  • Services: The default type and the core of your catalog, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module.
  • Domains: An entity that allows you to group your services, resources, and other domains into hierarchical, logical units
  • Teams: An entity to store all of your team data
  • Cortex also supports pulling in resources directly from AWS, Azure Resources, and Google Cloud as their corresponding types out of the box

Learn more about custom and default entity types below.

Defining entities via YAML file​

Whether you use the UI or GitOps to manage entities, every entity in your Cortex catalogs is defined 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.)

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.

Adding metadata to the entity descriptor​

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.

Managing entities​

Editing in the UI or via GitOps​

By default, your account is configured to edit entities through the UI. We recommend starting with the UI editor, which includes a built-in YAML editor, then switching over to GitOps when ready for a wider rollout.

If you want to use GitOps to manage your entity YAML files, you can change this setting:

  1. In Cortex, navigate to Settings > Entities and click the GitOps tab.
  2. Under "Options by entity type," click the toggles under UI editing to enable UI editing for each entity type.

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 or you can store the YAML in the repository of the corresponding service.

See the single repository example below:

.
└── .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

Unique identifiers for entities​

Entity tag​

The entity tag - the value of x-cortex-tag in an entity's YAML file - 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 the Cortex Slack Bot.

The entity tag must be globally unique across all entities. It is possible to customize the entity tag.

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, in-app, and you can use it with the Cortex Slack Bot. 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.

Understanding the entity types​

See the tabs below to learn more about services, domains, teams, and custom entity types.

Service entities​

Service entity 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

Required fields​

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 for a service​

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