Creating custom entities

This article explains how to create a custom entity. For information on creating a custom entity type, see Adding custom entity types.

Prerequisites

1. Users or API keys with the Edit Entities permission can create custom entities.

2. A custom entity type. Once the custom entity type is created, you can begin creating entities of that type.

Creating a custom entity

After creating the custom entity type, you can create entities of that custom type in the Cortex UI, in the entity descriptor YAML via GitOps, or via the Cortex API.

Creating a custom entity manually in the Cortex UI

1. From the main sidebar, expand Catalogs, then select All entities.

2. In the upper-right corner, click Import entities.

3. Select Create entities manually. The Edit details page opens.

4. Configure the following options. The options shown are filtered at runtime based on the entityType (e.g. 'Members' is team-only, 'Dependencies' excludes domains/teams) and whether the required integrations are enabled (e.g. 'Communications' requires Slack, 'On-call' requires Opsgenie/PagerDuty, etc.).

   1. In the Type section:

      1. From the drop-down menu, select your custom entity type (required).

      2. Below 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:

         

         • Optionally, click Show example above the schema to view an example of how the entity's schema should be formatted. The Entity Schema Example window opens. To use the example as a starting point, click Copy example, then paste it into the Entity schema text editor. See JSON schema for custom entity types for more information.

   2. In the Details section:

      1. Under Entity name, enter a name for the entity (required).

      2. The Cortex tag field is auto-populated based on the name of the entity (required). It's a unique identifier for the entity. This is also known as the x-cortex-tag.

      3. Under Description, enter a description of the entity to help others understand its purpose.

      4. From the Groups drop-down menu, select a group or groups to segment the entity.

   3. In the Repository section:

      1. From the Provider drop-down menu, select the repo provider.

      2. From the Alias drop-down menu, select the alias of the connected provider account that has access to the repository.

      3. From the Repository drop-down menu, select the repo associated with the entity. If you don't see it listed, click Refresh repositories to pull in the latest list.

      4. Below Basepath, enter the subdirectory within the repo where the entity's code lives. Leave blank if the entity occupies the entire repo.

   4. In the Owners section, define ownership for the entity. Ownership can be assigned to either teams or individual users. It's recommended to select team owners to keep the ownership information up to date through any future personnel changes. To add a team or teams, click Add in the Teams area. To add an individual user or users, click Add in the Users area.

      • Cortex may recommend owners based on repository activity. You can accept or reject the recommendations.

   5. In the Links section, click Add to add links to external documentation, such as runbooks, docs, logs, or custom categories.

   6. In the Slack channels section, click Add to link a Slack channel to the entity. If enabled, you'll receive notifications about the entity in the selected Slack channel.

   7. In the Parents section, select a parent domain or domains from the drop-down menu. This is where you configure the hierarchy for your entity, which can be visualized in the relationship graph.

   8. In the Dependencies section, click Add entity to select an entity or entities that this entity depends on. These can be visualized in the relationship graph.

5. If you selected more than one entity, click Next entity in the bottom-right corner of the page.

6. Click Confirm import. The entity is imported into Cortex.

Adding a custom entity in YAML via GitOps

Before creating a custom entity via GitOps, be sure UI-based editing is disabled in Cortex. See Managing entities via GitOps.

Custom entity types require both x-cortex-type and x-cortex-definition.

The x-cortex-definition field is validated against the entity type definition created via the UI or API. Even if your custom entity type has no specific requirements, you must still provide a non-null definition, e.g. x-cortex-definition: {}.

Example cortex.yaml

openapi: 3.0.1
info:
  title: Henry Tallman
  description: Product Manager
  x-cortex-tag: employee-henry
  x-cortex-type: org-employees
  x-cortex-definition:
    location: Cleveland
    department: Product

Creating a custom entity via the API

You can create, read, update, and delete entities via the Cortex API.

Users or API keys must have the Delete Entities permission to delete entities.