Add nexthop parameter to cloudstack_static_route resource

This change adds support for the nexthop parameter in static routes,
which allows VPC-based routing without requiring a private gateway.

Resource Changes:
- Add nexthop and vpc_id optional parameters to schema
- nexthop is mutually exclusive with gateway_id
- When using nexthop, vpc_id is required
- When using gateway_id, nexthop and vpc_id are not allowed
- Update resource creation logic to support both routing methods:
  - Private Gateway routing (gateway_id)
  - VPC direct routing (nexthop + vpc_id)
- Update Read function to maintain plan stability for both modes

Test Coverage:
- Add comprehensive test coverage for both routing methods
- Add testAccPreCheckStaticRouteNexthop helper to check CloudStack version
- Automatically skip nexthop tests on CloudStack versions < 4.22.0
- Version check uses CloudStack capabilities API
- Tests are skipped (not failed) on older versions for backward compatibility
- All acceptance tests passing (2/2)

Documentation:
- Update documentation with examples for both routing methods
- Document mutual exclusivity requirements
- Note CloudStack 4.22+ requirement for nexthop support

CI/CD:
- Add CloudStack 4.22.0.0 to acceptance test matrix
- Ensures tests run on both old and new CloudStack versions

Author: bhouse-nexthop

.github/workflows/acceptance.yml

@@ -30,7 +30,7 @@ permissions:
 
 env:
   CLOUDSTACK_API_URL: http://localhost:8080/client/api
-  CLOUDSTACK_VERSIONS: "['4.19.0.1', '4.19.1.3', '4.19.2.0', '4.19.3.0', '4.20.1.0']"
+  CLOUDSTACK_VERSIONS: "['4.19.0.1', '4.19.1.3', '4.19.2.0', '4.19.3.0', '4.20.1.0', '4.22.0.0']"
 
 jobs:
   prepare-matrix:

cloudstack/provider_test.go

@@ -23,8 +23,11 @@ import (
 	"context"
 	"os"
 	"regexp"
+	"strconv"
+	"strings"
 	"testing"
 
+	"github.com/apache/cloudstack-go/v2/cloudstack"
 	"github.com/hashicorp/terraform-plugin-framework/providerserver"
 	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
 	"github.com/hashicorp/terraform-plugin-mux/tf5to6server"
@@ -145,3 +148,50 @@ func testAccPreCheck(t *testing.T) {
 		t.Fatal("CLOUDSTACK_SECRET_KEY must be set for acceptance tests")
 	}
 }
+
+// testAccPreCheckStaticRouteNexthop checks if the CloudStack version supports
+// the nexthop parameter for static routes (requires 4.22.0+)
+func testAccPreCheckStaticRouteNexthop(t *testing.T) {
+	testAccPreCheck(t)
+	cs := testAccProvider.Meta().(*cloudstack.CloudStackClient)
+
+	// Check the API capabilities to get CloudStack version
+	p := cs.Configuration.NewListCapabilitiesParams()
+	caps, err := cs.Configuration.ListCapabilities(p)
+	if err != nil {
+		t.Skipf("Unable to check CloudStack capabilities: %v", err)
+		return
+	}
+
+	// Check CloudStack version - nexthop support was added in 4.22.0
+	if caps != nil && caps.Capabilities != nil && caps.Capabilities.Cloudstackversion != "" {
+		version := caps.Capabilities.Cloudstackversion
+
+		// Parse version string (e.g., "4.22.0.0" -> major=4, minor=22)
+		// Convert to numeric value: major * 1000 + minor (e.g., 4.22 -> 4022)
+		parts := strings.Split(version, ".")
+		if len(parts) >= 2 {
+			major := 0
+			minor := 0
+
+			// Parse major version - extract first numeric part
+			majorStr := regexp.MustCompile(`^\d+`).FindString(parts[0])
+			if majorStr != "" {
+				major, _ = strconv.Atoi(majorStr)
+			}
+
+			// Parse minor version - extract first numeric part
+			minorStr := regexp.MustCompile(`^\d+`).FindString(parts[1])
+			if minorStr != "" {
+				minor, _ = strconv.Atoi(minorStr)
+			}
+
+			versionNum := major*1000 + minor
+			const minVersionNum = 4022 // 4.22.0
+
+			if versionNum < minVersionNum {
+				t.Skipf("Static route nexthop parameter not supported in CloudStack version %s (requires 4.22.0+)", version)
+			}
+		}
+	}
+}

cloudstack/resource_cloudstack_static_route.go

@@ -42,9 +42,26 @@ func resourceCloudStackStaticRoute() *schema.Resource {
 			},
 
 			"gateway_id": {
-				Type:     schema.TypeString,
-				Required: true,
-				ForceNew: true,
+				Type:          schema.TypeString,
+				Optional:      true,
+				ForceNew:      true,
+				ConflictsWith: []string{"nexthop", "vpc_id"},
+			},
+
+			"nexthop": {
+				Type:          schema.TypeString,
+				Optional:      true,
+				ForceNew:      true,
+				ConflictsWith: []string{"gateway_id"},
+				RequiredWith:  []string{"vpc_id"},
+			},
+
+			"vpc_id": {
+				Type:          schema.TypeString,
+				Optional:      true,
+				ForceNew:      true,
+				ConflictsWith: []string{"gateway_id"},
+				RequiredWith:  []string{"nexthop"},
 			},
 		},
 	}
@@ -58,11 +75,20 @@ func resourceCloudStackStaticRouteCreate(d *schema.ResourceData, meta interface{
 		d.Get("cidr").(string),
 	)
 
+	// Set either gateway_id or nexthop+vpc_id (they are mutually exclusive)
 	if v, ok := d.GetOk("gateway_id"); ok {
 		p.SetGatewayid(v.(string))
 	}
 
-	// Create the new private gateway
+	if v, ok := d.GetOk("nexthop"); ok {
+		p.SetNexthop(v.(string))
+	}
+
+	if v, ok := d.GetOk("vpc_id"); ok {
+		p.SetVpcid(v.(string))
+	}
+
+	// Create the new static route
 	r, err := cs.VPC.CreateStaticRoute(p)
 	if err != nil {
 		return fmt.Errorf("Error creating static route for %s: %s", d.Get("cidr").(string), err)
@@ -76,7 +102,7 @@ func resourceCloudStackStaticRouteCreate(d *schema.ResourceData, meta interface{
 func resourceCloudStackStaticRouteRead(d *schema.ResourceData, meta interface{}) error {
 	cs := meta.(*cloudstack.CloudStackClient)
 
-	// Get the virtual machine details
+	// Get the static route details
 	r, count, err := cs.VPC.GetStaticRouteByID(d.Id())
 	if err != nil {
 		if count == 0 {
@@ -90,6 +116,19 @@ func resourceCloudStackStaticRouteRead(d *schema.ResourceData, meta interface{})
 
 	d.Set("cidr", r.Cidr)
 
+	// Set gateway_id if it's not empty (indicates this route uses a gateway)
+	if r.Vpcgatewayid != "" {
+		d.Set("gateway_id", r.Vpcgatewayid)
+	}
+
+	// Set nexthop and vpc_id if nexthop is not empty (indicates this route uses nexthop)
+	if r.Nexthop != "" {
+		d.Set("nexthop", r.Nexthop)
+		if r.Vpcid != "" {
+			d.Set("vpc_id", r.Vpcid)
+		}
+	}
+
 	return nil
 }
 

cloudstack/resource_cloudstack_static_route_test.go

@@ -42,6 +42,32 @@ func TestAccCloudStackStaticRoute_basic(t *testing.T) {
 					testAccCheckCloudStackStaticRouteExists(
 						"cloudstack_static_route.foo", &staticroute),
 					testAccCheckCloudStackStaticRouteAttributes(&staticroute),
+					resource.TestCheckResourceAttr(
+						"cloudstack_static_route.foo", "cidr", "172.16.0.0/16"),
+				),
+			},
+		},
+	})
+}
+
+func TestAccCloudStackStaticRoute_nexthop(t *testing.T) {
+	var staticroute cloudstack.StaticRoute
+
+	resource.Test(t, resource.TestCase{
+		PreCheck:     func() { testAccPreCheckStaticRouteNexthop(t) },
+		Providers:    testAccProviders,
+		CheckDestroy: testAccCheckCloudStackStaticRouteDestroy,
+		Steps: []resource.TestStep{
+			{
+				Config: testAccCloudStackStaticRoute_nexthop,
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckCloudStackStaticRouteExists(
+						"cloudstack_static_route.bar", &staticroute),
+					testAccCheckCloudStackStaticRouteNexthopAttributes(&staticroute),
+					resource.TestCheckResourceAttr(
+						"cloudstack_static_route.bar", "cidr", "192.168.0.0/16"),
+					resource.TestCheckResourceAttr(
+						"cloudstack_static_route.bar", "nexthop", "10.1.1.1"),
 				),
 			},
 		},
@@ -89,6 +115,22 @@ func testAccCheckCloudStackStaticRouteAttributes(
 	}
 }
 
+func testAccCheckCloudStackStaticRouteNexthopAttributes(
+	staticroute *cloudstack.StaticRoute) resource.TestCheckFunc {
+	return func(s *terraform.State) error {
+
+		if staticroute.Cidr != "192.168.0.0/16" {
+			return fmt.Errorf("Bad CIDR: %s", staticroute.Cidr)
+		}
+
+		if staticroute.Nexthop != "10.1.1.1" {
+			return fmt.Errorf("Bad nexthop: %s", staticroute.Nexthop)
+		}
+
+		return nil
+	}
+}
+
 func testAccCheckCloudStackStaticRouteDestroy(s *terraform.State) error {
 	cs := testAccProvider.Meta().(*cloudstack.CloudStackClient)
 
@@ -136,3 +178,17 @@ resource "cloudstack_static_route" "foo" {
   cidr = "172.16.0.0/16"
   gateway_id = cloudstack_private_gateway.foo.id
 }`
+
+const testAccCloudStackStaticRoute_nexthop = `
+resource "cloudstack_vpc" "bar" {
+  name = "terraform-vpc-nexthop"
+  cidr = "10.0.0.0/8"
+  vpc_offering = "Default VPC offering"
+  zone = "Sandbox-simulator"
+}
+
+resource "cloudstack_static_route" "bar" {
+  cidr = "192.168.0.0/16"
+  nexthop = "10.1.1.1"
+  vpc_id = cloudstack_vpc.bar.id
+}`

website/docs/r/static_route.html.markdown

@@ -12,22 +12,43 @@ Creates a static route for the given private gateway or VPC.
 
 ## Example Usage
 
+Using a private gateway:
+
 ```hcl
 resource "cloudstack_static_route" "default" {
   cidr       = "10.0.0.0/16"
   gateway_id = "76f607e3-e8dc-4971-8831-b2a2b0cc4cb4"
 }
 ```
 
+Using a nexthop IP address:
+
+```hcl
+resource "cloudstack_static_route" "with_nexthop" {
+  cidr    = "10.0.0.0/16"
+  nexthop = "192.168.1.1"
+  vpc_id  = "76f607e3-e8dc-4971-8831-b2a2b0cc4cb4"
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported:
 
 * `cidr` - (Required) The CIDR for the static route. Changing this forces
     a new resource to be created.
 
-* `gateway_id` - (Required) The ID of the Private gateway. Changing this forces
-    a new resource to be created.
+* `gateway_id` - (Optional) The ID of the Private gateway. Changing this forces
+    a new resource to be created. Conflicts with `nexthop` and `vpc_id`.
+
+* `nexthop` - (Optional) The IP address of the nexthop for the static route.
+    Changing this forces a new resource to be created. Conflicts with `gateway_id`.
+    Must be used together with `vpc_id`.
+
+* `vpc_id` - (Optional) The ID of the VPC. Required when using `nexthop`.
+    Changing this forces a new resource to be created. Conflicts with `gateway_id`.
+
+**Note:** Either `gateway_id` or (`nexthop` + `vpc_id`) must be specified.
 
 ## Attributes Reference