LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • Visualize dependencies in the relationship graph
  • Automated dependency notifications
  • Discovery
  • How to define dependencies
  • Sync dependencies
  • Troubleshooting and FAQ

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex
  2. Managing Entities
  3. Adding entities

Defining dependencies

Last updated 16 hours ago

Was this helpful?

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 the outgoing dependency definitions.

Visualize dependencies in the relationship graph

In Cortex, you can visualize dependencies using the relationship graph at Tools > Relationship graphs. See the for more information.

Automated dependency notifications

This feature is available in beta. Please reach out to your Cortex Customer Success Manager for access.

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 .

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

Define dependencies in the Cortex UI

  1. Navigate to the entity where you need to define a dependency.

  2. In the upper right corner of the entity details page, click Configure entity.

  3. Click the Hierarchy tab.

  4. In the dropdown menu, choose an entity.

  5. Optionally, select an endpoint.

  6. 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:

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

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.

info:
  x-cortex-dependency:
    - tag: braavos
      method: GET
      path: /2.0/users/
      description: ensure user has payment information configured
      metadata:
        tags:
          - billing
          - identity
        prod: true
Field
Description
Optional?

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

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

Define dependencies via the API

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 field. If no endpoint is referenced it is assumed that the caller depends on all endpoints of the callee.

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.

Field
Description
Optional?

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

Required if method is present

description

A description of the dependency.

Yes

metadata

JSON metadata tags for the relationship. Supports arbitrary objects.

Yes

{
  "callerTag": "my-service",
  "calleeTag": "braavos",
  "path": "/2.0/users/",
  "method": "GET",
  "description": "ensure user has payment information configured",
  "metadata": {
    "tags": ["billing", "identity"],
    "prod": true
  }
}

Create a dependency

POST /api/v1/catalog//dependencies/?method=&path=

{
  "description": "ensure user has payment information configured",
  "metadata": 
}

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.

{
  "description": "ensure user has payment information configured",
  "metadata": 
}

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

{
  "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": 
      }
    ]
  }
}

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.

Troubleshooting and FAQ

What if I have multiple dependency sources?

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

In the Dependencies block, click +Add entity.

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.

In the UI, the paths will appear in the Endpoint dropdown:

See the for authentication details.

In the upper right corner of the page, click the menu icon, then click Sync dependencies.

API docs
Relationship graph documentation
Settings > Breaking API changes
AWS
Azure Resources
Datadog
Dynatrace
Google Cloud
New Relic
discover dependencies
notify owners
relationship graph
"Set an endpoint for a dependency"