# Migrating from Terraform Provider v1.x to v2.0

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

| Aspect | v1.x (API v3) | v2.0 (API v4) |
| --- | --- | --- |
| **API Version** | Azion API v3 | Azion API v4 |
| **Domain Management** | `azion_domain` resource | `azion_workload` and `azion_workload_deployment` resources |
| **Origin Management** | `azion_edge_application_origin` resource | `azion_connector` resource |
| **Functions** | `azion_edge_function` resource | `azion_function` resource |
| **Custom Pages** | Not available | `azion_custom_page` resource |

### Version Compatibility

| Terraform Provider Version | API Version | Status |
| --- | --- | --- |
| 1.41.0 and earlier | API v3 | Deprecated |
| 2.0.0 and later | API v4 | Current |

---

## 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](/en/documentation/products/accounts/personal-tokens/) 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:

```bash
# 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:

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

:::warning
Version 1.41.0 and earlier no longer receive updates or bug fixes. Plan your migration to v2.0 as soon as possible.
:::

---

## 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:

| Resource | Status | Replacement |
| --- | --- | --- |
| `azion_domain` | Removed | Use `azion_workload` and `azion_workload_deployment` |
| `azion_domains` (data source) | Removed | Use `azion_workloads` data source |
| `azion_edge_application_origin` | Removed | Use `azion_connector` |
| `azion_edge_applications_origins` (data source) | Removed | Use `azion_connectors` data source |

### Renamed Resources

| v1.x Resource | v2.0 Resource | Notes |
| --- | --- | --- |
| `azion_edge_function` | `azion_function` | Resource renamed to align with new product naming |

### New Resources in v2.0

| Resource | Description |
| --- | --- |
| `azion_workload` | Manage Azion workloads (replaces domain management) |
| `azion_workload_deployment` | Manage workload deployments |
| `azion_connector` | Manage Azion connectors (replaces origin management) |
| `azion_custom_page` | Manage custom pages |

### Unchanged Resources

The following resources remain available with their original names:

| Resource | Description |
| --- | --- |
| `azion_intelligent_dns_zone` | DNS zones |
| `azion_intelligent_dns_record` | DNS records |
| `azion_intelligent_dns_dnssec` | DNSSEC settings |
| `azion_network_list` | Network Lists |
| `azion_waf_rule_set` | WAF rule sets |
| `azion_digital_certificate` | Digital certificates |
| `azion_environment_variable` | Environment variables |

---

## 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:

| v1.x (Domain) | v2.0 (Workload) |
| --- | --- |
| `azion_domain` | `azion_workload` + `azion_workload_deployment` |
| `azion_domains` (data source) | `azion_workloads` |

**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:

| v1.x (Origin) | v2.0 (Connector) |
| --- | --- |
| `azion_edge_application_origin` | `azion_connector` |
| `azion_edge_applications_origins` (data source) | `azion_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

| v1.x | v2.0 |
| --- | --- |
| `azion_edge_function` | `azion_function` |
| `azion_edge_functions` (data source) | `azion_functions` data source |

---

## Migration Examples

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

### Domain to Workload Migration

#### v1.x Configuration

```hcl
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

```hcl
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

```hcl
# 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

```hcl
# 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

```hcl
# 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

```hcl
# 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

```hcl
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

```hcl
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:

```hcl
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:

```bash
terraform init -upgrade
```

### Step 3: Remove Deprecated Resources from State

Remove deprecated resources from your Terraform state:

```bash
# 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](#migration-examples) section.

### Step 5: Import New Resources

Import your existing resources to the new resource types:

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/en/documentation/products/terraform-provider/)
- [Terraform Provider v1.x Documentation](/en/documentation/products/terraform-provider-v3/) (Deprecated)
- [Azion API v4 Documentation](https://api.azion.com/)
- [Terraform Registry - Azion Provider](https://registry.terraform.io/providers/aziontech/azion/latest)

### Getting Help

If you encounter issues during migration:

1. Review the [Troubleshooting](#troubleshooting) section
2. Consult the [Terraform Registry documentation](https://registry.terraform.io/providers/aziontech/azion/latest/docs)
3. Contact Azion Support through the [Support Portal](https://tickets.azion.com/)
4. Visit the [Azion Community](https://www.azion.com/en/documentation/) 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