Dependencies
One of the most powerful features of Cortex is the ability to define outgoing dependencies on other services and resources. 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.
Catalog 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
Cortex automatically discovers dependencies between your services and AWS resources with a matching tag (see Discovery for details), but you can also specify a list of AWS tag key and value pairs to explicitly define dependencies. 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 tag (key = my-key-1
, value = my-value-1
) or tag (key = my-key-2
, value = 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: my-key-1
value: my-value-1
- key: my-key-2
value: my-value-2
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 |
Discovery
Cortex can automatically discover dependencies from your integrations. Dependency discovery occurs on a fixed schedule, but admins can manually trigger dependency discovery by clicking the sync button on the Dependency Graph page, next to 'Sources'. Supported providers:
API
See API Docs for authentication details.
If a dependency has already been set through the cortex.yaml
, the API will return an error.
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}
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
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
}
}
]
}
}