Skip to main content

Catalog entities

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

Catalog entities are broken into four distinct types:

  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. Resources - any entity that is not a service, such as infrastructure assets, kafka topics, custom types, etc.
  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

When you log in you'll see this distinction immediately in the top navigation.

top-nav

By default, your account is set up to use GitOps. However, if you want to work without GitOps you can change the setting in Settings | App Preferences | Enable UI Editor.

UI editing

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

Catalog descriptor​

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

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 a catalog descriptor spec with optional usage of actual OpenAPI fields.

Service entities​

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

openapi: 3.0.0
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 and the x-cortex-tag.

Resource entities​

However, if your entity is not a service, you must also specify x-cortex-type and x-cortex-definition. The x-cortex-definition field is validated against the Resource Definition.

openapi: 3.0.0
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

Domain entities​

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

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

Team entities​

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

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

Entity tag​

You'll see us refer to the "entity tag" throughout the docs. The entity tag is a unique identifier that's used through Cortex, for example to declare dependencies on other services or to look up information using the Slackbot. The entity tag must be globally unique across Service, Resource, Domain, and Team Entities.

tip

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

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!

Example cortex.yaml for service entity​

openapi: 3.0.0
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

Example cortex.yaml for resource entity​

Note: the YAML definition for a resource entity can use file names other than cortex.yaml or cortex.yml; please refer to the Resource Catalog for more details.

openapi: 3.0.0
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

Example cortex.yaml for domain entity​

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

openapi: 3.0.0
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

Example cortex.yaml for team entity​

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

openapi: 3.0.0
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