Skip to main content

Check out Port for yourself 

Terraform Cloud Actions

Port's Terraform Cloud integration allows you to trigger Terraform Cloud runs directly from Port.

Overview​

You can implement this action in two ways:

  1. Synced webhook and secrets: A simpler approach that uses Port's secret management to store your Terraform Cloud credentials.
  2. Execution agent: A slightly more complex approach that runs within your infrastructure, keeping credentials in your environment.

Prerequisites​

  • A Terraform Cloud User token or Team token.

    Terraform Cloud run endpoint

    Note: Terraform Cloud run endpoint cannot be accessed with organization tokens. You must access it with a user token or team token.

  • If you choose to implement using the Execution Agent, you will need to:

    • Install Helm on your infrastructure
    • Contact Port support to set up a Kafka topic for your organization.

Set up data model​

Before implementing either approach, you'll need to create a blueprint for Terraform Cloud workspaces:

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose "Edit JSON".

  4. Add this JSON schema:

    Terraform Cloud workspace blueprint
    {
      "identifier": "terraform_cloud_workspace",
      "title": "Terraform Cloud Workspace",
      "icon": "Terraform",
      "schema": {
        "properties": {
          "workspace_id": {
            "title": "Workspace Id",
            "type": "string"
          },
          "organization_name": {
            "title": "Organization Name",
            "type": "string"
          },
          "workspace_name": {
            "title": "Workspace Name",
            "type": "string"
          }
        },
        "required": ["workspace_id", "organization_name", "workspace_name"]
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "relations": {}
    }

  5. Click Save to create the blueprint.

Implementation​

You can trigger Terraform Cloud runs by leveraging Port's synced webhooks to directly interact with the Terraform Cloud API and secrets to store your Terraform Cloud credentials. This method simplifies the setup by handling everything within Port.

Add Port secrets

To add Terraform Cloud credentials to your portal:

  1. Click on the ... button in the top right corner of your Port application.

  2. Click on Credentials.

  3. Click on the Secrets tab.

  4. Click on + Secret and add:

    • TF_TOKEN: Your Terraform Cloud user or team token

Create Terraform Cloud self-service action

To create a self-service action that triggers a Terraform Cloud run, follow these steps:

  1. Head to the self-service page.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the following JSON configuration into the editor.

    Trigger TF Cloud Run action
    {
      "identifier": "terraform_cloud_workspace_trigger_run",
      "title": "Trigger TF Cloud Run",
      "icon": "Terraform",
      "trigger": {
        "type": "self-service",
        "operation": "DAY-2",
        "userInputs": {
          "properties": {
            "is_destroy": {
              "title": "Is Destroy",
              "type": "boolean",
              "default": false
            },
            "message": {
              "title": "Message",
              "type": "string",
              "default": "Triggered via Port"
            },
            "variables": {
              "title": "Variables",
              "type": "object",
              "default": {}
            }
          },
          "required": ["message"],
          "order": ["message", "is_destroy", "variables"]
        },
        "blueprintIdentifier": "terraform_cloud_workspace"
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://app.terraform.io/api/v2/runs",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "Authorization": "Bearer {{.secrets.TF_TOKEN}}",
          "Content-Type": "application/vnd.api+json"
        },
        "body": {
          "data": {
            "attributes": {
              "is-destroy": "{{.inputs.is_destroy}}",
              "message": "{{.inputs.message}}",
              "variables": "{{.inputs.variables | toTFVariables}}"
            },
            "type": "runs",
            "relationships": {
              "workspace": {
                "data": {
                  "type": "workspaces",
                  "id": "{{.entity.properties.workspace_id}}"
                }
              }
            }
          }
        }
      },
      "requiredApproval": false
    }

  5. Click Save.

Now you should see the Trigger TF Cloud Run action in the self-service page. 🎉

Let's test it!​

  1. Head to the self-service page of your portal

  2. Click on the Terraform Cloud run action you created

  3. Fill in the run details:

    • Message describing the purpose of the run
    • Whether this is a destroy operation
    • Any variables needed for the Terraform run

  4. Click on Execute

  5. Wait for the run to be triggered in Terraform Cloud

  6. Check your Terraform Cloud workspace page to see the new run