> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies.md). # 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](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md). Incoming dependencies are inferred automatically from your outgoing definitions. ## Automated dependency notifications {% hint style="info" %} This feature is available in beta. Please reach out to your Cortex Customer Success Manager for access. {% endhint %} Cortex can automatically discover dependencies from the following integrations: * [AWS](/ingesting-data-into-cortex/integrations/aws.md) * [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources.md) * [Datadog](/ingesting-data-into-cortex/integrations/datadog.md) * [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace.md) * [Google Cloud](/ingesting-data-into-cortex/integrations/google.md) * [New Relic](/ingesting-data-into-cortex/integrations/newrelic.md) 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](/ingesting-data-into-cortex/entities-overview/entities/details.md), click **Configure entity**. 3. From the left entity sidebar, click **Dependencies**.

The 'Dependencies' tab in the left entity sidebar.

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](#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: ```yaml 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. ```yaml 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](/api/readme/dependencies.md) for authentication details. {% hint style="warning" %} YAML is the source of truth. If a dependency has already been set through the `cortex.yaml`, the API returns an error. {% endhint %} 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.

```json { "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=` ```json { "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=` {% hint style="warning" %} `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`. {% endhint %} ```json { "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` {% hint style="warning" %} `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`. {% endhint %} ```json { "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. {% hint style="info" %} Cortex automatically syncs AWS dependencies every day at 8:00 a.m. UTC. All other dependencies sync at 12:00 a.m. UTC. {% endhint %} **To sync dependencies manually**: 1. From the main sidebar, expand **Tools**, then select **Relationship graphs**. 2. In the upper-right corner of the page, click the **overflow menu icon**, then click **Sync dependencies**.

The overflow menu icon in the upper-right corner of the page.

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