Add custom entity types
Last updated
Last updated
Cortex comes with several built-in entity types, but you can create unlimited custom entity types to extend your catalogs.
Every entity in the catalog is associated with an entity type. Entity type definitions require a type and a JSON schema that outlines the attributes that entities should conform to.
To view all entity types, go to Catalogs > All Entities then click the Entity types tab.
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:
When creating an entity type, keep in mind that these will ultimately dictate how you import specific entities later on.
To create, edit, and delete entity types, your user or API key must have the Edit entity types permission.
In Cortex, navigate to Catalogs > All entities.
Click the Entity types tab, then click Create entity type.
Configure the form:
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 is not required to create an entity type, but will be useful if you want 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.
In the example screen shot, we’ve created a custom entity 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 and their dream vacation. This means every time you create an Employee entity, you’ll define each employee’s location and dream vacation in a schema for that entity.
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 will be 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.
After creating your custom entity type, you can start creating entities of that type:
In the main nav of Cortex, click Catalogs > All entities.
At the top of the Services page, click +Import entities.
Configure the form:
Type: Select your custom entity type.
Schema: Enter a JSON schema to define your custom entity. See JSON schema for custom entity types below 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 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.
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.
When you are finished, click Confirm import at the bottom of the page.
Custom entity type definitions are powered by the open-source JSON Schema 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.
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
Defining a JSON schema also enables visibility on an entity's detail page. The schema and the defined properties will appear under the Entity Metadata section on the Overview page, making it easy for users to identify key specs.
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.
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 create a custom catalog, you can set the entity type criteria.
By default, any custom entity types 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.
In some instances, you may want to use custom data instead of a custom entity type.
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 custom data.
A schema is ideal for enforcing static properties across all entities, while custom data allows users to augment and update attributes.
Choose Create entities manually.
