Guide: Migrating to Provider v3.0.0

Migrating to Provider v3.0.0

This guide covers the migration from F5XC Terraform provider v2.x to v3.0.0. Version 3.0.0 introduces significant improvements to the provider’s API specification foundation, bringing enhanced documentation, better categorization, and improved example generation.

Overview

Provider v3.0.0 represents a major upgrade to the underlying API specification infrastructure:

Aspect	v2.x	v3.0.0
API Specs	269 individual files	38 domain-organized files
Categories	Pattern-based	API-defined (`x-f5xc-category`)
Subscription Info	Static metadata	API-defined (`x-f5xc-requires-tier`)
Examples	Hardcoded	API-enriched (`x-f5xc-example`)
Descriptions	Schema-only	Multi-level descriptions

What’s New

Improved Resource Categorization

Resources are now categorized based on official F5 API metadata rather than pattern matching. This provides more accurate Terraform Registry navigation:

Security: WAF, DDoS protection, certificates, blindfold encryption
Networking: DNS, CDN, network policies, rate limiting
Infrastructure: Sites, service mesh, cloud infrastructure
Platform: Tenants, identity, authentication, billing
Operations: Observability, statistics, support
AI Services: AI-powered features (preview)

Enhanced Documentation

Documentation now includes:

Subscription badges: Clear indication when Advanced subscription is required
Preview notices: Warning when features are in preview/beta status
Improved descriptions: Enriched descriptions from API metadata
Better examples: API-sourced example values for attributes

Specification Foundation

The provider now uses enriched API specifications that include:

x-f5xc-category: Official resource categorization
x-f5xc-requires-tier: Subscription tier requirements
x-f5xc-complexity: Resource complexity indicators
x-f5xc-is-preview: Preview/beta feature flags
x-f5xc-example: Enriched example values

Migration Steps

Step 1: Update Provider Version

Update your Terraform configuration to use v3.0.0:

terraform {
  required_providers {
    f5xc = {
      source  = "robinmordasiewicz/f5xc"
      version = "~> 3.0"
    }
  }
}

Step 2: Run Terraform Plan

After updating, run terraform plan to verify your configuration:

terraform init -upgrade
terraform plan

Step 3: Review Any Warnings

Version 3.0.0 may display new warnings about:

Subscription requirements: Resources now clearly indicate when Advanced subscription is needed
Preview features: Some features may be marked as preview with potential for change
Deprecations: Any deprecated attributes will be clearly documented

Breaking Changes

Version 3.0.0 maintains backward compatibility with v2.x configurations. However, be aware of:

Documentation Changes

Resource subcategories in the Terraform Registry may change due to improved categorization
Example configurations may be updated to reflect API-enriched values

Potential State Changes

No state migration is required. Your existing Terraform state files will continue to work without modification.

Compatibility Matrix

Terraform Version	Provider v3.0.0
1.8.0+	Supported
1.7.x	Supported
1.6.x	Supported
1.5.x	Supported
< 1.5.0	Not supported

Troubleshooting

Issue: “Subscription Required” Warning

If you see a subscription warning for a resource you’re using:

Verify your F5 Distributed Cloud subscription tier
Contact F5 support if you believe the warning is incorrect
Check the resource documentation for subscription requirements

Issue: Changes Detected After Upgrade

If terraform plan shows changes after upgrading:

Review the changes carefully - they may be improvements to default values
The changes are typically cosmetic (descriptions, examples)
Run terraform apply to update the state if changes are acceptable

Issue: Resource Category Changed

If you have automation relying on resource subcategories:

Update your automation to use the new category names
The new categories align with official F5 API organization

Getting Help

Documentation: Provider Documentation
Issues: GitHub Issues
F5 Support: F5 Distributed Cloud Console