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 two distinct 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.
- Resources - any entity that is not a service, such as infrastructure assets, kafka topics, custom types, etc.
When you log in you'll see this distinction immediately in the top navigation.
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.
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.
We use the OpenAPI spec as a base for service 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
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 both Service Entities and Resource Entities.
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-link:
- name: Chat ServiceAPI Spec
type: OPENAPI
url: ./docs/chat-service-openapi-spec.yaml
x-cortex-groups:
- python-services
x-cortex-owners:
- type: group
name: Delta
provider: OKTA
description: Delta Team
- type: slack
channel: delta-team
notificationsEnabled: true
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-owners:
- type: group
name: CloudOps
provider: OKTA
description: Cloud Operations Team
- type: slack
channel: cloudops-team
notificationsEnabled: true
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
x-cortex-type: domain
x-cortex-children:
# children can be of type service, resource, or domain
- tag: chat-service
- tag: chat-database
x-cortex-domain-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
- type: slack
channel: support-team
notificationsEnabled: true
x-cortex-oncall:
pagerduty:
id: ASDF2345
type: SCHEDULE
x-cortex-apm:
datadog:
monitors:
- 23456