Edge Delta Terraform Provider

Guide on using the Edge Delta Terraform Provider for managing pipelines, dashboards, and deploying multiple fleets, including installation, configuration options, and multi-environment deployment workflows.

  7 minute read  

Prerequisites

  • Terraform >= 1.0 (download from terraform.io/downloads)
  • terraform-provider-edgedelta >= 0.0.8
  • Edge Delta API credentials (Organization ID and API Token from the Edge Delta dashboard)

Verify your Terraform installation by running terraform version in your terminal.

Installing the Provider

Add the following to your Terraform configuration:

terraform {
  required_providers {
    edgedelta = {
      source  = "edgedelta/edgedelta"
      version = "0.0.8"
    }
  }
}

provider "edgedelta" {
  org_id       = var.ORG_ID
  api_secret   = var.ED_API_TOKEN
  # api_endpoint = "https://api.edgedelta.com"  # Optional, defaults to this value
}

Run terraform init to download and install the provider.

Configuration Options

API Secret and Organization ID

You must include your Edge Delta Organization ID and API Token in the configuration. Use Terraform variables to pass sensitive values securely.

Create a terraform.tfvars file for your credentials:

ORG_ID       = "your-organization-id-here"
ED_API_TOKEN = "your-api-token-here"

Define the variables in your Terraform configuration:

variable "ED_API_TOKEN" {
  type        = string
  description = "Edge Delta API token"
  sensitive   = true
}

variable "ORG_ID" {
  type        = string
  description = "Edge Delta organization ID"
}

Never commit terraform.tfvars to version control as it contains sensitive information.

API Endpoint

The provider supports an optional api_endpoint parameter for connecting to a custom API URL:

provider "edgedelta" {
  org_id       = var.ORG_ID
  api_secret   = var.ED_API_TOKEN
  api_endpoint = "https://custom-api.example.com"  # Defaults to https://api.edgedelta.com
}

Most users do not need to set this parameter.

Environment Options

When creating configurations, specify one of the following environments:

  • Kubernetes: For Kubernetes clusters (requires fleet_subtype when using Edge fleet type)
  • Linux: For Linux servers
  • Windows: For Windows servers
  • MacOS: For macOS systems
  • Docker: For Docker containers
  • Helm: For Helm-based deployments

Fleet Type Options

  • Edge: For edge deployments
  • Cloud: For cloud deployments

Fleet Subtype Options

Required only when using Kubernetes environment with Edge fleet type:

  • Edge: Standard edge deployment
  • Coordinator: Coordinator node
  • Gateway: Gateway node

Optional Parameters

The edgedelta_config resource supports these optional parameters:

  • conf_id: Specify an existing configuration ID to manage. When omitted, Terraform creates a new configuration on the first terraform apply
  • cluster_name: Group pipelines under a cluster name
  • description: Human-readable description for the configuration
  • auto_deploy: Set to false to save configurations without deploying (default is true)

Resource Outputs

The edgedelta_config resource exports these attributes:

  • id: The active configuration ID. Use this output instead of conf_id when referencing the configuration
  • tag: The tag value from the configuration content

Deploying Multiple Fleets

This section walks through deploying multiple Edge Delta fleets using Terraform. You can deploy the same base configuration to multiple environments (production, staging, development, etc.) with different tags and settings.

Step 1: Create Your Project Structure

Create a new folder for your Terraform project and add the following files:

your-project-folder/
├── main.tf
├── terraform.tfvars
├── base-config.yml
└── .gitignore (optional)

Step 2: Create main.tf

Create main.tf with the following template:

terraform {
  required_providers {
    edgedelta = {
      source  = "edgedelta/edgedelta"
      version = "0.0.8"
    }
  }
}

variable "ED_API_TOKEN" {
  type        = string
  description = "Edge Delta API token"
  sensitive   = true
}

variable "ORG_ID" {
  type        = string
  description = "Edge Delta organization ID"
}

provider "edgedelta" {
  org_id     = var.ORG_ID
  api_secret = var.ED_API_TOKEN
}

# Define your fleets
locals {
  base_config = file("${path.module}/base-config.yml")
  fleets = {
    "production" = {
      tag           = "my-prod-fleet"
      environment   = "Kubernetes"
      fleet_type    = "Edge"
      fleet_subtype = "Edge"
    }
    "staging" = {
      tag         = "my-staging-fleet"
      environment = "Linux"
      fleet_type  = "Edge"
    }
    "development" = {
      tag         = "my-dev-fleet"
      environment = "Docker"
      fleet_type  = "Edge"
    }
  }
}

# Create config resources for each fleet
resource "edgedelta_config" "fleet" {
  for_each = local.fleets

  config_content = replace(
    local.base_config,
    "tag: \"PLACEHOLDER_TAG\"",
    "tag: \"${each.value.tag}\""
  )

  environment   = each.value.environment
  fleet_type    = each.value.fleet_type
  fleet_subtype = try(each.value.fleet_subtype, null)
  cluster_name  = try(each.value.cluster_name, null)
  description   = try(each.value.description, null)
}

# Output the created config IDs
output "fleet_config_ids" {
  value = {
    for k, v in edgedelta_config.fleet : k => {
      id          = v.id
      tag         = v.tag
      environment = local.fleets[k].environment
    }
  }
  description = "Map of fleet names to their config IDs, tags, and environments"
}

Step 3: Create terraform.tfvars

Create terraform.tfvars with your credentials:

ORG_ID       = "your-organization-id-here"
ED_API_TOKEN = "your-api-token-here"

Step 4: Create base-config.yml

Create base-config.yml with your Edge Delta pipeline configuration template. Include PLACEHOLDER_TAG in the settings section — Terraform will replace this with each fleet’s unique tag:

version: v3
settings:
  tag: "PLACEHOLDER_TAG"
# ... rest of your configuration ...

Step 5: Create .gitignore (Optional)

If using version control, create a .gitignore file to protect sensitive information:

# Terraform files
.terraform/
*.tfstate
*.tfstate.backup
.terraform.lock.hcl

# Sensitive variables
terraform.tfvars
*.tfvars

Step 6: Initialize and Deploy

Initialize Terraform to download the provider:

terraform init -upgrade

Review the deployment plan:

terraform plan

Deploy your fleets:

terraform apply

Type yes when prompted to confirm. Terraform will create all fleet configurations and display the created config IDs.

Step 7: Verify Deployment

After deployment, Terraform outputs the created config IDs:

fleet_config_ids = {
  "production" = {
    id = "abc123..."
    tag = "my-prod-fleet"
    environment = "Kubernetes"
  }
  "staging" = {
    id = "def456..."
    tag = "my-staging-fleet"
    environment = "Linux"
  }
}

Verify in the Edge Delta dashboard that your fleets appear with the correct tags.

Making Changes

Adding a New Fleet

Edit main.tf and add a new entry to the fleets map, then run terraform plan followed by terraform apply.

Updating an Existing Fleet

Edit the fleet entry in main.tf, then run terraform plan to preview changes and terraform apply to update.

Updating the Base Configuration

Edit base-config.yml, then run terraform plan to see which fleets will be updated and terraform apply to update all fleets.

Importing Existing Configurations

You can import existing Edge Delta configurations into Terraform state using terraform import.

  1. Define an empty resource block in your configuration:

    resource "edgedelta_config" "imported_config" {
}

  2. Run the import command with your configuration ID:

    terraform import edgedelta_config.imported_config <config-id>

  3. After importing, add the required config_content parameter to your resource block to manage the configuration with Terraform.

Troubleshooting

Error: “environment is required” Ensure each fleet has an environment field set to one of the valid options.

Error: “fleet_subtype is required” When using environment = "Kubernetes" with fleet_type = "Edge", you must set fleet_subtype to Edge, Coordinator, or Gateway.

Error: API authentication failed Verify your ORG_ID and ED_API_TOKEN in terraform.tfvars and ensure your API token is still valid.

Configuration not deploying By default, auto_deploy = true and configurations deploy automatically after saving. If you’ve set auto_deploy = false, deploy manually through the Edge Delta dashboard.

Best Practices

  • Use descriptive tags: Make tags unique and meaningful (e.g., prod-us-east-1, staging-eu-west-1)
  • Review plans: Always run terraform plan before terraform apply
  • Protect credentials: Never commit terraform.tfvars to version control
  • Use version control: Track your main.tf and base-config.yml in git for change history

Managing Dashboards

The edgedelta_dashboard resource allows you to create and manage Edge Delta dashboards through Terraform.

Basic Dashboard

resource "edgedelta_dashboard" "monitoring" {
  dashboard_name = "Infrastructure Monitoring"
  description    = "Main monitoring dashboard for production infrastructure"
  tags           = ["infrastructure", "monitoring", "production"]

  definition = file("${path.module}/dashboards/monitoring.json")
}

Dashboard with Inline Definition

resource "edgedelta_dashboard" "simple" {
  dashboard_name = "Simple Dashboard"

  definition = jsonencode({
    panels = [
      {
        type  = "graph"
        title = "Requests per Second"
      }
    ]
  })
}

Dashboard Parameters

Required:

  • dashboard_name: Name of the dashboard

Optional:

  • description: Description of the dashboard
  • tags: List of searchable tags for the dashboard
  • definition: Dashboard definition as a JSON string. Use file() to load from a file or jsonencode() for inline definitions

Dashboard Outputs

  • dashboard_id: Unique identifier for the dashboard
  • creator: User ID who created the dashboard
  • updater: User ID who last updated the dashboard
  • created: UTC timestamp of dashboard creation
  • updated: UTC timestamp of last update

Importing Dashboards

You can import existing dashboards into Terraform state using terraform import.

Import a single dashboard:

terraform import edgedelta_dashboard.example <dashboard-id>

Import multiple dashboards using comma-separated IDs:

terraform import edgedelta_dashboard.example <id1>,<id2>,<id3>

Import all dashboards:

terraform import edgedelta_dashboard.example "*"