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.
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โ
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.
- If an
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
- Number
- Boolean
- Object
- Array
- URL
- User
- Team
- Datetime
- Timer
- YAML
properties {
name = "myStringProp"
value = "My string"
}
properties {
name = "myNumberProp"
value = 7
}
properties {
name = "myBooleanProp"
value = true
}
properties {
name = "myObjectProp"
value = jsonencode({ "my" : "object" })
}
properties {
name = "myArrayProp"
items = [1, 2, 3]
}
properties {
name = "myUrlProp"
value = "https://example.com"
}
properties {
name = "myEmailProp"
value = "me@example.com"
}
properties {
name = "myUserProp"
value = "user@example.com"
}
properties {
name = "myTeamProp"
value = "argo-admins"
}
properties {
name = "myDatetimeProp"
value = "2022-04-18T11:44:15.345Z"
}
properties {
name = "myTimerProp"
value = "2023-04-18T11:44:15.345Z"
}
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).
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
- Many
The following parameters are required:
name
- theidentifier
of the relation in the blueprint definition;identifier
- the identifier of the target entity.
The following parameters are required:
name
- theidentifier
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
- Update
- Delete
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.
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
...
}
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.
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
- Entity
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}"
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.