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
}
}
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
- Terraform
{
"myRelation": {
"title": "My title",
"target": "myTargetBlueprint",
"required": false,
"many": false
}
}
Check out Port's API reference to learn more.
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
- Terraform
{
"myRelation": {
"title": "My title",
"target": "myTargetBlueprint",
"required": false,
"many": true
}
}
Check out Port's API reference to learn more.
resource "port_blueprint" "myBlueprint" {
# ...blueprint properties
# ...user-defined properties
relations {
identifier = "myRelation"
title = "My relation"
target = "myTargetBlueprint"
required = false
many = true
}
}
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.
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
- UI
- Terraform
{
"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.
- Go to the DevPortal Builder page;
- Click the pencil icon on the blueprint that will be the
source
blueprint of the relation:
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