Terraform Cloud & Terraform Enterprise

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 OrganizationProjectWorkspaceRunState VersionState FileHealth AssessmentTeamOrganization MembershipTeam Workspace AccessTeam Project Access

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.

Choose method

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
- kind: team
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .attributes.name
        blueprint: '"terraformCloudTeam"'
        properties:
          visibility: .attributes.visibility
          usersCount: .attributes."users-count"
          description: .attributes.description
          ssoTeamId: .attributes."sso-team-id"
          organizationAccess: .attributes."organization-access"
        relations:
          organization: .relationships.organization.data.id
- kind: organization-membership
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: .attributes.email
        blueprint: '"terraformCloudOrganizationMembership"'
        properties:
          email: .attributes.email
          status: .attributes.status
          createdAt: .attributes."created-at"
          userId: .relationships.user.data.id
        relations:
          organization: .relationships.organization.data.id
          teams: '[.relationships.teams.data[].id]'
- kind: team-workspace-access
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: '"\(.relationships.team.data.id) → \(.relationships.workspace.data.id)"'
        blueprint: '"terraformCloudTeamWorkspaceAccess"'
        properties:
          access: .attributes.access
          runs: .attributes.runs
          variables: .attributes.variables
          stateVersions: .attributes."state-versions"
          sentinelMocks: .attributes."sentinel-mocks"
          workspaceLocking: .attributes."workspace-locking"
          runTasks: .attributes."run-tasks"
          policyOverrides: .attributes."policy-overrides"
        relations:
          team: .relationships.team.data.id
          workspace: .relationships.workspace.data.id
- kind: team-project-access
  selector:
    query: 'true'
  port:
    entity:
      mappings:
        identifier: .id
        title: '"\(.relationships.team.data.id) → \(.relationships.project.data.id)"'
        blueprint: '"terraformCloudTeamProjectAccess"'
        properties:
          access: .attributes.access
          projectAccess: .attributes."project-access"
          workspaceAccess: .attributes."workspace-access"
        relations:
          team: .relationships.team.data.id
          project: .relationships.project.data.id

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.

Teams, memberships and access records

The organization-membership kind lists human members only, because Terraform Cloud omits service account memberships from the memberships listing. On organizations without the teams entitlement, Terraform Cloud returns a reduced team payload that omits organization-access, so the organizationAccess property is not ingested. Organizations whose teams and memberships your token cannot read are skipped, so revoking that access removes their entities from your catalog on the next resync.

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.

Self-hosted

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.

Scaling for high-volume, self-hosted deployments

If you're running high volumes of live events in a self-hosted deployment and want better reliability, event durability, or horizontal scalability, you can optionally set up Port's dedicated live events infrastructure. See live events at scale for details.

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 connectors page.
Find the integration in the list of connectors 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.