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.

Metadata in entity descriptor YAML files

The metadata you add to your descriptor belongs in the info section of the YAML file.

Throughout the Cortex docs, you'll see metadata examples that start with x-cortex-* – these belong in the info section of your entity YAMLs.

Note that it is not currently supported to include comments in YAML files.

Required blocks

Every entity YAML requires the following:

title: The entity's name
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, we recommend adding a description, groups, and owners:

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.

Additional basic metadata blocks

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. Under this block you can define members.
- 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.

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 file.

## 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: [email protected]
      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: [email protected]
     notificationsEnabled: true 
   - name: Product Manager
     email: [email protected]
     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>

  # 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

Last updated 9 hours ago

Was this helpful?