Terraform

Our integration with Terraform allows you to combine the state of your infrastructure with the entities representing them in Port.

By using Port's Terraform provider you make it easy to integrate Port with your existing IaC definitions, every resource provisioned by Terraform can also be reported to the software catalog using the same .tf definition file.

port terraform provider

You can view the official registry page for our Terraform provider here

💡 Terraform provider common use cases

Our Terraform provider makes it easy to fill the software catalog with data directly from your IaC definitions, for example:

• Report cloud accounts;
• Report databases;
• Report lambdas and managed Kubernetes services (EKS, AKS, GKE, etc.);
• etc.

Installation

Prerequisites

To install and use Port's Terraform provider, you will need to install the Terraform CLI

To install the Terraform provider, create a .tf file specifying the provider and the required Port credentials:

terraform {
  required_providers {
    port-labs = {
      source  = "port-labs/port-labs"
      version = "~> 0.9.6"
    }
  }
}

provider "port-labs" {
  client_id = "{YOUR CLIENT ID}"     # or set the environment variable PORT_CLIENT_ID
  secret    = "{YOUR CLIENT SECRET}" # or set the environment variable PORT_CLIENT_SECRET
}

Then run the following command to install the provider in your Terraform workspace:

terraform init

Terraform definition structure

Port's Terraform provider supports The following resources to ingest data to the catalog:

port-labs_entity

The port-labs_entity resource defines a basic entity:

resource "port-labs_entity" "myEntity" {
  identifier = "myEntity" # Entity identifier
  title      = "My Entity" # Entity title
  blueprint  = "myBlueprint" # Identifier of the blueprint to create this entity from

  # Entity property values
  properties {
    ...
  }
  ...
  # Entity relations
  ...
}

The following parameters are required:

• blueprint - the identifier of the blueprint to create this entity from;
• title - the title of the entity;
• One or more properties schema definitions.

It is also possible to specify the following parameters as part of the port-labs_entity resource:

• identifier - the identifier of the entity;
  • If an identifier is not provided, an identifier will be autogenerated.
• team - the team that owns the entity;
• teams - an array of teams that own the entity;
• run_id - the run ID of the action that created the entity.

properties schema

The properties schema assigns a specified value to one of the entity's properties.

resource "port-labs_entity" "myEntity" {
  identifier = "myEntity" # Entity identifier
  title      = "My Entity" # Entity title
  blueprint  = "myBlueprint" # Identifier of the blueprint to create this entity from

  properties {
    name  = "myStringProp"
    value = "My string"
  }

  properties {
    name  = "myNumberProp"
    value = 7
  }

  properties {
    name  = "myArrayProp"
    items = [1,2,3]
  }

  # Entity relations
  ...
}

Definition

String

properties {
  name = "myStringProp"
  value = "My string"
}

Number

properties {
  name = "myNumberProp"
  value = 7
}

Boolean

properties {
  name = "myBooleanProp"
  value = true
}

Object

properties {
  name = "myObjectProp"
  value = jsonencode({ "my" : "object" })
}

Array

properties {
  name = "myArrayProp"
  items = [1, 2, 3]
}

URL

properties {
  name = "myUrlProp"
  value = "https://example.com"
}

Email

properties {
  name = "myEmailProp"
  value = "me@example.com"
}

User

properties {
  name = "myUserProp"
  value = "user@example.com"
}

Team

properties {
  name = "myTeamProp"
  value = "argo-admins"
}

Datetime

properties {
  name = "myDatetimeProp"
  value = "2022-04-18T11:44:15.345Z"
}

Timer

properties {
  name = "myTimerProp"
  value = "2023-04-18T11:44:15.345Z"
}

YAML

properties {
  name = "myYAMLProp"
  value = "my: yaml"
}

The following parameters are required:

• name - the name of the property in the blueprint definition;
• value - the value of the property (for non-array properties);
• items - an array of values (for array properties).

note

To set a default value, use the object keyword default_value with the desired value as the key. For example:

properties {
  name = "myStringProp"
  default_value = {
    "value": "My string"
  }
}

To set default values for array properties, use the default_items keyword with the desired array as its value. For example:

properties {
name = "myArrayProp"
default_items = [1,2,3]
}

relations schema

The relations schema maps a target entity to the source entity definition:

resource "port-labs_entity" "myEntity" {
  identifier = "myEntity" # Entity identifier
  title      = "My Entity" # Entity title
  blueprint  = "myBlueprint" # Identifier of the blueprint to create this entity from

  # Entity properties
  ...

  relations {
    name  = "myRelation"
    identifier = "myTargetEntityIdentifier"
  }

  relations {
    name  = "myAdditionalManyRelation"
    identifiers = ["myAdditionalTargetEntityIdentifier", myAdditionalTargetEntityIdentifier2"]
  }
}

Definition

Single

The following parameters are required:

• name - the identifier of the relation in the blueprint definition;
• identifier - the identifier of the target entity.

Many

The following parameters are required:

• name - the identifier of the relation in the blueprint definition;
• identifiers - the identifiers of the target entities.

Ingest data using the Terraform provider

To ingest data to the software catalog using the Terraform provider, you will define port-labs_entity resources in your Terraform definition files:

Create

To create an entity using Terraform, add a port-labs_entity resource to your .tf definition file:

resource "port-labs_entity" "myEntity" {
  identifier = "myEntity"
  title      = "My Entity"
  blueprint  = "myBlueprint"

  properties {
    name  = "myStringProp"
    value = "Example microservice"
  }
  properties {
    name  = "myNumberProp"
    value = 1
  }
  properties {
    name  = "myArrayProp"
    items = ["#rnd", "#deployments"]
  }
  properties {
    name  = "myObjectProp"
    value = jsonencode({ "foo" : "bar" })
  }
  properties {
    name  = "myBoolProp"
    value = true
  }
}

Then run the following commands to apply your changes and update the catalog:

# To view Terraform's planned changes based on your .tf definition file:
terraform plan
# To apply the changes and update the catalog
terraform apply

After running these commands, you will see your catalog updated with the new entities.

Update

To update an entity using Terraform, update the existing port-labs_entity resource in your .tf definition file and then run terraform apply.

It is also possible to start managing existing entities using Port's Terraform provider, to begin managing an existing entity, add a new port-labs_entity resource to your .tf definition file and make the desired changes:

resource "port-labs_entity" "myExistingEntity" {
  identifier = "myExistingEntity"
  title      = "My Entity"
  blueprint  = "myBlueprint"

  # Entity properties and relations
  ...
}

info

Important notes about adding existing entities to the Terraform provider:

• It is important to specify the identifier of the entity, otherwise terraform will create a new entity with an autogenerated identifier.
• Port's Terraform provider uses the create/override strategy, meaning for an existing entity, any properties not defined in the resource definition will be overridden with empty values.

Delete

To delete an entity using Terraform, simply remove the port-labs_entity resource defined in your .tf definition file and then run terraform apply.

Import existing data to the Terraform state

Blueprint

To import an existing blueprint to the Terraform state, add a port-labs_blueprint resource to your .tf definition file:

resource "port-labs_blueprint" "myBlueprint" {
  ...
}

Then run the following command to import the blueprint to the Terraform state:

terraform import port-labs_blueprint.myBlueprint "{blueprintIdentifier}"

Entity

To import an existing entity to the Terraform state, add a port-labs_entity resource to your .tf definition file:

resource "port-labs_entity" "myEntity" {
  ...
}

Then run the following command to import the entity to the Terraform state:

terraform import port-labs_entity.myEntity "{blueprintIdentifier}:{entityIdentifier}"

Examples

Refer to the examples page for practical configurations and their corresponding blueprint definitions.