Defining dependencies

In Cortex, you can define outgoing dependencies on other entities, and for some integrations Cortex can discover them automatically. Defining dependencies lets you notify owners when a dependency deprecates its API or ships a backwards-incompatible change, and lets you visualize dependencies in a relationship graph. Incoming dependencies are inferred automatically from your outgoing definitions.

Automated dependency notifications

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

Cortex can automatically discover dependencies from the following integrations:

• AWS

• Azure Resources

• Datadog

• Dynatrace

• Google Cloud

• New Relic

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

  1. From the main sidebar, click your avatar in the bottom-left corner.

  2. Click Settings.

  3. From the Settings menu, locate the Logging section, then click Breaking API changes.

• When a PR introduces breaking OpenAPI changes that affect downstream dependencies Cortex knows about, Cortex attempts to comment on it automatically.

• If a breaking change is merged to the default branch, Cortex alerts dependency owners via Slack that a breaking change was merged.

Defining dependencies

Users or API keys with the Edit Entities permission can define dependencies.

Dependencies can be defined in the Cortex UI, manually via an entity's YAML descriptor, or from the API.

Defining dependencies via the Cortex UI

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

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

3. From the left entity sidebar, click Dependencies.

   
4. Click Add entity.

5. In the Dependency sidebar, do the following:

   1. From the Entity drop-down menu, select an entity (required).

   2. From the Endpoints drop-down menu, select an endpoint. For an endpoint to populate in this dropdown, it must first be defined as a path in the entity's YAML file. See Setting an endpoint for a dependency for more information.

   3. From the Description drop-down menu, enter a description for the dependency.

6. Click Add.

Setting an endpoint for a dependency

When manually defining a dependency, you can only select endpoints from the dropdown that are already defined as paths in the target entity's YAML file. For example, to make the GET /v1/payments and POST /v1/refunds endpoints selectable, the payments service would need the following in its OpenAPI spec:

openapi: 3.0.1
info:
  title: Payments Service
  description: Handles payment processing and refunds
  x-cortex-tag: payments-service
  x-cortex-type: service
paths:
  /v1/payments:
    get:
      description: List payments
      responses:
        "200":
          description: A list of payments
      deprecated: false
  /v1/refunds:
    post:
      description: Issue a refund
      requestBody:
        description: Refund details
        required: true
      responses:
        "201":
          description: Refund created
      deprecated: false

In the UI, the paths now appear in the Endpoints drop-down menu:

Defining 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	Required?
tag	The tag of the entity this entity depends on, i.e. the callee. See x-cortex-tag
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.
metadata	JSON metadata tags for the relationship. Supports arbitrary objects.

Defining 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 returns 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 and 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	Required?
callerTag	The tag of the caller.
calleeTag	The tag the caller depends on.
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.
metadata	JSON metadata tags for the relationship. Supports arbitrary objects.

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

Creating a dependency

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

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

Retrieving a dependency

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

Updating a dependency

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

PUT replaces the entire object. The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON is interpreted as null.

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

Deleting a dependency

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

Creating or updating dependencies in bulk

PUT /api/v1/catalog/dependencies

PUT replaces the entire object The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON is 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": "payments-service",
        "path": "/1.0/widget/",
        "method": "GET",
        "description": "get widget",
        "metadata": 
      }
    ]
  }
}

Syncing dependencies manually

Users with the Enable Entity Dependency Discovery permission can manually sync dependencies.

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

To sync dependencies manually:

1. From the main sidebar, expand Tools, then click Relationship graphs.

2. In the upper-right corner of the page, click the overflow 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 are merged together and de-duplicated.

For example, if an entity YAML indicates X->Y and Datadog indicates X->Y and X->Z, two edges are presented (X->Y and X->Z).