Skip to main content

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 = {
source = "port-labs/port-labs"
version = "~> 1.0.0"
}
}
}

provider "port" {
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_entity​

The port_entity resource defines a basic entity:

resource "port_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_entity resource:

  • identifier - the identifier of the entity;
    • If an identifier is not provided, an identifier will be autogenerated.
  • 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_entity" "myEntity" {
identifier = "myEntity" # Entity identifier
title = "My Entity" # Entity title
blueprint = "myBlueprint" # Identifier of the blueprint to create this entity from

properties = {
string_props = {
"myStringProp" = "My string"
}

number_props = {
"myNumberProp" = 7
}

array_props = {
string_items = {
"myArrayProp" = ["a", "b", "c"]
}
}
}
# Entity relations
...
}

Definition​

properties = {
string_props = {
"myStringProp" = "My string"
}
}

relations schema​

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

resource "port_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 = {
single_relations = {
"mySingleRelation" = "myTargetEntityIdentifier"
}
}

relations = {
many_relations = {
"myManyRelation" = ["myTargetEntityIdentifier", "myTargetEntityIdentifier2"]
}
}
}

Definition​

the schema is as follows:

relations {
single_relations = {
# Key-value pair of the relation identifier and the target identifier
"mySingleRelation" = "myTargetEntityIdentifier"
}
}

Ingest data using the Terraform provider​

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

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

resource "port_entity" "myEntity" {
identifier = "myEntity"
title = "My Entity"
blueprint = "myBlueprint"

properties = {
"string_props" = {
"myStringProp" = "My string"
}
"number_props" = {
"myNumberProp" = 7
}
"boolean_props" = {
"myBooleanProp" = true
}
"object_props" = {
"myObjectProp" = jsonencode({ "my" : "object" })
}
"array_props" = {
"string_props" = {
"myArrayProp" = ["a", "b", "c"]
}
}
}
}

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.

Import existing data to the Terraform state​

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



resource "port_entity" "myEntity" {
...
}


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


terraform import port_entity.myEntity "{blueprintIdentifier}:{entityIdentifier}"
Applying after import

Before using terraform import to bring data from your Port account into your Terraform state file, make sure your resource definitions match the schema of your resources in Port. If they don't, your state will be deleted in the next terraform apply, since Terraform will try to apply the empty resources and override the imported state, while also updating Port in the process.

Examples​

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