This guide provides detailed instructions for migrating from Azion Terraform Provider v1.x (API v3) to v2.0 (API v4). Follow the steps below to ensure a smooth transition.

Migration Overview

Terraform Provider v2.0 represents a major version that migrates to Azion API v4. This version introduces new resources and removes deprecated ones to align with the new API architecture.

Key Changes

Version Compatibility

Before You Begin

Before starting the migration process, make sure you’ve completed the following preparations.

Prerequisites

• Terraform: Version 1.0 or later installed
• Azion Account: Valid account with API v4 access
• Personal Token: A valid personal token with appropriate permissions
• Backup: A complete backup of your current Terraform state and configurations

Configuration Backup

Create a backup of your current Terraform configuration and state files before making any changes:

# Create a backup directory
mkdir -p ~/terraform-backup

# Copy your configuration files
cp -r ./your-terraform-project ~/terraform-backup/

# Backup state file (if using local state)
cp terraform.tfstate ~/terraform-backup/
cp terraform.tfstate.backup ~/terraform-backup/ 2>/dev/null || true

# If using remote state, download a local copy
terraform state pull > ~/terraform-backup/terraform.tfstate

Pin Your Version

If you need to remain on v1.x temporarily, pin the provider version:

terraform {
  required_providers {
    azion = {
      source  = "aziontech/azion"
      version = "1.41.0"
    }
  }
}

Breaking Changes

This section details the breaking changes between v1.x and v2.0.

Removed Resources

The following resources and data sources were removed in v2.0:

Renamed Resources

New Resources in v2.0

Unchanged Resources

The following resources remain available with their original names:

Resource Mapping

This section provides detailed mapping between v1.x and v2.0 resources.

Domain to Workload Mapping

Domain management in v1.x has been replaced by a two-resource model in v2.0:

Key Differences:

• v1.x: A single azion_domain resource managed the entire domain lifecycle
• v2.0: Separation of concerns with azion_workload (definition) and azion_workload_deployment (deployment)

Origin to Connector Mapping

Origin management has been replaced by connectors:

Key Differences:

• v1.x: Origins were defined within the Applications context
• v2.0: Connectors are independent resources that provide more flexible integration options

Edge Function to Function Mapping

Migration Examples

This section provides side-by-side configuration examples for migrating your Terraform resources.

Domain to Workload Migration

v1.x Configuration

terraform {
  required_providers {
    azion = {
      source  = "aziontech/azion"
      version = "1.41.0"
    }
  }
}

provider "azion" {
  api_token = var.api_token
}

# Domain resource (v1.x)
resource "azion_domain" "example" {
  name               = "my-domain"
  cname_access_only  = false
  digital_certificate = 1234
  edge_application   = 5678
  is_active          = true

  # Domain name binding
  domain_name = "example.com"
}

v2.0 Configuration

terraform {
  required_providers {
    azion = {
      source  = "aziontech/azion"
      version = "2.0.0"
    }
  }
}

provider "azion" {
  api_token = var.api_token
}

# Workload resource (v2.0)
resource "azion_workload" "example" {
  name = "my-workload"

  # Workload configuration options
  # See Terraform Registry documentation for complete options
}

# Workload deployment (v2.0)
resource "azion_workload_deployment" "example" {
  workload_id = azion_workload.example.id

  # Deployment configuration
  # See Terraform Registry documentation for complete options
}

Origin to Connector Migration

v1.x Configuration

# Edge Application Origin (v1.x)
resource "azion_edge_application_origin" "example" {
  edge_application_id = azion_edge_application_main_setting.example.id

  name               = "my-origin"
  origin_type        = "single_origin"
  origin_address     = "origin.example.com"
  origin_protocol    = "https"
  origin_path        = "/api"
  host_header        = "origin.example.com"

  # Connection settings
  connection_timeout = 30
  read_timeout       = 60
}

v2.0 Configuration

# Connector (v2.0)
resource "azion_connector" "example" {
  name = "my-connector"

  # Connector configuration
  # See Terraform Registry documentation for complete options

  # Example configuration
  origin = {
    address = "origin.example.com"
    protocol = "https"
    path = "/api"
  }

  # Connection settings
  connection_timeout = 30
  read_timeout = 60
}

Function Migration

v1.x Configuration

# Edge Function (v1.x)
resource "azion_edge_function" "example" {
  name    = "my-function"
  active  = true
  code    = file("${path.module}/function.js")

  # Function arguments
  json_args = jsonencode({
    key = "value"
  })
}

v2.0 Configuration

# Function (v2.0)
resource "azion_function" "example" {
  name   = "my-function"
  active = true
  code   = file("${path.module}/function.js")

  # Function arguments
  json_args = jsonencode({
    key = "value"
  })
}

Complete Example: Application with Workload

v1.x Configuration

terraform {
  required_providers {
    azion = {
      source  = "aziontech/azion"
      version = "1.41.0"
    }
  }
}

provider "azion" {
  api_token = var.api_token
}

# Edge Application
resource "azion_edge_application_main_setting" "app" {
  name = "my-application"
}

# Origin
resource "azion_edge_application_origin" "origin" {
  edge_application_id = azion_edge_application_main_setting.app.id
  name               = "my-origin"
  origin_type        = "single_origin"
  origin_address     = "origin.example.com"
}

# Domain
resource "azion_domain" "domain" {
  name             = "my-domain"
  edge_application = azion_edge_application_main_setting.app.id
  domain_name      = "example.com"
}

# Edge Function
resource "azion_edge_function" "func" {
  name   = "my-function"
  active = true
  code   = file("${path.module}/function.js")
}

v2.0 Configuration

terraform {
  required_providers {
    azion = {
      source  = "aziontech/azion"
      version = "2.0.0"
    }
  }
}

provider "azion" {
  api_token = var.api_token
}

# Application
resource "azion_application_main_setting" "app" {
  name = "my-application"
}

# Connector (replaces origin)
resource "azion_connector" "connector" {
  name = "my-connector"
  # Connector configuration
}

# Workload (replaces domain)
resource "azion_workload" "workload" {
  name = "my-workload"
}

# Workload deployment
resource "azion_workload_deployment" "deployment" {
  workload_id = azion_workload.workload.id
  # Deployment configuration
}

# Function (renamed)
resource "azion_function" "func" {
  name   = "my-function"
  active = true
  code   = file("${path.module}/function.js")
}

State Migration Steps

Follow these steps to migrate your Terraform state from v1.x to v2.0.

Step 1: Update Provider Version

Update your Terraform configuration to use Provider v2.0:

terraform {
  required_providers {
    azion = {
      source  = "aziontech/azion"
      version = "2.0.0"
    }
  }
}

Step 2: Initialize the New Provider

Run Terraform init to download the new provider:

terraform init -upgrade

Step 3: Remove Deprecated Resources from State

Remove deprecated resources from your Terraform state:

# Remove domain resources
terraform state rm azion_domain.example

# Remove origin resources
terraform state rm azion_edge_application_origin.example

# Remove function resources (will be recreated as azion_function)
terraform state rm azion_edge_function.example

Step 4: Update Configuration Files

Update your .tf files with the new resource configurations following the examples in the Migration Examples section.

Step 5: Import New Resources

Import your existing resources to the new resource types:

# Import workloads
terraform import azion_workload.example <workload_id>

# Import connectors
terraform import azion_connector.example <connector_id>

# Import functions
terraform import azion_function.example <function_id>

Step 6: Verify the Plan

Run a plan to verify expected changes:

terraform plan

Review the output carefully to ensure:

• No resources will be unexpectedly destroyed
• New resources will be created correctly
• Resource attributes are mapped correctly

Step 7: Apply Changes

Apply the changes:

terraform apply

Troubleshooting

This section covers common issues encountered during migration.

Common Errors and Solutions

Error: Provider Version Conflict

Error: Failed to query available provider packages
Could not retrieve the list of available versions for provider aziontech/azion

Solution: Make sure to specify the correct source and version. Run:

terraform init -upgrade

Error: Resource Type Not Found

Error: Invalid resource type
on main.tf line 10:
10: resource "azion_domain" "example" {
The provider aziontech/azion does not support resource type "azion_domain".

Solution: This resource was removed in v2.0. Replace with azion_workload and azion_workload_deployment resources.

Error: State Migration Failed

Error: Error refreshing state: azion_application_origin.example:
resource not found

Solution: The resource was already removed or doesn’t exist. Remove it from state:

terraform state rm azion_application_origin.example

Error: Import Not Found

Error: Cannot import non-existent remote object

Solution: Make sure the resource ID you’re importing exists in API v4. Some API v3 resources may have different IDs in API v4. Check the Azion Console to find the correct resource IDs.

Additional Resources

• Terraform Provider v2.0 Documentation
• Terraform Provider v1.x Documentation (Deprecated)
• Azion API v4 Documentation
• Terraform Registry - Azion Provider

Getting Help

If you encounter issues during migration:

1. Review the Troubleshooting section
2. Consult the Terraform Registry documentation
3. Contact Azion Support through the Support Portal
4. Visit the Azion Community for additional resources

Migration Checklist

Use this checklist to track your migration progress:

Preparation

• Verify account is enabled for API v4
• Backup current Terraform state
• Backup .tf configuration files
• Pin provider version to 1.41.0 (last v1.x version)
• Document current resources in use
• Identify resources that will be removed or renamed

Migration

• Update provider version to 2.0.0
• Run terraform init -upgrade
• Remove deprecated resources from state (azion_domain, azion_edge_application_origin, etc.)
• Update .tf configuration files
• Replace azion_domain with azion_workload + azion_workload_deployment
• Replace azion_edge_application_origin with azion_connector
• Replace azion_edge_function with azion_function
• Import new resources to state
• Run terraform plan and review changes

Validation

• Verify no resources will be unexpectedly destroyed
• Verify new resources will be created correctly
• Confirm attributes are mapped correctly
• Run terraform apply in test environment
• Validate migrated resources are working
• Update CI/CD pipelines if necessary

Post-Migration

• Remove unused legacy code
• Update project documentation
• Communicate changes to team
• Archive backups after confirming success