feat(byo_ip_prefix): support migration (#131)

* feat(zero_trust_organization): support v4 to v5 migration

* refactor imports to use import blocks generated in main.tf

* update readme

* feat(byo_ip_prefix): support migration

* set up structure for pass through of byo ip prefix env vars, fix linter

* add byo ip env vars, update prefix

* fix int tests

* update prefix consistency, import statements

* move state logic to provider

* update byo ip with warnings

* skip byo ip e2e test

* remove import in zero trust org

* remove any changes to import

* remove changes to runner

* add missing func

* remove e2e skip logic

* exclude in ci

Author: ssicard

.github/workflows/e2e-tests.yml

@@ -53,4 +53,4 @@ jobs:
 
       - name: Run E2E Tests (provider state upgrader)
         working-directory: ./tf-migrate
-        run: ./scripts/run-e2e-tests.sh --apply-exemptions --uses-provider-state-upgrader --provider ../provider --parallelism 5
+        run: ./scripts/run-e2e-tests.sh --apply-exemptions --uses-provider-state-upgrader --provider ../provider --parallelism 5 --exclude byo_ip_prefix

agents.md

@@ -564,6 +564,72 @@ import {
 }
 ```
 
+#### Skipping Resources from E2E Tests
+
+Some resources cannot be tested in E2E environments due to lifecycle constraints (cannot be created/destroyed) or external dependencies. To exclude a resource from E2E tests while keeping integration tests:
+
+**Add E2E-SKIP marker to the `*_e2e.tf` file:**
+
+```hcl
+# E2E-SKIP: Brief reason why E2E testing is not possible
+#
+# REASON FOR SKIP:
+# - Detailed explanation of constraints
+# - Why automated testing is not feasible
+#
+# TESTING COVERAGE:
+# ✓ Integration tests: What IS tested
+# ✓ Provider tests: What IS tested
+# ✗ E2E tests: Why NOT tested
+
+# Rest of file content...
+```
+
+**Pattern Rules:**
+
+1. **Marker location**: Must be in the first 20 lines of the `*_e2e.tf` file
+2. **Format**: `# E2E-SKIP:` (case-sensitive, must be in a comment)
+3. **Documentation**: Include detailed reasoning and alternative test coverage
+4. **Integration tests**: Continue to work normally (use separate input files)
+
+**Example: BYO IP Prefix**
+
+The `byo_ip_prefix` resource is skipped from E2E tests because:
+- Cannot be created via Terraform (requires manual account manager provisioning)
+- Cannot be destroyed (active bindings prevent deletion)
+- Requires manual intervention during migration
+
+See: `integration/v4_to_v5/testdata/byo_ip_prefix/input/byo_ip_prefix_e2e.tf`
+
+**E2E Runner Behavior:**
+
+```bash
+# When initializing E2E tests:
+./bin/e2e-runner init
+
+# Output shows skipped resources:
+Syncing resource files from testdata...
+  ✓ dns_record/dns_record.tf (from dns_record_e2e.tf)
+  ⊗ Skipped byo_ip_prefix (E2E-SKIP)
+  ✓ zone_setting/zone_setting.tf (from zone_setting_e2e.tf)
+
+  Total: 120 files synced
+  Skipped: 1 modules (E2E-SKIP)
+```
+
+**When to Use E2E-SKIP:**
+
+Use the E2E-SKIP marker when:
+- Resources cannot be created via Terraform/API
+- Resources cannot be destroyed (lifecycle constraints)
+- Resources require manual provisioning or external setup
+- E2E testing would require pre-existing infrastructure
+
+**Do NOT use E2E-SKIP for:**
+- Resources that can be imported (use import annotations instead)
+- Resources with slow operations (improve test efficiency instead)
+- Temporary test failures (fix the underlying issue)
+
 ---
 
 ## Drift Exemptions System
@@ -1196,6 +1262,50 @@ func (t *MyTransformer) TransformHCL(ctx *transform.Context) (*transform.Result,
 }
 ```
 
+### Pattern 7: Manual Intervention with Warning Comments
+
+When required fields cannot be automatically populated (e.g., values must come from external sources), add warning comments to guide users:
+
+```go
+// See: internal/resources/byo_ip_prefix/v4_to_v5.go
+// See: internal/resources/list_item/v4_to_v5.go
+
+func (m *V4ToV5Migrator) TransformConfig(ctx *transform.Context, block *hclwrite.Block) (*transform.TransformResult, error) {
+    body := block.Body()
+
+    // Remove deprecated fields
+    tfhcl.RemoveAttributes(body, "old_field_1", "old_field_2")
+
+    // Add warning comment for fields requiring manual intervention
+    warningMsg := "This resource requires manual intervention to add v5 required fields 'field_a' and 'field_b'. Find values in [source]. See migration documentation for details."
+    tfhcl.AppendWarningComment(body, warningMsg)
+
+    return &transform.TransformResult{
+        Blocks:         []*hclwrite.Block{block},
+        RemoveOriginal: false,
+    }, nil
+}
+```
+
+**Result in HCL:**
+```hcl
+resource "cloudflare_example" "test" {
+  account_id = "abc123"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'field_a' and 'field_b'. Find values in [source]. See migration documentation for details.
+}
+```
+
+**When to use:**
+- New v5 required fields don't exist in v4
+- Values must come from external sources (API, dashboard, user)
+- No reasonable default value exists
+- Field values are account/environment-specific
+
+**Integration test strategy:**
+- Expected output files include the warning comment
+- E2E tests simulate user adding fields from environment variables
+- Provider tests verify warning exists before manual intervention step
+
 ---
 
 ## Additional Resources

e2e/tf/v4/provider.tf

@@ -60,3 +60,29 @@ variable "crowdstrike_customer_id" {
   type        = string
   default     = ""
 }
+
+# BYO IP Prefix variables for testing
+# Set via TF_VAR_byo_ip_* environment variables or directly in terraform.tfvars
+variable "byo_ip_cidr" {
+  description = "BYO IP CIDR notation for the prefix"
+  type        = string
+  default     = "2606:54c2:2::/48"
+}
+
+variable "byo_ip_asn" {
+  description = "BYO IP ASN number"
+  type        = string
+  default     = "13335"
+}
+
+variable "byo_ip_loa_document_id" {
+  description = "BYO IP LOA document ID"
+  type        = string
+  default     = "a6061274b61449d3bb4521aee2e90c95"
+}
+
+variable "byo_ip_prefix_id" {
+  description = "BYO IP prefix ID (for v4 provider or migration tests)"
+  type        = string
+  default     = "b543f1a825f4474b88e945f164624412"
+}

integration/v4_to_v5/testdata/byo_ip_prefix/expected/byo_ip_prefix.tf

@@ -0,0 +1,233 @@
+# Comprehensive Integration Tests for byo_ip_prefix Migration (v4 → v5)
+# This file covers all v4 schema attributes and Terraform patterns
+# Target: 15-30+ resource instances
+
+# ============================================================================
+# PATTERN 1-2: Variables & Locals
+# ============================================================================
+
+variable "cloudflare_account_id" {
+  description = "Cloudflare account ID"
+  type        = string
+  # No default - must be provided
+}
+
+variable "cloudflare_zone_id" {
+  description = "Cloudflare zone ID"
+  type        = string
+  # No default - must be provided
+}
+
+variable "cloudflare_domain" {
+  description = "Cloudflare domain for testing"
+  type        = string
+}
+
+variable "prefix_base" {
+  description = "Base prefix ID for testing"
+  type        = string
+  default     = "cftftest"
+}
+
+variable "enable_optional" {
+  description = "Whether to create optional resources"
+  type        = bool
+  default     = true
+}
+
+variable "advertisement_status" {
+  description = "Advertisement status for prefixes"
+  type        = string
+  default     = "on"
+}
+
+locals {
+  name_prefix          = "cftftest"
+  environment          = "integration-test"
+  description_template = "BYO IP Prefix for ${local.environment}"
+
+  prefix_map = {
+    prod    = "cftftest-prod-001"
+    staging = "cftftest-staging-001"
+    dev     = "cftftest-dev-001"
+    test    = "cftftest-test-001"
+  }
+
+  prefix_list = [
+    "cftftest-list-001",
+    "cftftest-list-002",
+    "cftftest-list-003"
+  ]
+}
+
+# ============================================================================
+# PATTERN 1: Basic Resources (3 instances)
+# ============================================================================
+
+# Instance 1: Minimal resource (only required fields)
+resource "cloudflare_byo_ip_prefix" "minimal" {
+  account_id = var.cloudflare_account_id
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# Instance 2: Full resource with all optional fields
+resource "cloudflare_byo_ip_prefix" "full" {
+  account_id  = var.cloudflare_account_id
+  description = "Full BYO IP prefix with all fields"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# Instance 3: Resource with variables
+resource "cloudflare_byo_ip_prefix" "with_variables" {
+  account_id  = var.cloudflare_account_id
+  description = local.description_template
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# PATTERN 3: for_each with Maps (4 instances)
+# ============================================================================
+
+resource "cloudflare_byo_ip_prefix" "from_map" {
+  for_each = local.prefix_map
+
+  account_id  = var.cloudflare_account_id
+  description = "Prefix for ${each.key} environment"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# PATTERN 4: for_each with Sets (3 instances)
+# ============================================================================
+
+resource "cloudflare_byo_ip_prefix" "from_set" {
+  for_each = toset(local.prefix_list)
+
+  account_id  = var.cloudflare_account_id
+  description = "Prefix from set: ${each.value}"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# PATTERN 5: count-based Resources (3 instances)
+# ============================================================================
+
+resource "cloudflare_byo_ip_prefix" "with_count" {
+  count = 3
+
+  account_id  = var.cloudflare_account_id
+  description = "Prefix number ${count.index + 1}"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# PATTERN 6: Conditional Resource Creation (2 instances)
+# ============================================================================
+
+resource "cloudflare_byo_ip_prefix" "conditional" {
+  count = var.enable_optional ? 1 : 0
+
+  account_id  = var.cloudflare_account_id
+  description = "Conditional prefix"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+resource "cloudflare_byo_ip_prefix" "conditional_ternary" {
+  count = var.enable_optional ? 2 : 0
+
+  account_id  = var.cloudflare_account_id
+  description = var.enable_optional ? "Enabled prefix ${count.index}" : null
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# PATTERN 7: Cross-resource References (1 instance)
+# ============================================================================
+
+# Note: byo_ip_prefix is a standalone resource, so cross-references are limited
+# But we can reference other instances
+resource "cloudflare_byo_ip_prefix" "reference" {
+  account_id  = cloudflare_byo_ip_prefix.minimal.account_id
+  description = "References minimal: ${cloudflare_byo_ip_prefix.minimal.prefix_id}"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# PATTERN 8: Lifecycle Meta-arguments (2 instances)
+# ============================================================================
+
+resource "cloudflare_byo_ip_prefix" "with_lifecycle" {
+  account_id  = var.cloudflare_account_id
+  description = "Prefix with lifecycle rules"
+
+  lifecycle {
+    create_before_destroy = true
+    ignore_changes        = [description]
+  }
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+resource "cloudflare_byo_ip_prefix" "prevent_destroy" {
+  account_id  = var.cloudflare_account_id
+  description = "Protected prefix"
+
+  lifecycle {
+    prevent_destroy = true
+  }
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# PATTERN 9: Terraform Functions (3 instances)
+# ============================================================================
+
+resource "cloudflare_byo_ip_prefix" "with_join" {
+  account_id  = var.cloudflare_account_id
+  description = join(" - ", ["BYO IP", local.environment, "test"])
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+resource "cloudflare_byo_ip_prefix" "with_format" {
+  account_id  = var.cloudflare_account_id
+  description = format("Prefix for %s environment", local.environment)
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+resource "cloudflare_byo_ip_prefix" "with_interpolation" {
+  account_id  = var.cloudflare_account_id
+  description = "Prefix managed by ${local.name_prefix} for ${local.environment}"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# EDGE CASES (2 instances)
+# ============================================================================
+
+# Edge case 1: Empty string description (vs null)
+resource "cloudflare_byo_ip_prefix" "empty_description" {
+  account_id  = var.cloudflare_account_id
+  description = ""
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# Edge case 2: Advertisement off
+resource "cloudflare_byo_ip_prefix" "advertisement_off" {
+  account_id  = var.cloudflare_account_id
+  description = "Prefix with advertisement disabled"
+  # MIGRATION WARNING: This resource requires manual intervention to add v5 required fields 'asn' and 'cidr'. Find values in Cloudflare Dashboard → Manage Account → IP Addresses → IP Prefixes. See migration documentation for details.
+}
+
+# ============================================================================
+# INSTANCE COUNT SUMMARY
+# ============================================================================
+# Basic: 3
+# for_each maps: 4 (prod, staging, dev, test)
+# for_each sets: 3
+# count-based: 3
+# conditional: 3 (1 + 2 when enabled)
+# cross-reference: 1
+# lifecycle: 2
+# functions: 3
+# edge cases: 2
+# TOTAL: 24 instances (exceeds 15-30 target)
+# ============================================================================