In this section, learn how to add each of the built-in entity types and dependencies, and how to create a custom entity type and add custom entities:
Want to learn more? Check out the Cortex Academy course on , available to all Cortex customers and POVs.
Domains offer a way to group entities into hierarchical units. You can group by product area, functionality, systems, business units, or something unique to your organization. With this feature, you can cluster entities into a single, hierarchical domain that can include both parents and children.
You can define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace. This hierarchy is available to view in the Domains catalog, on a domain entity's details page, and in the relationship graph. The domain hierarchy can also be used to configure ownership inheritance, helping you keep track of ownership in case of personnel changes at your organization.
You can view all domains under Catalogs > Domains.
To display domains in a hierarchy:
Click Display at the top of the domains list.
Enable to toggle next to Display hierarchy.
Click Done.
You can also view the hierarchy for a given domain on its . If the domain has parents or children, those will appear on the Relationships page.
In the entity's side bar, click Relationships, then click the Hierachy tab.
At the top of the domain, click View in domains tree to visualize your domain hierarchy in the .
You can create domains:
By importing them from a connected integration
Manually in the Cortex UI
Via the entity descriptor YAML through
Via the
For simplicity, we recommend adding the highest-level domain first and then selecting it as the parent for subsequent domains. However, you can add parents and children to any domain at any point.
Importing domains
You can import domains directly from third-party integrations:
In Cortex, navigate to Catalogs > All entities, then click Import entities.
Choose Import discovered entities.
Select the integration to import from.
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Note: The only field you cannot edit is the identifier.
Under , you can enable automatic import of domains and domain relationships from .
On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.
If you have a large volume of entites, click Filter in the upper right corner of the results list to select and apply entity type filters.
At the bottom of the page, click Next step.
Edit the details for the entity:
Type: Select Domain.
Entity name: Enter a human readable name.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the entity to help others understand its purpose.
Groups: Optionally select your entity.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes. You may see owners that Cortex . You can accept or reject the recommendations.
When adding an owner, you can also configure one of the following inheritance options:
Append: Select this option to add your entity as an additional owner to all of its child entities.
Parents and Children: Define parent and children domains. This is where you configure the hierarchy for your domain. These can be visualized in the .
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
When you are finished, click Confirm import at the bottom of the page.
If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.
Click Confirm import.
Manually creating domains
In the main nav of Cortex, click Catalogs > Domains.
At the top of the Domains page, click +Import entities.
Choose Create entities manually.
Configure the form:
Type: Select Domain.
Entity name: Enter a human readable name.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
When you are finished, click Confirm import at the bottom of the page.
The hierarchy of entities in Cortex is based on that hierarchy being defined in the entity's YAML file; Cortex does not set hierarchies based on a YAML file's location in your repository.
Domain entity descriptor
If your entity is a domain, you must specify x-cortex-type as domain:
Domain hierarchies
These can be defined in two ways:
From the parent entity YAML
Define children entities using the x-cortex-children tag in the parent entity YAML.
From the child entity YAML
Define parent entities using the x-cortex-parents tag in the child entity YAML.
While defining these relationships top-down (on the parent entity) or bottom-up (on the child entity) will both result in a hierarchy, you may choose one or the other depending on your workflow. For example, if you are frequently making changes to a group of children domains, it may be more efficient to have the children defined on the parent YAML.
Domain children
Define a list of other entities as children for a domain, allowing you to represent a hierarchy of how your entities are modeled across your workspace using the x-cortex-children tag.
Domain parents
Define another entity as the parent for a domain, allowing you to represent a hierachy of how your entities are modeled across your workspace using the x-cortex-parents tag.
Note: Parents must be of type domain.
Ownership inheritance
A common use case for domains is defining ownership for the subtree of entities. Instead of defining ownership individually for every entity in your catalog, you can define ownership at the domain level and have that pass down to all of its children.
The inheritance type for each owner can be one of APPEND, FALLBACK, or NONE. If not set, inheritance is defaulted to NONE.
APPEND: This owner is appended to the list of owners for all child entities.
FALLBACK: In the case where a child has no valid owners, including fallbacks, this fallback will be assigned as the owner. Note that this only applies to a child entity down the hierarchy; it is not the fallback for the parent domain itself.
NONE: This owner owns the domain, but not necessarily any of its children (no inheritance).
Example cortex.yaml
Note: the YAML definition for a domain entity can take file names other than cortex.yaml or cortex.yml; see the .
Creating domains via the API
You can create, update, and delete domains using the .
At the bottom of the screen, click Save changes.
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domainNone: Select this option if you do not want to configure inheritance. The owner will own the domain you are creating, but will not be configured as an appended or a fallback owner.
Groups: Optionally select groups to segment your entity.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
When adding an owner, you can also configure one of the following inheritance options:
Append: Select this option to add your entity as an additional owner to all of its child entities.
Fallback: Select this option to add your entity as an owner to child entities if the child entity has no other valid owners.
None: Select this option if you do not want to configure inheritance. The owner will own the domain you are creating, but will not be configured as an appended or a fallback owner.
Parents and Children: Define parent and children domains. This is where you configure the hierarchy for your domain. These can be visualized in the relationship graph.
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-children:
- tag: child-domain-1
- tag: child-service-1
- tag: child-resource-1openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-parents:
- tag: parent-domain-1
- tag: parent-domain-2openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-owners:
- type: GROUP
name: cortexapps/engineering
provider: GITHUB
inheritance: APPENDopenapi: 3.0.1
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:
- 23456Teams serve as both an entity representing your organization in Cortex and as owners for different entities in the catalogs. Teams offers a centralized place for the most important information about each group, making it easier for everyone to find what they need.
Teams can be assessed via Scorecards, interact with integrations, and leverage custom data. They can also be configured in a hierarchy.
To view your teams, navigate to Catalogs > Teams.
When you open the Teams catalog page, you'll see Mine and All, which denote teams you belong to and all teams at your organization, respectively. The teams that appear under "All" will automatically display as a , whereas those under "Mine" will be listed individually.
On the right side of the Teams catalog page, see the Scorecard Leaderboard, which highlights the ten best-performing teams within your organization.
The leaderboard is calculated from the average of scores for all entities owned by a team. Change in rank is based on the team's score 7 days ago. You can use the dropdown to select a different Scorecard, allowing you to view the leaderboard based on specific Scorecards.
The leaderboard gamifies entity quality and encourages team members to achieve goals. This creates a culture of accountability, where everyone has visibility into how they're performing.
Each team has its own details page, where you can view key details about the team. Click a team from the Teams catalog page to view its details.
At the top of a team details page, you’ll find on-call information, Slack channels, and parent and children teams.
Additional information appears in tabs on the team's details page:
The Overview tab includes:
Vulnerabilities and issues from linked integrations.
How the team is performing across Scorecards. By default, this will show the level that the team’s entities have reached in each Scorecard.
Learn more about the sidebar links in the documentation.
Teams not only allow you to collect vital information in a single place, but are also crucial for ownership. Rather than assign an entity to individual team members, you can assign ownership to an entire team. This makes it easy to assign multiple team members to an entity, and it ensures that when a team’s composition changes, ownership is updated accordingly.
Read more in the .
You can create teams:
By importing them from a connected integration (e.g., Workday, GitHub)
Manually in the Cortex UI
Via the entity descriptor YAML through
Via the
You can configure teams to reflect the actual hierarchy at your organization while creating or importing teams in Cortex. A team can be defined as the parent of one or more teams while also being the child of another team.
When you access the , individual teams and parent teams are displayed by default. Parent teams have an arrow next to their name, indicating that you can expand to view children teams.
In the above example, My Company is a parent team with 7 child teams nested under it.
See the tabs below for instructions on each method.
Importing a team from an integration
If you have an existing source of truth for your teams and team members, we recommend importing teams. By integrating with your identity provider at this stage, Cortex will automatically sync team pages with your source of truth so you don't have to update information in more than one place when people join or leave teams.
Each integration syncs teams daily.
You can only import entities from integrations that have already been configured.
Supported integrations
Teams from the following integrations can be imported:
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Note: The only field you cannot edit is the identifier.
You can manually create a team member role:
In Cortex, navigate to .
Click Add role.
In the "Add role" modal, configure the role:
Role name: Enter the role's name.
You can apply a role only to manually-created team members. Team members who were imported from an identity integration will retain the role that was imported.
To apply a role:
In Cortex, navigate to Catalogs > Teams.
Click into a team.
In the upper right corner, click Configure entity.
Click Members.
Under , there are several settings relating to teams. You can select which identity providers to use to sync teams and team memberships, configure automatic import from Workday, configure entity editing access, and sync or create roles. Learn more in .
Services are a default entity type in Cortex, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module.
To view services, click Catalogs > Services from the main nav.
When you open the Services page, you'll see tabs labeled Mine and All, which denote services you own and all services visible to you in your Cortex workspace.
A list of recent events associated with this team, such as alerts from PagerDuty.
The Dependencies tab shows any incoming or outgoing dependencies associated with this team.
The Team members tab includes a list of all team members and their roles. When available, Cortex will also pull in profile photos from your Git provider.
The Entities tab shows a list of all entities that the team owns.
Before following the import process, you must configure table mappings.
For the Workday integration, you can enable automatic import of discovered teams.
Importing teams
After configuring an integration that includes teams, follow these steps to import teams:
In Cortex, navigate to Catalogs > All entities, then click Import entities.
Choose Import discovered entities.
Select the integration to import from.
On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.
If you have a large volume of entites, click Filter in the upper right corner of the results list to select and apply entity type filters.
At the bottom of the page, click Next step.
Edit the details for the entity:
Type: Select Team.
Name: Enter a human readable name for your team.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the
If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.
Click Confirm import.
Manually creating teams
If you don’t have an identity provider with updated team information, you can create a team manually within Cortex. Because teams are important for effective ownership, it's recommended that you create teams in Cortex even if you don't have a single source of truth for team information.
In Cortex, navigate to Catalogs > Teams, then click Import teams.
Choose Create entities manually.
Configure the form:
Configure the team details:
Type: Select Team.
Name: Enter a human readable name for your team.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the
Click Confirm import.
Once you've created a team, you can view it on the Teams page within the hierarchy. If you haven't added parents or children, you can disable View as hierarchy to see the list of all teams.
Adding Cortex-managed teams
You can manually create teams in Cortex and define them in the entity descriptor.
You can also define teams as owners via entity descriptors. See the Ownership documentation for more information.
Team entity descriptor
If your entity is a team, you must specify x-cortex-type as team.
The x-cortex-team tag has two main sections: groups and members.
Adding groups to the team entity descriptor
Use groups to link your team entity with a team on a different platform that you have integrated with Cortex. You can only link one group to a team entity.
For example, you can specify:
Under groups, when you specify okta-security-team, your team will contain all the members from your okta-security-team.
Now, if you specify the okta-security-team in your on any of your other entities, they will automatically recognize example-team as a team that owns their entity.
Adding team members to the team entity descriptor
members can be used to add individual members to your team when you have a use case for a team entity that doesn't correspond exactly to a team on one of your integrations. Members support roles. For example, the following entity includes a member who has the product-manager role and a member who has both the engineering-manager role and manager role:
After specifying the YAML example above, your team now will contain Product Manager and Engineering Manager. If [email protected] or [email protected] were to correspond with the email of an actual account in Cortex, they would start seeing example-team being displayed as a team that they're a part of (i.e., it would start showing up in their Mine tab in catalogs that contain teams).
must be defined for your workspace in your , under the "Teams" tab.
Team children
You can define a list of other teams as children, allowing you to represent a hierarchy of how your teams are modeled across your workspace, using the x-cortex-children tag.
This hierarchy is available to look at in the Teams catalog page.
The hierarchy of entities in Cortex is based on that hierarchy being defined in the entity's YAML file; Cortex does not set hierarchies based on a YAML file's location in your repository.
Team parents
Team children allow you to define the team relationship from the top-down, but in some cases it may be easier to define the team hierarchy from the bottom-up. For these cases, x-cortex-parents can be added to any entity's YAML to define its parents.
Example cortex.yaml
Note: the YAML definition for a team entity can take file names other than cortex.yaml or cortex.yml; see the .
Creating teams via the API
You can create, update, and delete teams using the .
At the bottom of the screen, click Save changes.
Tag: The tag - a unique identifier for the role - automatically populates based on the role name.
Role description: Enter a description of the role.
Enable notifications by default: If notifications are enabled, members with this role will receive relevant updates on Scorecards, Initiatives, and more.
Click Save.
Next to a team member, click the edit icon.
In the side panel, add a new team role.
Click Update.
At the top of your services list, you can choose how the list is displayed:
Name: Click Name, then choose whether to sort by name or identifier (Cortex tag), and whether the sort order should be ascending or descending.
Display: Click Display, then choose whether to display hierarchies, whether to show archived, and which columns to display.
Filter: To narrow the scope of your list, click Filter then select criteria you'd like to filter by.
You can create services:
By importing them from a connected integration
Manually in the Cortex UI
Via the entity descriptor YAML through GitOps
Via the
You can import services directly from third-party integrations:
In Cortex, navigate to Catalogs > All entities, then click Import entities.
Choose Import discovered entities.
Select the integration to import from.
On the following page, after the integration sync is complete, a list of entities from the integration are displayed. Check the boxes next to any entities you want to import.
If you have a large volume of entites, click Filter in the upper right corner of the results list to select and apply entity type filters.
At the bottom of the page, click Next step.
Edit the details for the entity:
Type: Select Service.
Entity name: Enter a human readable name.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag
If you selected more than one entity: After the first entity is configured, click the name of the next entity on the right to navigate to the detail editor for that entity.
Click Confirm import.
To create a service:
In the main nav of Cortex, click Catalogs > Services.
At the top of the Services page, click +Import entities.
Choose Create entities manually.
Service entity descriptor
A barebones spec file has the OpenAPI version, along with an info section that contains some basic details.
Required fields
The only required fields under info are the title, x-cortex-tag, and x-cortex-type. The description is optional, but we highly recommend adding descriptions to all of your entities.
Example cortex.yaml for a service
You can create, update, and delete services using the .
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Note: The only field you cannot edit is the identifier.
At the bottom of the screen, click Save changes.
openapi: 3.0.1
info:
title: Payments Team
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: teamx-cortex-tagDescription: Enter a description of the team to help others understand its purpose.
Groups: Select groups to segment your entity.
Members: Select members of your team. Team members will be marked as owners of entities and receive notifications about entities owned by the team if notifications are enabled.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Slack channels: Link the team's associated Slack channel. If notifications are configured, the team will receive notifications here.
You must have the Slack integration configured before linking a channel.
Parents and Children: Define parent and children teams. This is where you configure the hierarchy for your entity. These can be visualized in the relationship graph.
On-call: Configure the on-call service associated with this team. When selected, you will see the latest on-call information displayed on the team's details page.
x-cortex-tagDescription: Enter a description of the team to help others understand its purpose.
Groups: Select groups to segment your entity.
Members: Select members of your team. Team members will be marked as owners of entities and receive notifications about entities owned by the team if notifications are enabled.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Slack channels: Link the team's associated Slack channel. If notifications are configured, the team will receive notifications here.
You must have the Slack integration configured before linking a channel.
Parents and Children: Define parent and children teams. This is where you configure the hierarchy for your entity. These can be visualized in the relationship graph.
On-call: Configure the on-call service associated with this team. When selected, you will see the latest on-call information displayed on the team's details page.
Description: Enter a description of the entity to help others understand its purpose.
Groups: Select groups to segment your entity.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
You may see owners that Cortex recommends based on repository activity. You can accept or reject the recommendations.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Parents: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the relationship graph.
Dependencies: Select entities that this entity depends on. These can be visualized in the relationship graph.
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
Type: Select Service.
Entity name: Enter a human readable name.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the entity to help others understand its purpose.
Groups: Select your entity.
Owners: Define ownership for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Parents: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the .
Dependencies: Select entities that this entity depends on. These can be visualized in the .
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
When you are finished, click Confirm import at the bottom of the page.
openapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
groups:
- name: okta-security-team
provider: OKTAopenapi: 3.0.1
info:
title: Example Team
description: My Cool Team
x-cortex-type: team
x-cortex-tag: example-team
x-cortex-team:
members:
- name: Product Manager
email: [email protected]
notificationsEnabled: true
roles:
- tag: product-manager
- name: Engineering Manager
email: [email protected]
notificationsEnabled: true
roles:
- tag: engineering-manager
- tag: manager openapi: 3.0.1
info:
title: Payments
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-children:
- tag: child-team-1
- tag: child-team-2openapi: 3.0.1
info:
title: Payments
description: This is my cool team.
x-cortex-tag: payments-team
x-cortex-type: team
x-cortex-parents:
- tag: parent-team-1
- tag: parent-team-2openapi: 3.0.1
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: [email protected]
notificationsEnabled: true
- name: Engineering Manager
email: [email protected]
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: SCHEDULEopenapi: 3.0.1
info:
title: My Service
description: This is my cool service.
x-cortex-tag: my-service
x-cortex-type: serviceopenapi: 3.0.1
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:
- CSEvery entity you add to your workspace is associated with an entity type. Cortex comes with several built-in entity types, but you can create unlimited custom entity types to extend your catalogs.
There are two distinct parts of this process: Creating the entity type itself (via the UI or API), then creating entities of that custom type (via the UI, GitOps, or API).
Want to learn more? Check out the Cortex Academy course on Catalogs, Entities, and Relationships, available to all Cortex customers and POVs.
To view all entity types, go to Catalogs > All Entities then click the .
A Cortex logo appears next to built-in entity types. When you hover over the logo, you will see a "Powered by Cortex" banner:
The other entity types in the list are custom types.
You can create custom entity types:
Manually in the Cortex UI
Via the
When creating an entity type, keep in mind that these will ultimately dictate how you import specific entities later on. After creating the type itself, you will be able to (via the UI, API, or GitOps).
To create, edit, and delete entity types, your user or API key must have the Edit entity types permission.
Create entity types in the Cortex UI
In Cortex, navigate to Catalogs > All entities.
Click the Entity types tab, then click Create entity type.\
Configure the form:
Entity type definitions require a JSON schema that outlines the attributes that entities should conform to.
Custom entity type definitions are powered by the open-source project.
The JSON schema for a custom entity type ensures consistency and validation when creating entities of that type. The attributes listed under required in the schema must be defined for entities of that type according to the outlined properties.
In the example below, location is required when creating this type of entity, but the schema also includes department as a possible property.
When creating a new entity of the custom type, if the entity type's JSON schema requires certain attributes, you must include the metadata for those attributes on that entity.
Defining a JSON schema enables visibility on an . The schema and the defined properties will appear under the Metadata section on the entity's overview, making it easy for you to identify key specs.
In the example below, the entity "Sally S" displays metadata for the property "location."
After , you can create entities of that custom type:
in the Cortex UI
in the via
via the
To create custom entities, your user or API key must have the Edit entities permission.
Create custom entities in the Cortex UI
Before creating a custom entity in the UI, make sure you have UI-based editing enabled for this entity type in .
In the main nav of Cortex, click Catalogs > All entities.
At the top of the Services page, click +Import entities.
Choose Create entities manually.
It is possible to edit entities after creating them:
Navigate to the entity's page.
In the upper right corner, click Configure entity.
Make any desired changes.
Note: The only field you cannot edit is the identifier.
After an entity is imported or created, it will automatically belong to a catalog based on the entity type criteria set for each catalog. When you , you can set the entity type criteria.
By default, any you create will belong to the Infrastructure catalog. If you do not want the entity type to belong to this catalog, you can add the entity type to a different catalog's definition.
After creating a custom entity type, you can view or edit its schema, view a list of entities of that type, and validate the schema of entities of that type.
You can view a custom entity type's schema and a list of entities of that type.
Navigate to Catalogs > All entities, then click the .
Click into an entity type.
The schema is displayed on the entity type page.
Navigate to Catalogs > All entities, then click the .
Click into an entity type.
In the upper right corner, click Edit.
Make changes to your entity type, then at the bottom of the page, click Save.
Navigate to Catalogs > All entities, then click the .
Click into an entity type.
Click the Schema linter tab.
In the text editor, paste in your entity's JSON schema to verify that it is properly formatted for this entity type.
In some instances, you may want to use custom data instead of a custom entity type. This is recommended if you need more flexibility for these entity types; they may not always require specific metadata.
While a custom entity type's metadata will appear on the overview of an , custom data does not appear there. Instead, it appears in the Custom data sidebar of an entity details page.
It is possible to create an entity type with an empty properties schema:
This entity type will display in the catalogs, but entities of this type won't be validated against certain specs. Such properties can instead be defined using .
A schema is ideal for enforcing static properties across all entities, while custom data allows users to augment and update attributes.
In Cortex, you have the ability to define outgoing dependencies on other entities. Cortex can also automatically for some integrations. Having dependencies defined powers the ability to when a dependency deprecates its API or makes backwards incompatible changes, and the ability to visualize dependencies in a .
Incoming dependencies are inferred based on the outgoing dependency definitions.
In Cortex, you can visualize dependencies using the relationship graph at Tools > Relationship graphs. See the for more information.
Name: Enter a human-readable name that will appear in the catalog for this entity type.
Type: Enter a unique identifier that corresponds to the entity type. This will be used to specify the type defined in the YAML definitions for imported entities.
Description: Optionally, enter a description for the entity type.
Display icon: Select an icon to appear alongside the entity type throughout the app.
Schema: Define a JSON schema that will be used to validate the x-cortex-validation block of a given entity’s YAML.
This can be used to enforce certain attributes about entities, such as a region or version number. Attributes defined in the schema will be required when creating an entity of that type, which can then be validated in Scorecards. Learn more under JSON schema for custom entity types.
In the example screen shot below, we’ve created a custom entity type called Employee — this is what we’ll use to represent individuals at our organization. In the schema section, you can see that each profile is required to include an employee’s location. This means every time you create an entity of type "Employee," you will define the employee's location.\
At the bottom of the page, click Create.
After saving, the entity type will appear in the Entity types tab under Catalogs > All entities, and you are now able to import entities of that type.
If you want entities of the new entity type to automatically belong to a specific catalog, you can configure the catalog's defined entity types while creating a new catalog or you can edit an existing catalog to update the entity types.
Create entity types via the API
You can create, update, and delete entity types using the Cortex API.
Learn more about the JSON schema below.
Configure the form:
Type: Select your custom entity type.
Entity schema: Enter a JSON schema to define your custom entity.
For example, if the entity type's schema requires location and department, your new entity's schema might look like this:\
Click Show example above the schema to view an example of how the entity's schema should be formatted. To use the example as a starting point, click Copy example then paste it into the Entity schema text editor.
See for more information.
Entity name: Enter a human readable name for your entity.
Identifier: This field is auto-populated based on your entity name. It is a unique identifier for your entity. This is also known as the x-cortex-tag.
Description: Enter a description of the entity to help others understand its purpose.
Groups: Select your entity.
Owners: Define for your entity. We recommend selecting team owners to keep your ownership information up-to-date through any future personnel changes.
Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.
Parents: Define parent domains. This is where you configure the hierarchy for your entity. These can be visualized in the .
Dependencies: Select entities that this entity depends on. These can be visualized in the .
On-call: Configure on-call information.
Repository: Select the repository associated with this entity.
When you are finished, click Confirm import at the bottom of the page.
Create custom entities in the entity descriptor
Before creating a custom entity via GitOps, make sure you have UI-based editing disabled for this this entity type in Settings > GitOps.
If your entity is of a custom type, you must specify x-cortex-type and x-cortex-definition.
The x-cortex-definition field is validated against the entity type definition that you created via the UI or API. If your custom entity type does not have specific requirements, entities of that type still need a non-null definition specified, like x-cortex-definition: {}.
Example cortex.yaml
You can create, read, update, and delete entities via the Cortex API.
To delete entities, your API key must have the Delete entities permission.
At the bottom of the screen, click Save changes.
Learn more about the health and incident data columns in Key performance indicators listed for all entities.\
You cannot edit the entity type's unique identifier.
On the right side of the page, click Show example to see an example of how the schema should be formatted.
If you want to use the example as a starting point, click Copy example, then paste it into the text editor.
In the upper right side of the text editor, click Validate Schema.
type
Type of entity and/or required component: array, boolean, integer, null, number, object, or string
Yes
required
Required specs for the entity type
properties
Properties of the required specs (including type)
Yes only if the required field is not null
When a dependency deprecates its API or makes backwards incompatible changes, Cortex surfaces these issues via these methods:
Breaking API changes are listed in your Cortex workspace under Settings > Breaking API changes.
Cortex attempts to automatically make comments on PRs containing breaking OpenAPI changes that have downstream dependencies that Cortex knows about.
If a breaking change is merged to the default branch, Cortex alerts dependency owners via Slack that a breaking change was merged.
Cortex can automatically discover dependencies from your integrations:
You can define dependencies manually via an entity's YAML descriptor, via the Cortex UI (if UI editing is enabled), or via the API.
Your user or API key need the Edit entities permission.
Define dependencies in the Cortex UI
Navigate to the entity where you need to define a dependency.
In the upper right corner of the entity details page, click Configure entity.
Click the Hierarchy tab.
In the Dependencies block, click +Add entity.
In the dropdown menu, choose an entity.
Optionally, select an endpoint.
In order for an endpoint to populate in this dropdown, it must first be defined as a path in the entity's YAML file. See below.
Click Add.
Set an endpoint for a dependency
Before you can select an endpoint from the dropdown when manually defining a dependency, that endpoint must be defined as a path in the entity's YAML file. See the example below:
In the UI, the paths will appear in the Endpoint dropdown:
Define dependencies in the entity descriptor
The x-cortex-dependency field allows you to define a list of outgoing dependencies. A dependency should be directed towards an outgoing service or resource, or more granularly, to a specific endpoint of that entity.
Define dependencies via the API
See the for authentication details.
YAML is the source of truth. If a dependency has already been set through the cortex.yaml, the API will return an error.
Endpoints are optional. A dependency optionally references an endpoint (method and path) of the callee, and this must already be defined in the callee's cortex.yaml within the paths
Cortex syncs AWS dependencies every day at 8:00 a.m. UTC. All other dependencies sync at 12:00 a.m. UTC.
You must have the Enable entity dependency discovery permission to manually sync dependencies.
If you need to sync dependencies manually:
Navigate to Tools > Relationship graphs.
In the upper right corner of the page, click the menu icon, then click Sync dependencies.
When leveraging multiple dependency sources (such as Datadog and a catalog entity's YAML), all the sources will be merged together and deduplicated.
For example, if an entity YAML indicates X->Y and Datadog indicates X->Y and X->Z, we will have two edges presented (X->Y and X->Z).
openapi: 3.0.1
info:
title: Sally S
description: Technical writer
x-cortex-tag: employee-sally
x-cortex-type: org-employees
x-cortex-definition:
location: San Diego
department: Engineering{
"type": "object",
"required": [
"location"
],
"properties": {
"location": {
"type": "string"
},
"department": {
"type": "string"
}
}
}{
"location": "San Diego",
"department": "Engineering"
}x-cortex-type: org-employees
x-cortex-definition:
location: San Diego
department: Engineering{
"type": "object",
"required": []
"properties": {}
}
path
The actual endpoint this dependency refers to
Required if method is present
description
A description of the dependency.
Yes
metadata
JSON metadata tags for the relationship. Supports arbitrary objects.
Yes
For all requests method or path are optional, however if one is present the other must also be present.
When interacting with an existing dependency, the method and path must be specified correctly to identify it.
callerTag
The tag of the caller.
No
calleeTag
The tag the caller depends on.
No
method
HTTP method if depending on a specific endpoint
Required if path is present
path
The actual endpoint (as defined in the OpenAPI file) the caller depends on
Create a dependency
POST /api/v1/catalog//dependencies/?method=&path=
Retrieve a dependency
GET /api/v1/catalog//dependencies/?method=&path=
Update a dependency
PUT /api/v1/catalog//dependencies/?method=&path=
PUT replaces entire object. The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as null.
Delete a dependency
DELETE /api/v1/catalog//dependencies/?method=&path=
Bulk create or update dependencies
PUT /api/v1/catalog/dependencies
:::caution PUT replaces entire object The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as null. :::
tag
The tag of the entity this entity depends on, i.e. the callee. See x-cortex-tag
No
method
HTTP method if depending on a specific endpoint
Required if path is present
openapi: 3.0.1
info:
title: Endpoint Example Service
description: "This is an example"
x-cortex-tag: endpoint-example-service
x-cortex-type: service
paths:
/hello/world:
get:
description: Some description
requestBody:
description: optional
responses:
"200":
description: optional
deprecated: false
/another/path:
put:
deprecated: falseinfo:
x-cortex-dependency:
- tag: braavos
method: GET
path: /2.0/users/
description: ensure user has payment information configured
metadata:
tags:
- billing
- identity
prod: true{
"callerTag": "my-service",
"calleeTag": "braavos",
"path": "/2.0/users/",
"method": "GET",
"description": "ensure user has payment information configured",
"metadata": {
"tags": ["billing", "identity"],
"prod": true
}
}{
"description": "ensure user has payment information configured",
"metadata":
}{
"description": "ensure user has payment information configured",
"metadata":
}{
"values": {
"my-service": [
{
"tag": "braavos",
"path": "/2.0/users/",
"method": "GET",
"description": "ensure user has payment information configured",
"metadata":
}
],
"my-other-service": [
{
"tag": "my-service",
"path": "/1.0/widget/",
"method": "GET",
"description": "get widget",
"metadata":
}
]
}
}Required if method is present
description
A description of the dependency.
Yes
metadata
JSON metadata tags for the relationship. Supports arbitrary objects.
Yes