Defining dependencies
In Cortex, you have the ability to define outgoing dependencies on other entities. Cortex can also automatically discover dependencies for some integrations. Having dependencies defined powers the ability to notify owners when a dependency deprecates its API or makes backwards incompatible changes, and the ability to visualize dependencies in a relationship graph.
Incoming dependencies are inferred based on 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 Relationship graph documentation for more information.
Automated dependency notifications
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.
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
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 "Set an endpoint for a dependency" 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:
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: falseIn 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.
info:
x-cortex-dependency:
- tag: braavos
method: GET
path: /2.0/users/
description: ensure user has payment information configured
metadata:
tags:
- billing
- identity
prod: truetag
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
See the API docs 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 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.
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.
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.
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).
Last updated
Was this helpful?