> 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/defining-relationship-types/managing-relationships.md).

# Managing relationships

Cortex captures your organization's structure through two complementary concepts: **relationship types** and **relationship connections**.

A **relationship type** defines the rules of a connection: what it means, which entity types can participate, whether it flows in one direction or can form cycles, and whether metadata should inherit across it. Think of it as a template (e.g. "Repository," "Cloud account to resource," or "Service to environment") that describes *how* two kinds of entities relate before any specific entities are linked.

A **relationship connection** is a concrete instance of that template: the actual link between two specific entities. For example, once you've defined a "Repository" relationship type, a connection is what ties your `payments-service` entity to its specific GitHub repository entity.

This separation gives you flexibility and consistency. You define the shape of a relationship once, then apply it across as many entity pairs as needed. Relationships can be hierarchical (acyclical, like an org chart) or graph-like (cyclical, like service dependencies), and they can carry ownership metadata that flows from parent to child.

Together, relationship types and connections give Cortex a way to reflect how your systems actually fit together.

## Creating relationship types

Users with the `Edit Relationships` permission can create a relationship type.

Relationship types must be created via the Cortex UI or the API.

### Creating relationship types via the Cortex UI

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. In the upper-right corner, click **Create**, then click **Create new relationship type**.\
   The **Create new relationship** page is displayed.
4. In the **Details** section, do the following:
   1. Under **Name**, enter a name for the relationship type (required).
   2. The **Identifier** auto-populates based on the relationship type name and is made up of letters, digits, and hyphens.
   3. Under **Description**, enter a description of the relationship to help others understand its purpose.
   4. Toggle on **Create relationship type catalog** to create a catalog for this relationship type.
5. In the **Source entity types** section, do the following:
   1. From the drop-down menu, select an entity type. If no entity type is selected, all entity types are available as sources.
   2. Toggle on **Exclude** to hide all entity types from sources, or leave toggled off to include all.
   3. Optionally, customize the singular and plural wording of the entity types and the cardinality.
6. In the **Destination entity types** section, do the following:
   1. From the drop-down menu, select an entity type. If no entity type is selected, all entity types are available as destinations.
   2. Toggle on **Exclude** to hide all entity types from destinations, or leave toggled off to include all.
   3. Optionally, customize the singular and plural wording of the entity types and the cardinality.
7. In the **Relationship constraints** section, do the following:
   1. Select an architecture:
      1. **Acyclical** - Recommended for hierarchical data such as an org chart or product hierarchy.
      2. **Cyclical** - Recommended for graph-like data such as dependencies.
   2. Under **Definition location**, select a location:
      1. **From destination** - If selected, relationships can only be defined from destination entities.
      2. **From source** - If selected, relationships can only be defined from source entities.
      3. **Either source or destination** - If selected, relationships can be defined by either destination or source entities.
   3. Toggle on **Ownership** to configure inheritance for the relationship type, then select how metadata will be inherited. Learn more in [Ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance.md).
      1. **Fallback**: This option uses the source's data only if the destination does not have anything defined.
      2. **Append**: This option appends the source's data to the destination, even if it already has data defined.
8. Click **Create**.

### Creating relationship types via the API

You can create, update, and delete relationship types using the [Cortex API](https://docs.cortex.io/api/readme/entity-relationship-types).

## Creating relationship connections between entities

After creating a relationship type, connections between entities can be made via the Cortex UI, an entity descriptor, or the API.

### **Creating relationship connections via the UI**

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md).
2. In the upper-right corner, click **Configure entity**.
3. From the left entity sidebar, click **Relationships**.
4. In the **Relationship type** section, select a relationship type to configure from the drop-down menu.
5. Select the entities you want to connect. The available fields depend on the relationship type selected.
6. Click **Save changes**.

### Creating relationship connections via an entity descriptor

Once a relationship type exists, you can define the connection in either the source or destination entity's YAML using the `x-cortex-relationships` tag.

In the example below, a source entity's YAML has a defined relationship type called `app-components` and has destination entities `production-ui` and `backend-app`.

```yaml
  x-cortex-relationships:
  - type: app-components
    destinations:
    - tag: production-ui
    - tag: backend-app
```

Optionally, this can be configured in the YAML of the destination by replacing `source` with `destination` in the YAML above.

The relationship between entities in Cortex is based on the relationship being defined in the entity's YAML file; Cortex does not set hierarchies or relationships based on a YAML file's location in your repository.

### Creating relationship connections via the API

You can create, update, and delete relationships between entities using the [Cortex API](https://docs.cortex.io/api/readme/entity-relationships).

## Editing a relationship type

Users with the `Edit Relationships` permission can edit a relationship type.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Locate the relationship type you want to edit, then click the **pencil icon** next to it.
4. Make any necessary changes.
5. Click **Save**.

## **Configuring tag-based auto-linking for AWS**

You can configure any relationship type to automatically create relationships between AWS resources and other Cortex entities based on matching AWS tag values. This is the recommended way to connect AWS resources to domains, services, or custom entities for Scorecard reporting.

{% hint style="info" %}
The **Auto-creation of relationships** section only appears when at least one AWS-backed entity type is selected as the source and/or destination.
{% endhint %}

**To configure tag-based auto-linking**:

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Locate the relationship type you want to configure, then click the **pencil icon**. You can also [create a new relationship type](#creating-relationship-types-via-the-cortex-ui).
4. Scroll to the **Auto-create relationships from integration tags** section.
5. From the **Provider** drop-down menu, select **AWS**.
6. Configure the **Source tag key** by doing one of the following:
   * Enter the AWS tag key on the source entity (e.g. `cortex-entity-tag`), OR
   * Toggle on **Cortex provided tag** to use Cortex's standardized managed tag key.
7. Configure the **Destination tag key** by doing one of the following:
   * Enter the tag key on the destination entity (e.g. `AWS-tag-parent`), OR
   * Toggle on **Cortex provided tag** to use Cortex's standardized managed tag key.
8. Click **Save** (or **Create** if it's a new relationship type).

{% hint style="info" %}
Once a relationship type is saved with integration-backed auto-creation configured, this setting cannot be changed. To modify it, delete the relationship type and create a new one.
{% endhint %}

Cortex scans entities matching the relationship type's source and destination definitions and creates a relationship wherever tag values match. Newly configured relationships are created asynchronously and may take up to one sync cycle to appear.

**Example: Linking AWS resources to domains**

To roll AWS resources up to a domain for Scorecard reporting:

1. Tag your AWS resources with the domain they belong to (e.g. a `domain` tag with the domain's Cortex tag as the value).
2. Create or open a relationship type with AWS resources as the source and domains as the destination.
3. In the **Auto-creation of relationships** section, set the source tag key to `domain` and the destination tag key to the corresponding identifier on your domain entities.
4. Click **Save**. Cortex creates the relationships automatically.

## Deleting a relationship type

Users with the `Edit Relationships` permission can delete a relationship type.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Select the relationship type you want to delete.
4. Click the **Overflow menu** icon, then click **Delete relationship type**.