Relate Blueprints

Relations define connections between blueprints results into dependency reflection of assets in your software catalog.

What is a relation?

Relations enable us to make connections between blueprints, consequently connecting the entities based on these blueprints. That provides logical context to the software catalog.

💡 Common relations

Relations can be used to represent the logical connections between assets in your software catalog, for example:

• The packages that a microservice uses;
• The run history of a CI job;
• The Kubernetes clusters that exist in a cloud account;
• etc.

In this live demo example, we can see the DevPortal Builder page with all of the blueprints and their relations. 🎬

Relation schema structure

The basic structure of a relation object:

{
  "myRelation": {
    "title": "My title",
    "target": "My target blueprint",
    "required": true,
    "many": false
  }
}

info

A relation exists under the relations key in the Blueprint JSON schema

Structure table

Field	Description	Notes
identifier	Unique identifier	The identifier is used for API calls, programmatic access and distinguishing between different relations. The identifier is the key of the relation schema object, in the schema structure above, the identifier is myRelation
title	Relation name that will be shown in the UI	Human-readable name for the relation
target	Target blueprint identifier	The target blueprint has to exist when defining the relation
required	Boolean flag to define whether the target must be provided when creating a new entity of the blueprint
many	Boolean flag to define whether multiple target entities can be mapped to the Relation	For more information refer to many relation

Types of relations

👤 Single

A single type relation is used to map a single target entity to the source.

💡 Common Single Relations

• Map a Deployment to the Running Service that it deployed;
• Map a package version to the package;
• Map a K8s cluster to the cloud account it is provisioned in;
• etc.

In this live demo example, we can see a specific package version and its related core packages. 🎬

Single Relation Structure

A single type relation is distinguished by the many: false configuration:

API

{
  "myRelation": {
    "title": "My title",
    "target": "myTargetBlueprint",
    "required": false,
    "many": false
  }
}

Check out Port's API reference to learn more.

Terraform

resource "port_blueprint" "myBlueprint" {
  # ...blueprint properties
  # ...user-defined properties
  relations {
    identifier = "myRelation"
    title      = "My relation"
    target     = "myTargetBlueprint"
    required   = false
    many       = false
  }
}

👥 Many

A many type relation is used to map multiple target entities to the source.

💡 Common Many Relations

• Map dependencies between services;
• Map the packages used by a service;
• Map the cloud resources used by a service;
• Map the services deployed in a developer environment;
• etc.

In this live demo example, we can see a specific developer environment and the running services it uses. 🎬

Many Relation Structure

A many type relation is distinguished by the many: true configuration:

API

{
  "myRelation": {
    "title": "My title",
    "target": "myTargetBlueprint",
    "required": false,
    "many": true
  }
}

Check out Port's API reference to learn more.

Terraform

resource "port_blueprint" "myBlueprint" {
  # ...blueprint properties
  # ...user-defined properties
  relations {
    identifier = "myRelation"
    title      = "My relation"
    target     = "myTargetBlueprint"
    required   = false
    many       = true
  }
}

danger

At the moment, Port's Terraform provider does not support reporting entities from a blueprint that has a many relation configured.

If you plan on using Port's Terraform provider to report entities, please do not define blueprints with many relations in your Terraform definitions.

note

A Relation can't be configured with both many and required set to true

Configure relations in Port

Relations are part of the structure of a blueprint.

API

{
  "identifier": "myIdentifier",
  "title": "My title",
  "description": "My description",
  "icon": "My icon",
  "calculationProperties": {},
  "schema": {
    "properties": {},
    "required": []
  },
  "relations": {
    "myRelation": {
      "title": "My title",
      "target": "My target blueprint",
      "required": true,
      "many": false
    }
  }
}

Check out Port's API reference to learn more.

UI

1. Go to the DevPortal Builder page;
2. Click the pencil icon on the blueprint that will be the source blueprint of the relation:

Terraform

resource "port_blueprint" "myBlueprint" {
  # ...blueprint properties
  # ...user-defined properties
  relations = {
    "myRelation" = {
      title    = "My title"
      target   = "My target blueprint"
      required = true
      many     = false
    }
  }
}

Once added to the blueprint definition, you can apply the blueprint to Port