> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Terraform Cloud & Terraform Enterprise

Terraform iconTerraform icon
Loading version...

Port's Terraform Cloud integration allows you to model Terraform Cloud resources in your software catalog and ingest data into them.

Supported resources External link iconOrganizationProjectWorkspaceRunState VersionState FileHealth Assessment

Core support

Live eventsSee supported resources
Terraform enterprise (self hosted)

Port supports both Terraform Cloud and Terraform Enterprise versions (self hosted). The following data model and use cases are common for both integrations. If installing Port exporter for Terraform Enterprise, you will be required to specify your Terraform 's host URL by passing the following parameter to the installer: integration.config.terraformCloudHost

Setup​

Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.

Configuration​

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
- kind: organization
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .attributes.name
        blueprint: '"terraformCloudOrganization"'
        properties:
          externalId: .attributes."external-id"
          ownerEmail: .attributes.email
          collaboratorAuthPolicy: .attributes."collaborator-auth-policy"
          planExpired: .attributes."plan-expired"
          planExpiresAt: .attributes."plan-expires-at"
          permissions: .attributes.permissions
          samlEnabled: .attributes."saml-enabled"
          defaultExecutionMode: .attributes."default-execution-mode"
- kind: project
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .attributes.name
        blueprint: '"terraformCloudProject"'
        properties:
          name: .attributes.name
          permissions: .attributes.permissions
        relations:
          organization: .relationships.organization.data.id
- kind: workspace
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .attributes.name
        blueprint: '"terraformCloudWorkspace"'
        properties:
          organization: .relationships.organization.data.id
          createdAt: .attributes."created-at"
          updatedAt: .attributes."updated-at"
          terraformVersion: .attributes."terraform-version"
          locked: .attributes.locked
          executionMode: .attributes."execution-mode"
          resourceCount: .attributes."resource-count"
          latestChangeAt: .attributes."latest-change-at"
          tags: .__tags
        relations:
          currentStateVersion: .relationships."current-state-version".data.id
          project: .relationships.project.data.id
- kind: state-version
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .id
        blueprint: '"terraformCloudStateVersion"'
        properties:
          createdAt: .attributes."created-at"
          serial: .attributes.serial
          status: .attributes.status
          size: .attributes.size
          isResourcesProcessed: .attributes."resources-processed"
          hostedStateDownloadUrl: .attributes."hosted-state-download-url"
          hostedJsonDownloadUrl: .attributes."hosted-json-state-download-url"
          vcsCommitUrl: .attributes."vcs-commit-url"
          outputData: .__output
- kind: run
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .attributes.message
        blueprint: '"terraformCloudRun"'
        properties:
          createdAt: .attributes."created-at"
          status: .attributes.status
          hasChanges: .attributes."has-changes"
          isDestroy: .attributes."is-destroy"
          message: .attributes.message
          terraformVersion: .attributes."terraform-version"
          appliedAt: .attributes."status-timestamps"."applied-at"
          plannedAt: .attributes."status-timestamps"."planned-at"
          source: .attributes.source
        relations:
          terraformCloudWorkspace: .relationships.workspace.data.id
- kind: state-file
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .lineage + "-" + (.serial | tostring)
        title: '"State v" + (.serial | tostring)'
        blueprint: '"terraformCloudStateFile"'
        properties:
          version: .version
          terraformVersion: .terraform_version
          serial: .serial
          lineage: .lineage
          resourceCount: .resources | length
          resourceTypes: .resources | map(.type) | unique | sort
          providers: .resources | map(.provider) | unique | sort
          outputKeys: .outputs | keys

Mapping & selectors per resource​

Use the explorer below to view sample payloads and the resulting Port entities for each resource type. For additional resources and advanced configurations, see the examples page.

Set up live events​

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

BaseUrl & webhook configuration​

To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Terraform Cloud integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.

  • If Terraform Cloud and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
    For Kubernetes deployments, create a service to expose the integration pod and use the service URL as liveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient.
  • If Terraform Cloud is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Terraform Cloud can reach.

If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.

Debugging local integrations

To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)

Monitoring and sync status​

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.

Examples​

To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your data sources page.
Find the integration in the list of data sources and click on it to open the playground.

Examples of blueprints and the relevant integration configurations can be found in the examples page.

Relevant Guides​

For relevant guides and examples, see the guides section.