Hookdeck to Terraform State Initializer

This script fetches your existing Hookdeck connections and referenced transformations via the Hookdeck API and generates corresponding Terraform configuration files. It also outputs a sequence of recommended commands, including the necessary terraform import steps, to bring these existing resources under Terraform management and apply your configuration.

Prerequisites

• Node.js and npm (or yarn) installed.
• Terraform installed.
• A Hookdeck API Key.

Setup

1. Clone the repository (if applicable) or ensure you have the project files.
2. Install dependencies: Open your terminal in the project root directory and run:

   npm install

   or if you use yarn:

   yarn install

Usage

1. Run the script: Execute the script from the project root directory using the following command:

   npm run dev -- --apiKey YOUR_HOOKDECK_API_KEY --outputDir ./path/to/your/output_directory

   Replace:

   • YOUR_HOOKDECK_API_KEY with your actual Hookdeck API key.
   • ./path/to/your/output_directory with the desired directory where Terraform files will be generated (e.g., ./hookdeck_tf_config).

   The script will:

   • Fetch connections and referenced transformations from your Hookdeck account.
   • Generate the following files in your specified output directory:
     • provider.tf: Configures the Hookdeck Terraform provider.
     • variables.tf: Defines the hookdeck_api_key variable.
     • terraform.tfvars: Populated with the API key you provided.
     • connections.tf: Contains hookdeck_connection resources.
     • transformations.tf: Contains hookdeck_transformation resources (if any are referenced).
   • Print a "Next steps:" guide to the console. This guide includes commands to:
     • Change into the output directory.
     • Initialize Terraform (terraform init).
     • Import existing resources using terraform import (if applicable).
     • Plan your changes (terraform plan).
     • Apply your changes (terraform apply).

2. Follow the "Next steps" printed in the console: The script provides a clear sequence of commands. It's recommended to follow these steps in order:

   • cd ./path/to/your/output_directory: Navigate to where your Terraform files were generated.
   • terraform init: Initialize Terraform. This downloads the Hookdeck provider. The terraform.tfvars file (with your API key) will be used automatically.
   • Import Existing Resources: If connections or transformations were found, the script will print terraform import ... commands. Copy and execute these in your terminal. This step is crucial for managing existing resources. Example import commands printed by the script:

     terraform import hookdeck_connection.c_web_xxxxxxxxxxxx web_xxxxxxxxxxxx
     terraform import hookdeck_transformation.t_tfm_yyyyyyyyyyyy tfm_yyyyyyyyyyyy

   • terraform plan: Review the execution plan. Ideally, after imports, it should show "No changes. Your infrastructure matches the configuration." or only intended changes.
   • terraform apply: Apply the configuration.

Script Details

• The script uses yargs for command-line argument parsing.
• axios is used for making API calls to Hookdeck.
• Terraform resource names are generated based on the unique IDs of the connections and transformations (e.g., c_CONNECTION_ID, t_TRANSFORMATION_ID) to avoid naming conflicts.
• Filter rules in connections are generated with the nested json key structure as required by the Hookdeck Terraform provider.

Customizing the API Endpoint

By default, the script uses https://api.hookdeck.com/2025-01-01. You can override this by providing the --apiUrl argument:

npm run dev -- --apiKey YOUR_KEY --outputDir ./output --apiUrl https://your.custom.api.url/VERSION

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue.

(If you have specific contribution guidelines, like running linters, tests, or conventional commit messages, detail them here.)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Hookdeck Technologies Inc.