Explore the new Cortex UI redesign in our overview video:

Accelerate the path to engineering excellence

Cortex Internal Developer Portal makes it easy to ensure ownership, enforce standards, and unlock developer self-service, in weeks — not years.

An entity is an object that represents a software construct. A defined collection of entities is known as a catalog. All entities are represented in YAML, can pull in data from integrations, and can be Scorecarded.

Each entity has its own page that centralizes data related to it, allowing you to quickly access the information you're looking for. Learn more in the Entity details page documentation.

Entity types

You can create your own entity types or use one of the default entity types.

Default entity types

By default, Cortex supports the following entity types:

• Services: The default type and the core of your catalog, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module. Learn more in Add services.

• Domains: An entity that allows you to group your services, resources, and other domains into hierarchical, logical units. Learn more in Add domains.

• Teams: An entity to store all of your team data. Learn more in Add teams.

• Cortex also supports pulling in resources directly from AWS, Azure Resources, and Google Cloud as their corresponding types out of the box.

Custom entity types

In addition, you can create custom entity types to fit your organization's needs. Learn more in Add custom entity types.

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.

Adding metadata to the entity descriptor

Any additional metadata you want to add to your descriptor belongs in the info section. Throughout the docs, you'll see snippets that start with x-cortex-* – make sure to add this to the info section.

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

Managing entities

Editing in the UI or via GitOps

By default, your account is configured to edit entities through the UI. We recommend starting with the UI editor, which includes a built-in YAML editor, then switching over to GitOps when ready for a wider rollout.

If you want to use GitOps to manage your entity YAML files, you can change this setting:

1. In Cortex, navigate to Settings > GitOps.

2. Scroll down to the "Options by entity type" tile.

3. To only allow editing of entities via GitOps, toggle off the setting next to Enable UI editing for new entity types.

4. To only allow creation of entities via GitOps, toggle off the setting next to Enable UI importing for new entities.

When using GitOps, you can define any number of entities in any repository.

• Domain definitions should live in the .cortex/domains directory in your repository.

• Team definitions should live in the .cortex/teams directory in your repository.

You may store all of your entity definitions in a single repository or you can store the YAML in the repository of the corresponding service.

See the single repository example below:

.
└── .cortex
    ├── catalog
    │   ├── database.yml
    │   ├── s3-bucket.yml
    │   ├── auth-service.yml
    │   └── billing-service.yml
    ├── domains
    │   ├── billing-domain.yml
    │   └── health-domain.yml
    ├── teams
    │   ├── eng-team.yml
    │   └── sre-team.yml

Read more in Using GitOps for Cortex.

Unique identifiers for entities

Entity tag

The entity tag - the value of x-cortex-tag in an entity's YAML file - is a unique identifier that's used throughout Cortex. For example, the entity tag is used to declare dependencies on other entities or look up information using the Cortex Slack Bot.

The entity tag must be globally unique across all entities. It is possible to customize the entity tag.

Cortex ID

A Cortex ID (CID) is a unique, immutable entity ID that can be used outside of Cortex for historical tracking and reporting. It can be used in the API, in CQL queries, in-app, and you can use it with the Cortex Slack Bot. The ID is automatically generated by Cortex and it is 18 characters in length.

In Cortex, the CID for an entity appears in the URL for an entity and at the top of an entity page:

The CID does not appear in an entity's YAML file, as it cannot be modified.

Adding entities to catalogs

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.

For the default catalogs, the entity type criteria is set by default:

• The Services catalog contains service entity types

• The Domains catalog contains domain entity types

• The Teams catalog contains team entity types

• The Infrastructure catalog contains any entities that are not the types service, domain, or team.

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

Managing all entities across catalogs

The All entities page lists all entities that have been imported into Cortex, across all types. This page will open to the Mine tab when a user owns any entities; otherwise, it will default to the All entities tab.

Once you’ve imported entities, you’ll be able to see the entity’s name and tag. In the beginning, you may have just a few dozen entities, but eventually you may have hundreds, if not thousands, of entities across all catalogs.

Search across and filter all entities

There are several ways to search and filter your entities list:

• To find specific entities, use the search bar in the upper right corner of the entities list and type to search.

• Click Name to select whether you want to sort by name or identifier, and whether to sort ascending or descending.

• Click Display to choose whether to show archived entities in the list, and select which columns to display alongside entities. Learn more about the performance indicator columns below.

• Click Filter to narrow down your list by AWS account ID or region, domain, entity type, group, team, or user.

Key performance indicators listed for all entities

Click Display to select whether to display the following key performance indicators as columns alongside entities:

• Incidents: Displays how many active incidents are associated with a given entity. This information is pulled from FireHydrant, PagerDuty, and Rootly.

• Health: When you click into this column in an entity's row, you can view more information on:

  • Monitors: Shows how entities are performing against monitors you’ve created in your APM. When an entity is passing all monitors, this cell will display All OK; otherwise, it will display Failing, Warning, or No Data, along with how many monitors the entity is not hitting. This information is pulled from Datadog.

  • Error rate: Shows the percentage of transactions that result in a failure during a pre-specified window. This information is pulled from New Relic.

If you have not set up an integration needed to populate a column, that column will not appear on the "All entities" page or on specific catalogs. If an integration is established, but the data and/or configuration for an entity do not exist, the cell will display “None.”

View entity types

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.

Understanding the entity types

To learn more about adding each type of entity, see their documentation pages:

• Add services

• Add domains

• Add teams

• Add custom entity types

A catalog is a defined selection of entities. You can use catalogs to track and store information about all of the components that make up your infrastructure. This includes everything from services and domains to AWS S3 buckets and RDS, Google Cloud resources, or Azure Resources.

While entities are defined by YAML files, catalogs themselves are not defined by a YAML file and must be created in the Cortex UI. Think of catalogs as a folder containing a collection of entities, with each entity defined by its own YAML file. An entity can belong to multiple catalogs, so you can also think of a catalog as a filter that defines which entity types to group together.

In the example screen shot below, the Services page contains a list of all entities that belong to the Service catalog:

Default catalogs

By default, Cortex comes with four built-in catalogs:

• Services contains all service entities.

• Infrastructure contains all entities representing your infrastructure assets.

  • Cortex pulls in resources directly from AWS, Azure Resources, or Google Cloud, as their corresponding types out of the box. These resources are automatically added to the Infrastructure catalog.

• Domains contains all domain entities and displays them in a hierarchical view.

• Teams contains all team entities and displays them in a hierarchical view alongside a leaderboard based on Scorecards.

You can choose to rename these catalogs to fit your own taxonomy, but note that the custom names of these default catalogs will not override the references to their default names throughout the app. Instead, you could choose to create additional custom catalogs.

Custom catalogs

To customize your Cortex instance to your organization's needs, you can also define custom catalogs in Cortex to represent your infrastructure. See Create custom catalogs below.

View catalogs

Click Catalogs from the main nav to view your list of catalogs. You must have the View catalogs permission.

The "All entities" page

You can view and manage all entities in your Cortex account under Catalogs > All Entities. You can organize entities into catalogs to make it easier to find and manage them.

On that page you can also create entity types, which determine the types entities you’ll import into Cortex.

Cortex comes with built-in entity types to get you started quickly. These entity types do not have a definition schema, and instead fetch details on demand from the original source. You can also create your own entity types.

To view all entity types, go to Catalogs > All Entities then click the Entity types tab.

Manage all catalogs

On the All catalogs page, you’ll find all pre-defined and custom catalogs in Cortex.

This page will reflect the same list of catalogs you find in the Catalogs dropdown menu in the main nav.

Just like "All entities", "All catalogs" includes a search bar and a sort function, as well as a toggle for displaying or hiding Drafts.

From this page, you can create new catalogs and edit existing ones.

Create custom catalogs

You can create catalogs in the Cortex UI. For each catalog, you set the criteria that determines which entities belong to that catalog. In addition, you can define custom entity types to categorize the entities that live in your catalogs.

Because catalogs are not defined by a YAML file, it is not possible to create them via a GitOps workflow.

To create, edit, and delete catalogs, you must have the Edit catalogs permission.

To create a new catalog:

1. At the top of the "All catalogs" page, click Create catalog.

2. Configure the "Create catalog" form:

   • Name: Enter a name for the catalog.

   • Description: Optionally, enter a description of the catalog.

   • Display icon: an icon to appear alongside the catalog throughout the app.

   • URL: Enter a unique URL slug.

     • By default, the URL slug will be generated based on the catalog’s name, but you can use the URL field to create a custom slug.

   • Add entity types: In this section, you will define the entities that are included in your catalog. All entities that match the criteria defined in this section will be automatically included in the catalog. To create a catalog, you need to add at least one entity type. Catalogs can include a combination of any entity types, or can include just one type.

     • Selection type: Choose whether to include or exclude the entity types you select.

     • Entity types: Select from the entity types you've created.

     • Include or Exclude groups: Choose groups to include or exclude.

     • CQL expression: Optionally, enter a specific CQL expression to fine-tune your catalog based on specific criteria.

   • Draft: Choose whether to save the catalog as a draft or publish it. Only admins and managers have the ability to view drafts.

3. Click Save catalog.

Once the catalog is created, you’ll find it under Catalogs > All catalogs, automatically populated with all entities that apply based on the entity types you've created.

Edit catalogs

To edit a catalog:

1. In Cortex, go to Catalogs > All catalogs. Click into the catalog you want to edit, then click Edit catalog at the top of the page.

   • This will bring you back to the catalog creation page, with all the details from your last save.

2. Make any changes necessary to the catalog.

3. At the bottom of the page, click Save catalog.

Track catalog changes

You can use the audit log to track changes made to any of your catalogs. Catalog updates will be listed as CATALOG in the Type column, and the updated catalog will be listed under the Entity column.

The Action column will indicate whether a catalog was created, deleted, or updated.

Adding entities to catalogs

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.

For the default catalogs, the entity type criteria is set by default:

• The Services catalog contains service entity types

• The Domains catalog contains domain entity types

• The Teams catalog contains team entity types

• The Infrastructure catalog contains any entities that are not the types service, domain, or team.

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

Configure catalog display

You must have the Configure appearance settings permission to configure the catalog display.

By default, catalogs will appear in alphabetical order, but you can manually adjust the order that the catalogs appear in the main nav.

Navigate to Settings > Workspace > Main sidebar to drag and drop catalogs into your preferred order:

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

View teams

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 hierarchy, whereas those under "Mine" will be listed individually.

View the teams leaderboard

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

View an individual team's page

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:

  • On-call information.

  • Linked Slack channels.

  • Where the selected team belongs within the broader hierarchy.

  • How the team is performing across Scorecards. By default, this will show the level that the team’s entities have reached in each Scorecard.

    • On the right, enable the toggle next to Aggregate children scores to include child entities in the Scorecard overview.

  • A list of recent events associated with this team, such as alerts from PagerDuty.

• The Members tab includes a list of all team members, as well as their contact information. You can also add tags for each user to signify each member’s role on the team. 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.

• The Dependencies tab shows any incoming or outgoing dependencies associated with this team.

Ownership

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 Ownership documentation.

Creating a team

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 GitOps

• Via the API

Understanding hierarchies

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 Teams catalog, 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.

Create a team

See the tabs below for instructions on each method.

openapi: 3.0.1
info:
  title: Payments Team
  description: This is my cool team.
  x-cortex-tag: payments-team
  x-cortex-type: team

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: OKTA

openapi: 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: product-manager@cortex.io
        notificationsEnabled: true
        roles: 
          - tag: product-manager
      - name: Engineering Manager
        email: engineering-manager@cortex.io
        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-2

openapi: 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-2

openapi: 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: product-manager@cortex.io
        notificationsEnabled: true
      - name: Engineering Manager
        email: engineering-manager@cortex.io
        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: SCHEDULE

Edit teams

It is possible to edit entities after creating them:

1. Navigate to the entity's page.

2. In the upper right corner, click Configure entity.

3. Make any desired changes.

   • Note: The only field you cannot edit is the identifier.

4. At the bottom of the screen, click Save changes.

Adding team member roles

You can manually create a team member role:

1. In Cortex, navigate to Settings > Entities > Teams.

2. Click Add role.

3. In the "Add role" modal, configure the role:

   • Role name: Enter the role's name.

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

4. Click Save.

Apply role to team members

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:

1. In Cortex, navigate to Catalogs > Teams.

2. Click into a team.

3. In the upper right corner, click Configure entity.

4. Click Members.

5. Next to a team member, click the edit icon.

6. In the side panel, add a new team role.

7. Click Update.

Adjusting team settings

Under Settings > Entities > Teams, there are several settings relating to teams:

Enable identity providers

In this section, you can select which identity providers will be used to sync team and team memberships into Cortex.

When importing teams, you will see the option to import from the enabled IdPs listed here.

Auto import teams

When enabled, any discovered teams and team relationships from Workday are automatically imported.

In order for teams to be imported, Workday needs to be enabled under the Enabled identity providers section on this settings page. The Workday report must include the managerEmail field in order for team relationships to be auto imported.

Team ownership entity editing

When enabled, entities can only be edited by specific members of the team that own them. Read more about this feature in Team ownership entity editing.

Give edit access to all team members

When enabled, all team members will be granted edit access. You will not be able to turn off edit access for individual members in your teams configuration when this is enabled.

Team member roles tab

Sync team roles from identity providers

When enabled, Cortex will automatically assign roles to team members based on your enabled identity providers. Leave this option disabled to assign team roles manually.

Add roles

This process is described above, under Adding team member roles.

The entity details page

Each entity has its own page that centralizes data related to the entity, allowing developers to reduce context switching.

While viewing entities in a catalog, or from the Catalogs > All entities page, click an entity name to open that entity's details page.

When you first open an entity, see an overview of relevant information. If there are any active incidents, you will see them at the top of the page, in addition to recent events, on-call, owners, Slack or Microsoft Teams channels, groups, repository, language, and related domains.

If data is not available for a field on the entity page, it will not appear in the overview. For example, if you do not have the Slack integration configured, then the "Slack channels" field will not be displayed.

Entity details sidebar

In the sidebar, click into each category for more information:

Entity overview categories

• API explorer: Pulls from API documentation added to your entity.

• Events: Recent events such as deploys and other integration events.

• Links & docs: Documentation links you have added to the entity, along with documentation pulled from the related repository.

• On-call & incidents: On-call information from Opsgenie, PagerDuty, Splunk On-Call (formerly VictorOps), and xMatters, and incidents pulled from incident.io, PagerDuty, FireHydrant, and Rootly.

• Owners: See the teams who own the entity, the related Slack or Microsoft Teams channels, and a list of team members.

  • Learn more about how to define entity owners in Defining ownership.

• Entity YAML: View the entity YAML that defines this entity.

Cortex features for this entity

• Scorecards: A list of any Scorecards that are in progress where this entity is being scored. In additional, see the average score, median score, and a graph showing the entity's scores over time.

• Initiatives: A list of all active Initiatives for this entity, including the Scorecard's current level and the due date of the Initiative.

• Workflows: A list of Workflows that include this entity. If any Workflows are pending approval and you were designated as an approver when the Workflow was created, you will see the pending approval at the top of this page. This page also includes a list of recently run Workflows and the ability to run any related Workflows.

Connections for this entity

Under the "Connections" header, integration data for the entity is contextually grouped. When you configure integrations, data will be pulled in to the following sections on the entity details page:

• CI/CD: Pulls from deploys API, Azure DevOps, Bitbucket, Buildkite, CircleCI, GitHub, and GitLab.

• Code & security: Pulls from Checkmarx, Codecov, GitHub, GitLab, Mend, Snyk, SonarQube, Veracode, and Wiz.

• Custom data & metrics: Pulls from custom data and Eng Intelligence custom metrics.

• Dashboard: Pulls from charts configured in the entity's YAML file for Datadog, Grafana, and New Relic.

• Error tracking: Pulls from BugSnag, Rollbar, and Sentry.

• Environments: Pulls from AWS and Kubernetes.

• Issue tracking: Pulls from Azure DevOps, ClickUp, GitHub, GitLab, and Jira.

• Monitoring: Pulls from Coralogix, Datadog, Dynatrace, Google Observability Cloud, Lightstep, New Relic, Prometheus, Splunk Observability Cloud (formerly SignalFX), and Sumo Logic.

• Packages: Pulls from the packages API and any packages automatically discovered from your configured git repositories.

• Repository: Pulls from Azure DevOps, Bitbucket, GitHub, and GitLab.

• Integration settings: This page lists the integrations that are enabled and connected for this entity.

Plugins for this entity

Under the "Plugins" header, see any plugins in your workspace that are relevant to this entity.

More information on entities

Learn more about entities in Manging entities.

Need additional guidance?

To ensure a smooth and successful implementation, most of our customers partner with Cortex Professional Services (PS) for expert guidance and hands-on assistance. If you've already purchased a PS engagement, your dedicated team will be reaching out soon to kick things off.

If you haven’t engaged with PS yet, don’t worry—you can still take advantage of our expertise! Reach out to learn how we can support your implementation and adoption journey so you get the most out of Cortex.

Getting started in Cortex

Step 1: Log in to your workspace

You can access your Cortex workspace using the workspace ID provided to you by your Cortex team. Or, if you are deploying Cortex on-premises, the Cortex team will provide you with access to an installer.

SSO setup

Your initial login will be configured to use Google for Single Sign-On (SSO).

Add users

After accessing your account, you can add users to your Cortex workspace.

We recommend having at least two users with the Admin role configured to ensure redundancy of access.

Step 2: Configure integrations

We recommend configuring at least one integration from each of the following categories:

• • Configuring an on-call provider allows you to map services and other entities to the proper on-call rotations and manage alerts.

• • Configuring a communication provider allows you to receive timely notifications and collaborate seamlessly with team members.

• • Connecting your teams and team members in Cortex allows you to efficiently track ownership of entities.

Step 3: Import your first entities

After you’ve configured some basic integrations, you can start importing your entities. Connecting your entities to Cortex allows you to easily track ownership and create Scorecards to enforce standards and track progress on related projects.

Step 3.1: Define entities

Before importing entities, consider your data modeling approach.

• Identify the key entities that you want to represent in your Cortex catalogs.

Step 3.2: Import entities

1. Navigate to Catalogs > All entities.

2. Click Import entities.

3. Follow the on-screen prompts to import the entities that Cortex discovered from your integrations.

As you integrate additional tools with Cortex, it can also become possible to streamline work during an incident, efficiently track issues, monitor your code for vulnerabilities, and more. See the documentation for a full list of available integrations.

Step 3.3: Import teams and team members

Cortex supports connecting teams from the following integrations:

Step 4: Create an onboarding Scorecard

When you first start using Cortex, we recommend creating an onboarding Scorecard to ensure that your entities are configured with the basics.

To get started:

1. From the main nav, click Scorecards.

2. Click Create Scorecard.

3. Cortex offers templates to help you get started with common use cases. Click the Onboarding Scorecard.

4. Review the default integrations, levels, and rules that are included in the template. You’ll get a chance to edit these on the next page. Click Continue.

5. Configure your Scorecard, making any modifications necessary.

   • For in-depth instructions on creating Scorecards, see Creating and editing Scorecards.

6. When you are finished, click Save Scorecard.

Step 5: Explore additional resources

Congratulations - you are on the path to achieving engineering excellence with Cortex!

Now that you’ve completed your first steps, we recommend exploring the following topics:

• • Reach out to your Customer Success Manager for more information on enabling this feature.

• • Reach out to your Customer Success Manager for more information on enabling this feature.

Services are a default entity type in Cortex, used for entities such as microservices, libraries, components, etc – essentially any codebase-like module.

View services

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.

Configure the view of your service list

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

Creating services

You can create services:

• By importing them from a connected integration

• Manually in the Cortex UI

Edit services

It is possible to edit entities after creating them:

1. Navigate to the entity's page.

2. In the upper right corner, click Configure entity.

3. Make any desired changes.

   • Note: The only field you cannot edit is the identifier.

4. At the bottom of the screen, click Save changes.

Incoming dependencies are inferred based the outgoing dependency definitions.

Visualize dependencies in the relationship graph

Automated dependency notifications

When a dependency deprecates its API or makes backwards incompatible changes, Cortex surfaces these issues via these methods:

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

Discovery

Cortex can automatically discover dependencies from your integrations:

How to define dependencies

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.

Sync dependencies

Cortex syncs AWS dependencies every day at 8:00 a.m. UTC. All other dependencies sync at 12:00 a.m. UTC.

If you need to sync dependencies manually:

1. Navigate to Tools > Relationship graphs.

• Tagging

  • Use groups to segment entities.

  • For example, you could segment by tiers (tier-0 to indicate high priority), type (backend, frontend, library, API), or language (Python, Java).

• Filtering throughout Cortex

  • For example, you may want a Scorecard to only apply to Python services or a catalog that only shows tier-0 services.

• Reporting

  • You could aggregate Scorecard scores by a specific group, such as a tier.

  • For example, viewing a Production Readiness Scorecard broken down by tier.

While viewing an entity, its groups are listed at the top of the page:

Click the group name to view a list of all other entities that are tagged with this group.

How to define groups

You can define groups via an entity's YAML, directly in the Cortex UI, or via the API.

Note the following considerations:

• If a group has been set in the entity descriptor YAML, an API call will not overwrite the existing value.

• Groups created via the API will not appear in the entity descriptor YAML.

• Groups created via the API cannot be removed via the Cortex UI.

FAQ and troubleshooting

To determine whether or not to use groups or custom data, consider whether your use case would be considered "tagging" with a definite enum of values (backend vs frontend), or more freeform metadata availability-zones: [east, west].

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.

View entity types

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.

Create custom entity types

You can create custom entity types:

• Manually in the Cortex UI

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.

Creating custom entities

1. In the main nav of Cortex, click Catalogs > All entities.

2. At the top of the Services page, click +Import entities.

4. Configure the form:

   • Type: Select your custom entity type.

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

   • Links: Add links to external documentation, such as runbooks, docs, logs, or custom categories.

   • On-call: Configure on-call information.

   • Repository: Select the repository associated with this entity.

5. When you are finished, click Confirm import at the bottom of the page.

JSON schema for custom entity types

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.

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.

Edit custom entities

It is possible to edit entities after creating them:

1. Navigate to the entity's page.

2. In the upper right corner, click Configure entity.

3. Make any desired changes.

   • Note: The only field you cannot edit is the identifier.

4. At the bottom of the screen, click Save changes.

Add custom entities to catalogs

Using custom entity types or custom data

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:

A schema is ideal for enforcing static properties across all entities, while custom data allows users to augment and update attributes.

Cortex is your source of truth to external docs. Instead of digging through wikis and other resources, you can aggregate docs on the relevant entities in Cortex in the following ways:

View links on an entity

Links appear on an entity details page in the Links & docs section:

Add links to an entity

On entities, you can add links to docs, runbooks, tech specs, dashboards, and more.

Git-driven markdown docs

Cortex automatically embeds markdown files from the docs folder of your repo or from the root directory. If Cortex detects relevant files, these docs show up under the Links & docs page in an entity's sidebar.

Documentation types

OpenAPI docs

Embed specs from a git repository

If you have specs checked into your git repository, you can embed it by adding it as a relative URL with type openapi. For example:

Relative links in another repo

In addition to providing the ability to link to specs within the service repo, Cortex also allows for links that reference other git repositories that aren't necessarily associated with your entity but still within your organization.

Adding OpenAPI via the Cortex API

The request body is the following, in JSON format. See API Docs for authentication details.

AsyncAPI docs

If you have specs checked into your Git repository, you can embed it by adding it as a relative URL with type async_api. For example:

Embedded dashboards

• The type field is an optional enum of three types: datadog, grafana, or newrelic.

• The url field is the src value for the iframe embed generated by your dashboard tool.

  • You must use your tool's embed URL for individual charts.

Embed content from other sources

It is possible to display content from a source other than Datadog, Grafana, or New Relic. To do this, do not specify an option for the type field. The URL you add must be publicly accessible or provide cross-platform authentication for Cortex to view and display the iframe. For example, if the content is accessible via VPN, then you should be able to view it in Cortex while on the VPN.

Accessing docs links via Slack

• /slack links <tag-or-id> to list all documentation links for an entity

• /slack links [type] <tag-or-id> to list specific types of documentation links for an entity

For example:

• To list all documentation links for an entity with ID en29f044598b112345, you could run the following command in Slack: /cortex links en29f044598b112345

• To list the OpenAPI specs for an entity with tag plugin-extension, you could run the following command in Slack: /cortex links openapi plugin-extension

Ownership is a core use case of Cortex, as many organizations seek to establish clear ownership of services, data, and other entities. Entities should be owned within Cortex to ensure appropriate action can be driven using Scorecards and Initiatives.

Ownership can be defined by accepting Cortex's automated recommendations for ownership, pulled in from third-party integrations, or defined manually in the Cortex UI.

Where to view entity owners

When viewing an entity, the owners appear in the metadata bar at the top of the page:

Click into the team name to view the team's entity page, including a list of members and a list of entities owned by that team.

Define owners for entities

You can define owners based on:

• A team

  • We recommend setting up teams as owners. If you link a group in your YAML file from a different platform (such as Okta), the members of the team will be automatically updated in Cortex if anyone leaves your organization and is removed from your integrated identity provider.

• A user email address

Owners can be defined:

• By accepting Cortex's automated recommendations for owners, based on repository activity

• Automatically if Cortex detects that an entity is owned by a team that does not yet exist in Cortex

  • If an entity's YAML references a team, but that team doesn't have a corresponding entry within Cortex, Cortex will automatically create a team. The team will include a label that says Automatically created by Cortex.

• Directly in the Cortex UI

Automatic discovery for AWS

You can pull in all resources from AWS, and Cortex syncs those owners automatically based on their tags in AWS, allowing you to easily keep the resource owners up to date.

Viewing entity ownership

View your owned entities

View a team's owned entities

You can filter the entity list by owner:

2. In the upper right corner, click Filter.

View entities owned by all teams within a hierachy

Teams can exist within hierarchies. You can view a list of all entities that are owned by the parent team and all children teams in the hierarchy:

1. Navigate to the parent team's page in Cortex.

2. Click the Entities tab.

3. Click Display, then enable the toggle next to Inherited Children.
4. Click Done.

The list will now display all entities owned by the parent and its children teams. Note that this setting does not persist when you navigate away from the page.

Ownership settings in Cortex

Custom data extends the out-of-the-box metadata that Cortex provides via integrations, enhancing your use of catalogs and augmenting details available for your entities. This data can also be used to write CQL queries and Scorecard rules.

Custom data can be defined manually in the entity descriptor, added to entities programmatically via a REST API, or sent through a webhook.

Defining custom data

There are a few ways you can add custom data to an entity: the entity descriptor, a POST REST endpoint, or a simple webhook.

Adding custom data via entity descriptor is optimal for low-volume, human-maintained data because it requires updating the entity's YAML when the data changes.

Using a REST API is a better option for data that comes from an automated process, like a CI/CD pipeline.

Editing the entity descriptor

The simplest way to describe information in the YAML is to define an object.

x-cortex-custom-metadata:
  key-example: value-example
  arbitrary-custom-data: hippocampus
  regions-of-brain:
    value: 3
    description: cerebrum, cerebellum, brainstem
  cognition: true

Custom data can be of any type, including scalars (strings, numbers, booleans), objects, and lists.

When you add custom data to an entity's YAML, you'll see the key and value pairs on an entity's Custom data page.

Custom data added via entity descriptor will display with a YAML tag.

Adding descriptions

You can add a description to data by explicitly defining it along with the key and value pairs. While key and value pairs can be defined with any terms when a description is not added, value: must explicitly be defined when a description is included.

x-cortex-custom-metadata:
  regions-of-brain:
    value: 3
    description: cerebrum, cerebellum, brainstem
  brain-hemispheres:
    value: 2
    description: The brain has a left and a right hemisphere.

Note: While the description field is always optional, it is technically "required" to add a description to custom data.

Adding custom data via the Cortex API

You can pipe custom data directly into Cortex by POSTing to /api/v1/catalog/{tag}/custom-data where {tag}is the x-cortex-tag for a given entity.

The request body requires the following in JSON format:

See the API docs for authentication details.

If a key has already been set through the entity descriptor, an API call will NOT overwrite the existing value. Instead, it will simply return the existing value.

To explicitly overwrite values set in the YAML file, use the force=true flag as a query parameter.

Custom data added via API will display with a API tag.

Bulk upload entity keys

You can use the bulk upload endpoint to upload multiple keys for one or more entities.

PUT data in the following format to /api/v1/catalog/custom-data:

{
  "values": {
    "<entity-tag>": [
      {
        "key":"example-key",
        "value":"example value",
        "description":"A description of these data."
      }
    ],
    "<another-entity-tag>": [
      {
        "key":"example",
        "value":{
          "my-data":"my-value",
          "complex": "data",
          "v": 0
        }
      }
    ]
  }
}

You can include multiple key and value objects for each tag. The object conforms to the same shape as the single upload API.

Adding custom data via a webhook

You can use custom data webhooks to create unique URLs that you can use to directly POST arbitrary JSON payloads without auth or an explicit entity tag in the URL if you do not have obvious access to the entity tag or the ability to add authentication headers.

With this method, you can tell Cortex how to process the payload and map it to an entity. For example, the payload may include a data.tag field that corresponds to the entity tag.

Creating a webhook URL

1. Go to Custom integrations settings in Cortex.

2. Create a custom integration for the webhook:

• Name: A human-readable name for the webhook.

• Entity tag JQ: The JQ expression that Cortex will use to extract the entity tag from the payload (e.g. .data.entityTag). **If the tag Cortex extracts from the payload is not identical to the entity tag in Cortex, the endpoint will throw a 400.

• Key: The unique key that will be used in CQL queries with the syntax integration(key). Data will be stored under the key for entities, just like when adding data via entity descriptor or REST API.

1. Save the integration and copy the provided webhook URL.

2. cURL any JSON your heart desires to this URL!

The data can be used exactly the same way as custom data defined through the entity descriptor or the API.

Custom data added via webhook will display with an INTEGRATION tag.

Changing the mappings for entities

If the webhook payload does not contain a value that maps to the exact entity tag you can tell Cortex alternative mappings to look up when processing payloads.

x-cortex-custom-integration-mappings:
  - left-brain
  - right-brain

When processing a payload, Cortex takes the output of the Entity tag JQ field in step 2 above and searches for an entity with that value as a tag. If no such entity exists, Cortex checks whether an entity has registered the value as an alternative mapping; if so, the payload is attached to that entity.

Data source hierarchy

Cortex applies a data source hierarchy to determine how to handle a case where the same key is defined from multiple sources.

• The entity descriptor is the source of truth. If a key is defined there, the API or webhooks cannot override the key.

• The API and webhook approaches are at the same level and can override each other.

You can override keys defined in the YAML by adding a force=true parameter when using an API, but when the entity descriptor is eventually re-processed, the data provided via the API will be overwritten.

Use cases

Cataloging

Catalogs contain a lot of useful metadata about entities, including ownership and data from integrations. However, you may have your own custom fields that you want to include that would make exploring the catalog easier.

These can include things like:

• Which AWS zones is this deployed in?

• What databases does the entity consume?

• When was the last successful CI run?

Custom data can then be queried against by using the Query builder, explored with CQL reports, or viewed on an entity's details page.

Scorecards

Cortex makes it easy to write Scorecard rules based on custom data that exists in your catalogs. When adding a rule, you can select Custom data from Choose an integration in the form editor and follow the flow. Cortex will automatically supply variables based on the custom data you've defined.

Cortex supports integrations across essential use cases for engineering excellence, including alert management, error and issue tracking, git, ownership, security, and more.

See the Integrations page on the Cortex web site to filter available integrations by use case.

Integration rate limiting

Cortex has built a distributed self-throttling system to ensure that certain functionality, such as CQL evaluations or background syncs to pull data from integrations, are not going over the rate limit thresholds for specific vendors. It handles different rate limit thresholds for different APIs within the same integration, which is common for git APIs such as Bitbucket.

The system is designed to proactively throttle before hitting a 429 from the vendor, and it works regardless of how many evaluators are trying to access that integration. Note that this system does not track other requests with the same token or undocumented limits set by vendors.

In Cortex, use the relationship graph to better understand:

• Dependencies

  • Visualize how entities relate to one another
• Domains

  • See a hierarchical diagram of your software architecture
• Teams

  • View your company's team structure

View the relationship graph

You can access the relationship graph in different ways:

• From the main nav: Navigate to Tools > Relationship graphs. By default, the page displays all entities with dependencies and how they relate to one another.

• From an entity details page:

Filter the relationship graph

Select a relationship type

At the top of the page, choose which relationships you want to view: Dependencies, domains, or teams.

Filter the graph

You can apply filters to narrow the scope of the graph:

1. Click Filters at the top of the page.

2. Apply filters for the following options:

   • Sources

   • Groups

   • Entity types

   • Degrees from selected node

The page will automatically apply your selected filters and reload the visualization.

Select a display option

At the top of the graph, click Display options to select:

• A Scorecard to filter the graph by

• Whether to hide team nodes without children

• Whether to hide archived entities

View more details on an entity

In the graph, click an entity to open a modal with the ability to:

• Filter by this node

• Go directly to its entity details page

• View a list of its child entities or dependencies

Adjust appearance settings

You must have the Configure settings permission.

Under Settings > Relationship graph, you can select whether to display dependencies, domains, or teams by default when you first open the relationship graph.

Terraform is an infrastructure-as-code tool that lets you provision, manage, and update infrastructure. Terraform can help you manage databases, s3 buckets, clusters, and every other component that comprises your infra.

Terraform’s ability to manage resources comes from providers, which are plugins that enable interaction with cloud providers, SaaS providers, and other APIs. Providers allow you to define as code what a resource looks like.

The instructions on this page apply to Terraform Cloud, the web-based interface for Terraform.

How to manage Terraform infrastructure in Cortex

Before getting started

• Provision a new instance

  • Terraform will automatically provide you with a starter workspace when you begin — our example workspace is named "tfc-guide-example".

• Update the instance name in the Terraform variables.tf file.

  • All Terraform modules come with a file called variables.tf. As part of the Terraform script, we can enter variables for a given set, like region or instance type. In the example screen shot below, the variable name is "My Other Great Instance".

• Note: Terraform modules also come with a main.tf file, which contains instructions and information about the action. In our example, the main.tf file describes the instance that we’re going to create through Terraform.

Step 1: Confirm your instance name update in Terraform

In Terraform Cloud, navigate to the Run page. Verify that the changes you made to the instance name in variables.tf have applied.

In Terraform, there are two primary commands: plan and apply.

• The plan command creates a plan and preview of the changes that will be made to your infrastructure. During the plan stage, Terraform assesses the main.tf file with variables and compares it against the state. If there are differences, Terraform prompts you to approve and apply the change.

• When you navigate to the run that was triggered by updating variables.tf, you can see that the plan was automatically conducted. In this case, the plan was to create an instance with the name provided earlier. Verify that the run displays a "Plan finished" message.

In AWS, you can confirm that the instance exists and that the Terraform action was successful:

Step 2: Add the Terraform template in Cortex

Cortex not only integrates with Terraform, but can enhance your use of it. Once the integration is set up, you’ll use a Scaffolder step in a Workflow to interact with Terraform.

You must have the Configure Scaffolder templates permission.

1. Create a Cookiecutter JSON file that is equivalent to your Terraform module.
2. Register your template in Cortex.

3. After you have added the template to Cortex, you can create a Workflow that includes a Scaffolder block using the template.

4. Run the Workflow. When you run it, Cortex will automatically open a pull request against the selected repository.

To verify that the process worked, open Terraform Cloud and navigate to Runs.

Any runs that originate from Cortex will have "[Cortex Scaffolder]" at the start of their name. When we navigate into one of these runs, we can see that it was planned and finished but not yet applied, and we can see how many changes were proposed.

Execute a run via a Workflow

Terraform Cloud also has an API that can be used to make updates without following the pull request workflow. You can use a Workflow in Cortex to execute a run through the API. If a run is set to automatically apply, then Cortex will handle the rest of the process.

1. Create a Workflow in Cortex.

2. Add a user input block.

   1. Define inputs for Instance name, Region, and Instance type.

3. Add an HTTP request block. Configure the following fields:

   1. HTTP method: Select POST.

   2. URL: Enter the URL for the Terraform API you want to call.

   3. Headers: Add Authorization: Bearer {{token}} and Content-type: application/(name).

   4. Payload: Build the payload by referencing the outputs of the "User input" block, e.g., {{actions.input.outputs.instance-name}}

4. Save the Workflow. After saving, click Run at the top of the Workflow to run it.

When the Workflow is run in Cortex, it will override data in the variables.tf file with information that was entered in the fields.

In Terraform Cloud, you can verify that the action was successful and the run was queued. Runs triggered by actions are named "Triggered via API."

Once the run has been applied, you can also verify it in AWS. In the example screen shot below, the instance name has been changed.

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.

Viewing domains

You can view all domains under Catalogs > Domains.

Display in hierarchy

To display domains in a hierarchy:

1. Click Display at the top of the domains list.

3. Click Done.

You can also view the hierarchy for a given domain on its entity details page. 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.

View in relationship graph

At the top of the domain, click View in domains tree to visualize your domain hierarchy in the relationship graph.

Creating domains and a hierarchy

You can create domains:

• By importing them from a connected integration

• Manually in the Cortex UI

• Via the entity descriptor YAML through GitOps

• Via the API

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.

openapi: 3.0.1
info:
  title: Payments
  description: This is my cool domain.
  x-cortex-tag: payments-domain
  x-cortex-type: domain