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.).

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 = "~> 2.0.3"
    }
  }
}

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
  base_url  = "https://api.getport.io"
}

Selecting a Port API URL by account region

The baseUrl, port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters are used to select which instance or Port API will be used.

Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.

• If you use the EU region of Port (https://app.getport.io), your API URL is https://api.getport.io.
• If you use the US region of Port (https://app.us.getport.io), your API URL is https://api.us.getport.io.

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

String

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

Number

properties = {
  number_props = {
    "myNumberProp" = 7
  }
}

Boolean

properties = {
  boolean_props = {
    "myBooleanProp" = true
  }
}

Object

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

Array

properties = {
  array_props = {
    string_props = {
      "myArrayProp" = ["a", "b", "c"])
    }
  }
}

URL

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

Email

properties = {
  string_props = {
    "myEmailProp" = "me@example.com"
  }
}

User

properties = {
 string_props = {
   "myUserProp" = "argo-admin"
  }
}

Team

properties = {
  string_props = {
    "myTeamProp" = "argo-admins"
  }
}

Datetime

properties = {
  string_props = {
    "myDatetimeProp" = "2023-04-18T11:44:15.345Z"
  }
}

Timer

properties = {
  string_props = {
    "myUserProp" = "argo-admin"
  }
}

YAML

properties = {
  string_props = {
    "myYamlProp" = "myKey: myValue"
  }
}

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

Single

the schema is as follows:

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

Many

the schema is as follows:

relations {
  many_relations = {
    # Key-value pair of the relation identifier and the target identifiers
    "myManyRelation" = ["myTargetEntityIdentifier", "myTargetEntityIdentifier2"]
  }
}

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:

Create

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.

Update

To update an entity using Terraform, update the existing port_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_entity resource to your .tf definition file and make the desired changes:

resource "port_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_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_blueprint resource to your .tf definition file:

resource "port_blueprint" "myBlueprint" {
  ...
}

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

terraform import port_blueprint.myBlueprint "{blueprintIdentifier}"

Entity

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.

Advanced Example

See this guide which explains more in depth of how you can use import state to manage Port integrations using Terraform