Dependencies

One of the most powerful features of Cortex is the ability to define outgoing dependencies on other entities. This powers many features, including automated notifications to owners when a dependency deprecates its API or makes backwards incompatible changes. Incoming dependencies are inferred based the outgoing dependency definitions.

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/{username}
      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

Defining dependencies in the Cortex UI

To 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. In the entity's left sidebar, click Dependencies.
4. Click Add dependencies next to services or resources.
5. In the form, select an entity to add as a dependency.
6. 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 the example below.
7. Click Save dependency.

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
  /this/also/works:
    put:
      deprecated: false

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

Discovery

Cortex can automatically discover dependencies from your integrations.

• Amazon Web Services
• Azure Resources
• Datadog
• Dynatrace
• Google Cloud
• New Relic

caution

We sync dependencies every day at midnight UTC.

If you need to sync dependencies manually, you can do so by clicking the "Sync dependencies" button in the Dependency Graph page.

AWS discovery

By default, Cortex will try to automatically discover dependencies between your services and AWS resources with a matching tag (see Discovery for details). However, you can instead specify a list of AWS tag key and value pairs to explicitly define the dependencies yourself. If you'd like to explicitly define these AWS dependencies, the x-cortex-dependency field should be a map, not a list. A service will have dependencies on all resources in Cortex for which the corresponding AWS resource has at least one AWS tag key value pair matching the pairs in the specified list. For example, the service below will have dependencies on any AWS resource with (key = aws:cloudformation:my-key-1, value = arn:aws:cloudformation:my-region:my-value-1) or tag (key = aws:cloudformation:my-key-2, value = arn:aws:cloudformation:my-region:my-value-2).

x-cortex-dependency:
  cortex:
    - tag: braavos
      method: GET
      path: /2.0/users/{username}
      description: ensure user has payment information configured
      metadata:
        tags:
          - billing
          - identity
        prod: true
    - tag: charlie
      method: GET
      path: /2.0/users/
   aws:
      tags:
        - key: "aws:cloudformation:my-key-1"
          value: "arn:aws:cloudformation:my-region:my-value-1"
        - key: "aws:cloudformation:my-key-2"
          value: "arn:aws:cloudformation:my-region:my-value-2"

Google Cloud discovery

By default, Cortex will try to automatically discover dependencies between your entities and Google Cloud resources with a matching label. By default the label key that will be matched is service, however you can customize this key value in the Google Cloud Settings page. If you'd like to explicitly define these Google Cloud dependencies, the x-cortex-dependency field should be a map, defined as follows:

x-cortex-dependency:
   gcp:
     labels:
       - key: my-key-1
         value: my-value-1
       - key: my-key-2
         value: my-value-2

API

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

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/{username}",
  "method": "GET",
  "description": "ensure user has payment information configured",
  "metadata": {
    "tags": ["billing", "identity"],
    "prod": true
  }
}

Create a dependency

POST /api/v1/catalog/{caller-tag}/dependencies/{callee-tag}?method={method}&path={path}

{
  "description": "ensure user has payment information configured",
  "metadata": {
    "tags": ["billing", "identity"],
    "prod": true
  }
}

Retrieve a dependency

GET /api/v1/catalog/{caller-tag}/dependencies/{callee-tag}?method={method}&path={path}

Update a dependency

PUT /api/v1/catalog/{caller-tag}/dependencies/{callee-tag}?method={method}&path={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": {
    "tags": ["billing", "identity"],
    "prod": false
  }
}

Delete a dependency

DELETE /api/v1/catalog/{caller-tag}/dependencies/{callee-tag}?method={method}&path={path}

Bulk create or update dependencies

PUT /api/v1/catalog/dependencies

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/{username}",
        "method": "GET",
        "description": "ensure user has payment information configured",
        "metadata": {
          "tags": ["billing", "identity"],
          "prod": true
        }
      }
    ],
    "my-other-service": [
      {
        "tag": "my-service",
        "path": "/1.0/widget/{id}",
        "method": "GET",
        "description": "get widget",
        "metadata": {
          "tags": ["widget"],
          "prod": true
        }
      }
    ]
  }
}