# 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. {% hint style="info" %} 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. {% endhint %} ## 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. {% hint style="info" %} 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. {% endhint %} ### 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

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`

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

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 - `type` Owners can be defined by `group` from an ownership integration or by email address `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`.

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 - type
Owners can be defined by group from an ownership integration or by email address
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 Required field - `tag` These fields are supported for entities that are members of a hierarchical entity relationship, such as domains or teams
`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.

## API Spec and Version
openapi: 3.0.0

# Service Descriptors

# Required fields: info, title, x-cortex-tag
info:
  title: <HUMAN_READABLE_SERVICE_NAME>
  x-cortex-tag: <SERVICE_TAG>
   description: <DESCRIPTION>

  # Groups
  # !Groups must contain only alphanumeric characters, and may not contain whitespaces!
  x-cortex-groups:
    - <GROUP_NAME>
    - <GROUP_NAME>
    - <GROUP_NAME>
  
  # Owners
  x-cortex-owners:
    - type: group
      name: my-team
      provider: CORTEX # Use when referring to a team defined in Cortex; these teams do not map to identities from integrations
      description: This is a description for this owner
    - type: email
      email: user@example.com
      description: This is a description for this owner
    - type: group
      name: team-name
      provider: ACTIVE_DIRECTORY | AZURE_DEVOPS | BAMBOO_HR | GITHUB | GITLAB | GOOGLE | OKTA | OPSGENIE | SERVICE_NOW | WORKDAY
  # Also see the team entity example below
  
  # Links
  x-cortex-link:
     - name: <HUMAN_READABLE_NAME>
       type: <TYPE>
       url: <URL_TO_LINK>
       description: <DESCRIPTION>
  ## Note that type of OPENAPI/ASYNC_API will be displayed in the API Explorer tab in the Cortex UI
  ## Links support relative URLs

  # Dashboards
  x-cortex-dashboards:
   embeds:
     - type: <datadog | grafana | newrelic>
       url: <URL>

  # Custom Data
  x-cortex-custom-metadata:
     my-key: the value
     another-key:
       this: is
         an: object
     my-key-2:
       value: the actual value for the key
       description: This is the description
     final-key:
       - also
       - use
       - lists!
       
  # Custom entities
  # You cannot create a custom entity type via GitOps, but after creating the type in the UI or API, you can create custom entities via GitOps.
  title: Sally S
  description: Technical writer
  x-cortex-tag: employee-sally
  x-cortex-type: org-employees
  x-cortex-definition:
    location: San Diego
    department: Engineering

  # Parent and child relationships
  x-cortex-type: team
  x-cortex-children:
  - tag: child-team-1
  - tag: child-team-2
  
  x-cortex-type: domain
  x-cortex-parents:
  - tag: parent-team-1
  - tag: parent-team-2
  
  # Entity relationships
  x-cortex-relationships:
  - type: relationship-type-name
    destinations:
    - tag: destination-entity-1
    - tag: destination-entity-2
  

  # Dependencies
  # Required fields: x-cortex-tag, method (required if path present), path (required if method present)
  x-cortex-dependency:
       - tag: <TAG>
         method: <HTTP_METHOD>
         path: <PATH_FOR_METHOD>
         description: <DESCRIPTION>
         metadata:
           tags:
             - <TAG_1>
             - <TAG_2>
           prod: true
           
 # Team configurations
 title: Eng Team
 x-cortex-tag: eng-team
 x-cortex-type: team
 x-cortex-team:
   groups:
   - name: eng-team
     provider: OKTA
   members:
   - name: Eng Manager
     email: name@example.com
     notificationsEnabled: true 
   - name: Product Manager
     email: name@example.com
     notificationsEnabled: false
  x-cortex-children:
    - tag: infra-team
    - tag: sre-team
 
 # Domain configurations
   x-cortex-type: domain
   x-cortex-owners:
     - type: GROUP
       name: cortexapps/engineering
       provider: GITHUB
       interitance: APPEND | FALLBACK | NONE 
   x-cortex-children:
     - tag: chat-service
       tag: chat-database
       


  # Integrations
  
  # Apiiro
  x-cortex-apiiro:
    repositories:
      - alias: alias-one
        repositoryId: repository-one
      - alias: alias-two
        repositoryId: repository-two
    applications:
      - alias: alias-one
        applicationId: application-one
      - alias: alias-two
        applicationId: application-two
  
  # AWS Cloud Control types
  x-cortex-infra:
    aws:
      cloudControl:
      - type: AWS::RDS::DBInstance
        region: us-west-2
        accountId: "123456123456"
        identifier: rds-example
  
  # AWS ECS
  x-cortex-infra:
    aws:
      ecs:
        - clusterArn: <CLUSTER_ARN>
          serviceArn: <SERVICE_ARN>
        - clusterArn: <CLUSTER_ARN_2>
          serviceArn: <SERVICE_ARN_2>

  # Azure DevOps
  x-cortex-git:
    azure:
      project: <project-name>
      repository: <repository-name>
       
  # Azure Resources
  x-cortex-azure:
    ids:
    - id: /subscriptions/1fbb2da1-2ce7-45e4-b85f-676ab8e12345/resourceGroups/GROUP1/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e9
      alias: my-default-alias # alias is optional and only relevant if you have opted into multi account support
    - id: /subscriptions/1fbb2da1-2ce8-45e4-b85f-676ab8e12345/resourceGroups/GROUP2/providers/Microsoft.Compute/disks/vm1_disk1_3d9f85717666435e9e87e4883d31a7e0
      alias: my-other-alias # alias is optional and only relevant if you have opted into multi account support

  # BambooHR
  x-cortex-owners:
    - type: group
      name: <TEAM_NAME>
      provider: BAMBOO_HR
      description: # optional

  # Bitbucket
  x-cortex-git:
    bitbucket:
      repository: <workspace>/<repo>
   x-cortex-owners:
       - type: group
         name: <TEAM_NAME>
         provider: BITBUCKET
         description: # optional
         
  # Bugsnag
  x-cortex-bugsnag:
    project: <PROJECT_KEY> # projectKey in Bugsnag
     
  # Buildkite
  x-cortex-ci-cd:
    buildkite:
      pipelines:
        - slug: my-buildkite-pipeline-slug-1
        - slug: my-buildkite-pipeline-slug-2
      tags:
        - tag: my-buildkite-tag-1
        - tag: my-buildkite-tag-2

  # Checkmarx
  x-cortex-checkmarx:
    projects:
      - projectName: My Cool Project
      - projectId: 1234
  
  # CircleCI
  x-cortex-circle-ci:
      projects:
      - projectSlug: circleci-projectslug # projectslug in CircleCI
        alias: circleci-alias # alias is optional and only relevant if you have opted into multi account support
  
  # ClickUp
  x-cortex-issues:
    clickup:
      spaces:
      - identifier: 123456789
        identifierType: ID
      folders:
      - identifier: my-folder
        identifierType: NAME
      tags:
      - name: tag a
      - name: tag b
  
  # Codecov
  x-cortex-static-analysis:
    codecov:
      owner: org-name
      repo: my-project
      provider: AZURE_DEVOPS | BITBUCKET | BITBUCKET_SERVER | GITHUB | GITHUB_ENTERPRISE | GITLAB | GITLAB_ENTERPRISE
      flag: flag

  # Coralogix
  x-cortex-coralogix:
    applications:
    - applicationName: my-app # application name tied to alert
      alias: my-alias # alias is optional and only relevant if you have opted into multi account support
  
  # Datadog
  x-cortex-apm:
    datadog:
      serviceTags: # List of tags & values
       - tag: <KEY>
         value: <VALUE>
       - tag: <KEY>
         value: <VALUE>
  .   serviceName: <NAME IN DATADOG>
      monitors:
        - monitor-id
        - monitor-id-2
  x-cortex-slos:
     datadog: # List of SLO ids
       - id: slo-id-1
       - id: slo-id-1

  # Dynatrace
  x-cortex-apm:
    dynatrace:
      entityIds:
        - mock-service-id-1
        - mock-service-id-2
      entityNameMatchers:
        - "foo.*"
  x-cortex-slos:
    dynatrace:
      - id: slo-id-1
      - id: slo-id-2

  # Entra ID (Azure Active Directory)
  x-cortex-owners:
     - type: group
       name: <TEAM_NAME>
       provider: ACTIVE_DIRECTORY
       description: # optional

  # FireHydrant
  x-cortex-firehydrant:
    services:
      - identifier: ASDF1234
        identifierType: ID
      - identifier: service-slug
        identifierType: SLUG

  # GitHub
  x-cortex-git:
    github:
      repository: <org>/<repo>
      basepath: <SERVICE_NAME> # optional
   x-cortex-owners:
     - type: group
       name: <ORGANIZATION>/<TEAM> # Must be of form <org>/<team>
       provider: GITHUB
       description: # optional


  # GitLab
  x-cortex-git:
    gitlab:
      repository: <namespace>/<project>
      basepath: <SERVICE_NAME> # optional
  x-cortex-owners:
    - type: group
      name: Team Name
      provider: GITLAB
      description: This is a description for this owner


  # Google
  x-cortex-owners:
    - type: group
      name: <GROUP_NAME>
      provider: GOOGLE
  x-cortex-dependency:
    gcp:
      labels:
        - key: my-key-1
          value: my-value-1
        - key: my-key-2
          value: my-value-2
  x-cortex-infra:
    Google Cloud:
      resources:
        - resourceName: location/function
          projectId: project1
          resourceType: function
        - resourceName: example-bucket
          projectId: project1
          resourceType: storage
  x-cortex-slos:
    gcp:
      - projectId: cortex-gcp-integration
        serviceId: iLE2e4HvR_iVlxAaBbCc12
      - projectId: cortex-gcp-integration
        serviceId: adfdfdafd

  # Grafana
  x-cortex-dashboards:
    embeds:
      - type: grafana
        url: <embed_url_to_dashboard>
         
  # incident.io
  x-cortex-incident-io:
    customFields:
    - name: Entity
      value: My Entity
      alias: my-default-alias
    - id: Entity_ID
      value: my-second-entity
      alias: my-other-alias

  # Jira
  x-cortex-issues:
    jira:
      labels:
        - <LABEL1>
        - <LABEL2>
      components:
        - <COMPONENT1>
      projects:
        - project1
  # Optional: Override Cortex default Jira query
      defaultJql: 'status = "In Progress"'

  # Kubernetes
  x-cortex-k8s:
    deployment:
      - identifier: namespace/name
        cluster: dev # optional
      - identifier: experiment/scratch
        cluster: dev
      - identifier: default/cortex
        cluster: prod
    argorollout:
      - identifier: namespace/name
        cluster: dev
    statefulset:
      - identifier: namespace/name
        cluster: dev
    cronjob:
       - identifier: namespace/name
         cluster: dev

  # LaunchDarkly
  x-cortex-launch-darkly:
    projects:
      - key: project-key
        environments: # Optional
          - environmentName: prod
          - environmentName: staging
        alias: alias-1 # alias is optional and only relevant if you have opted into multi account support
      - tag: project-tag
        environments: # Optional
          - environmentName: prod
        alias: alias-2 # alias is optional and only relevant if you have opted into multi account support
    feature-flags:
      - tag: feature-flag-tag
        environments: # Optional
          - environmentName: staging
        alias: alias-3 # alias is optional and only relevant if you have opted into multi account support
  
  # Lightstep
  x-cortex-slos:
    lightstep:
      - streamId: <STREAM_ID>
        targets:
        latency:
          - percentile: <PERCENTILE>
            target: <TARGET>
            slo: <SLO>

  # Mend
  x-cortex-static-analysis:
    mend:
      applicationIds:
        - mend_id_1
        - mend_id_2
      projectIds:
        - project_id_1
        - project_id_2
  
  # Microsoft Teams
  x-cortex-microsoft-teams:
    channels:
    - name: team-engineering
      teamName: engineering
      description: This is a description for the engineering channel in Teams.
      notificationsEnabled: true
  
  # New Relic
  x-cortex-apm:
    newrelic:
      applications:
      - applicationId: <APP_ID>
        alias: default-app
      tags:
      - tag: tagKey
        value: tagValue
        alias: default-app
  x-cortex-dashboards:
    embeds:
      - type: newrelic
        url: <FULL_URL_TO_DASHBOARD>
  
  # While the `applications` wrapper format is the recommended format, Cortex also supports a flat array format:
  # x-cortex-apm:
  #   newrelic:
  #     - applicationId: <APP_ID>

  # Okta
  x-cortex-owners:
    - type: group
      name: <GROUP_NAME> # group name in Okta
      provider: OKTA
      description: # optional

  # OpsGenie
  x-cortex-oncall:
    opsgenie:
      type: SCHEDULE
      id: <SCHEDULE_ID> # Optionally, can use the Rotation UUID instead
  x-cortex-owners:
    - type: group
      name: <GROUP_NAME>
      provider: OPSGENIE
      description: # optional
  x-cortex-alerts:
    - type: opsgenie
      tag: <KEY>
      value: <VALUE>

  # PagerDuty
  x-cortex-oncall:
    pagerduty:
      id: <SERVICE_ID> # Service ID
      type: SERVICE
  x-cortex-oncall:
    pagerduty:
      id: <SCHEDULE_ID> # Schedule ID
      type: SCHEDULE
  x-cortex-oncall:
    pagerduty:
      id: <POLICY_ID> # Escalation Policy ID
      type: ESCALATION_POLICY

  # Prometheus
  x-cortex-slos:
    prometheus:
      - errorQuery: <query>
        totalQuery: <query>
        slo: <slo target number>
        alias: my-prometheus-instance
        name: my-slo-name

  # Rollbar
  x-cortex-rollbar:
    project: <PROJECT_NAME> # projectName in Rollbar
     
  # Rootly
  x-cortex-rootly:
    services:
      - id: ASDF1234
      - slug: service-slug

  # Sentry
  x-cortex-sentry:
    projects:
      - name: my-project # projectName in Sentry
      - name: my-second-project
     
  # Semgrep
  x-cortex-semgrep:
    projects:
    - alias: my_org 
      projectId: 1234567
    - alias: other_org
      projectId: 7654321

  # ServiceNow
  x-cortex-servicenow:
    services:
    - tableName: cortex-services
      id: 1
  x-cortex-owners:
    - type: group
      name: My ServiceNow Team
      provider: SERVICE_NOW
      description: This is a description for this owner # optional

  # Slack
  x-cortex-slack:
    channels:
    - id: ABCDEF123
      notificationsEnabled: true
      description: This is a description for this Slack channel
    - name: team-engineering
      notificationsEnabled: true
      description: A description for this Slack channel.

  # Snyk
  x-cortex-snyk:
    projects:
      - organizationId:<ORGANIZATION_ID>
        projectId: <PROJECT_ID>
        source: CODE

  # SonarQube
  x-cortex-static-analysis:
    sonarqube:
      project: <PROJECT_KEY> # projectKey in SonarQube
      alias: sonarqube-alias

  # Splunk Observability Cloud (SignalFX)
  x-cortex-slos:
    signalfx:
      - query: <FULL_SFX_QUERY>  # Ex. sf_metric:"jvm.memory.max" AND area:"nonheap"
        rollup: <ROLLUP>
        target: <TARGET>
        lookback: <LOOKBACK>
        operation: <OPERATION>
  
  # Splunk On-Call (VictorOps)
  x-cortex-oncall:
    victorops:
      type: SCHEDULE
      id: <SCHEDULE_ID>
       
  # Sumo Logic
  x-cortex-slos:
    sumologic:
      - id: 000000000001234
      - id: 000000000006789
      
  # Veracode
  x-cortex-static-analysis:
    veracode:
      applicationNames:
        - My Application
        - Second Application
      sandboxes:
        - applicationName: My Application
          sandboxName: My Sandbox
        - applicationName: Second Application
          sandboxName: Second Sandbox
          
  # Wiz
  x-cortex-wiz:
    projects:
      - projectId: 01234567-e65f-4b7b-a8b1-5b642894ec37
      
  # Workday
  x-cortex-owners:
    - type: group
      name: workday-team-tag
      provider: CORTEX
      description: This is a description for this owner.
      
  # xMatters
  x-cortex-oncall:
    xmatters:
      id: engineering_group
      type: SERVICE

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/yaml.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.