Can't find what you need? Tell us what's missing.
Take the survey
Ctrlk
Get a DemoCortex AcademyWebsiteStatusLogin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Defining entities with YAML

Every entity in your Cortex catalog is defined by a YAML file called the Cortex entity descriptor—often referred to as an entity's Cortex YAML, after the cortex.yaml filename used in the GitOps approach. This applies whether you manage entities through the UI or GitOps; the descriptor is the underlying source of truth either way.

Each descriptor is a fully compliant OpenAPI 3 spec file, extended with Cortex-specific fields that unlock additional functionality in your catalog.

You don't need to use OpenAPI or Swagger to use Cortex. The OpenAPI spec serves as the foundation for entity metadata because it's an open standard with official support for extensions, allowing Cortex to extend it into a full entity descriptor spec, while keeping the actual OpenAPI fields optional.

Metadata in entity descriptor YAML files

You can extend an entity by adding metadata to the info section of its descriptor. Throughout the docs, you'll see snippets prefixed with x-cortex-*; these are descriptor blocks that belong inside info and unlock additional Cortex functionality.

YAML comments aren't supported in entity descriptors. Cortex stores descriptors as JSON in the database, and JSON doesn't support comments. Most YAML parsers also strip comments during round-tripping, so any comments added to a descriptor will be lost.

Required blocks

Every entity YAML requires the following:

Block
Description

title

The name of the entity

x-cortex-tag

The unique identifier for the entity

x-cortex-type

The entity type

  • If the entity is a custom type, you must also include x-cortex-definition

Recommended blocks

Although they aren't required, it's strongly recommended to add a description, groups, and owners:

Block
Definition

description

A description of the entity

x-cortex-groups

The entity's groups - a tagging system used to segment entities

  • Required field - tag

x-cortex-owners

The entity's owners

  • Required field(s) - type, which can be group or email

    • For group owners, name and provider are also required. The provider value is the integration the group comes from; use CORTEX for a team defined in Cortex.

    • For email owners, email is also required

  • inheritance - When creating a domain entity and adding owners to it, or while creating an entity relationship, you can set ownership inheritance under this block to pass down to the entity's children. The inheritance type can be APPEND, FALLBACK, or NONE.

Additional basic metadata blocks

Block
Definition

x-cortex-custom-metadata:

The entity's custom data

  • Required fields - a key, value, and description. The key is the title for the custom data.

x-cortex-dependency

The entity's dependencies

  • Required fields - tag. If method is included, then path is also required.

x-cortex-link

Documentation links associated with the entity: name, type, and url

x-cortex-parents and x-cortex-children

The entity's parent entities and children entities

x-cortex-relationships

A block that includes the entity's relationship type and destination entities

  • Required fields - type and destinations

x-cortex-team

This appears in a team entity's YAML. members can be defined under this block.

  • A member is defined by name and email, and can also include notificationsEnabled and roles.

Integration metadata blocks

See the related linked documentation pages for instructions on adding metadata within each type of block.

Block

x-cortex-alerts

Opsgenie

x-cortex-apiiro

Apiiro

x-cortex-apm

Datadog, Dynatrace, New Relic

x-cortex-azure

Azure Resources

x-cortex-azure-devops

Azure DevOps

x-cortex-bugsnag

BugSnag

x-cortex-ci-cd

Buildkite

x-cortex-checkmarx

Checkmarx

x-cortex-circle-ci

CircleCI

x-cortex-coralogix

Coralogix

x-cortex-dashboards

Charts embedded from Datadog, Grafana, or New Relic

x-cortex-firehydrant

FireHydrant

x-cortex-git

Azure DevOps, Bitbucket, GitHub, GitLab

x-cortex-incident-io

incident.io

x-cortex-infra

AWS, Google

x-cortex-issues

ClickUp, GitHub, Jira

x-cortex-k8s

Kubernetes

x-cortex-launch-darkly

LaunchDarkly

x-cortex-microsoft-teams

Microsoft Teams channels

x-cortex-oncall

PagerDuty, Splunk On-Call (VictorOps), xMatters

x-cortex-owners

When you specify group as the type, you can use the following integrations as the group provider: BambooHR, Bitbucket, Entra ID (Azure AD), GitHub, GitLab, Google, Okta, ServiceNow, Workday

x-cortex-rollbar

Rollbar

x-cortex-rootly

Rootly

x-cortex-sentry

Sentry

x-cortex-semgrep

Semgrep

x-cortex-servicenow

ServiceNow

x-cortex-slack

Slack channels

x-cortex-slos

Datadog, Dynatrace, Google, Lightstep, Prometheus, Splunk Observability Cloud (SignalFX), Sumo Logic

x-cortex-snyk

Snyk

x-cortex-static-analysis

Codecov, Mend, SonarQube, Veracode

x-cortex-wiz

Wiz

Example entity YAML

The example below demonstrates how you can use each of the blocks in an entity's YAML.

PreviousManaging entitiesNextYAML linter tool

Last updated

Was this helpful?