feat(cluster): add support for availability zones (#241)

Author: adambabik

internal/provider/cluster/cluster.go

@@ -3,6 +3,7 @@ package cluster
 import (
 	"context"
 	"fmt"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
@@ -39,7 +40,7 @@ func ResourceCluster() *schema.Resource {
 			Delete: schema.DefaultTimeout(clusterDeleteTimeout),
 		},
 
-		SchemaVersion: 2,
+		SchemaVersion: 3,
 
 		StateUpgraders: []schema.StateUpgrader{
 			{
@@ -52,6 +53,11 @@ func ResourceCluster() *schema.Resource {
 				Type:    resourceClusterV1().CoreConfigSchema().ImpliedType(),
 				Upgrade: resourceClusterUpgradeV1,
 			},
+			{
+				Version: 2,
+				Type:    resourceClusterV2().CoreConfigSchema().ImpliedType(),
+				Upgrade: resourceClusterUpgradeV2,
+			},
 		},
 
 		Schema: map[string]*schema.Schema{
@@ -189,6 +195,20 @@ func ResourceCluster() *schema.Resource {
 				Computed:    true,
 				Type:        schema.TypeInt,
 			},
+			"availability_zone_ids": {
+				Description: "List of Availability Zone IDs for the cluster nodes (e.g., " +
+					"'use1-az1', 'use1-az2', 'use1-az4' for AWS or 'us-central1-a', 'us-central1-b', " +
+					"'us-central1-c' for GCP). It is recommended to specify exactly 3 AZ IDs to " +
+					"ensure optimal distribution of nodes across availability zones. AZ IDs are " +
+					"consistent identifiers that map to the same physical availability zone across " +
+					"all accounts, unlike AZ names which may differ between accounts. If not " +
+					"specified, the server will automatically select availability zones.",
+				Optional: true,
+				Computed: true,
+				ForceNew: true,
+				Type:     schema.TypeSet,
+				Elem:     &schema.Schema{Type: schema.TypeString},
+			},
 		},
 	}
 }
@@ -269,6 +289,37 @@ func resourceClusterCreate(ctx context.Context, d *schema.ResourceData, meta int
 
 	clusterCreateRequest.InstanceID = mi.ID
 
+	// Handle availability zone IDs
+	if azIDs, ok := d.GetOk("availability_zone_ids"); ok {
+		// Figure out the cloud account ID; it's either BYOA or Scylla Account.
+		// There is a clear mapping from cloudProviderID to cloudAccountID.
+		cloudAccountID := clusterCreateRequest.AccountCredentialID
+		if cloudAccountID == 0 {
+			switch cloudProvider.CloudProvider.ID {
+			case 1: // AWS
+				cloudAccountID = 1
+			case 2: // GCP
+				cloudAccountID = 200
+			default:
+				return diag.Errorf("unknown cloud provider ID %d", cloudProvider.CloudProvider.ID)
+			}
+		}
+
+		azIDsSet := azIDs.(*schema.Set)
+
+		var azIDList []string
+		for _, v := range azIDsSet.List() {
+			azIDList = append(azIDList, v.(string))
+		}
+		slices.Sort(azIDList)
+
+		if err := validateAvailabilityZoneIDs(ctx, scyllaClient, cloudAccountID, mr.ID, azIDList); err != nil {
+			return diag.FromErr(err)
+		}
+
+		clusterCreateRequest.AvailabilityZoneIDs = azIDList
+	}
+
 	if !versionOK {
 		clusterCreateRequest.ScyllaVersionID = scyllaClient.Meta.ScyllaVersions.DefaultScyllaVersionID
 	} else if mv := scyllaClient.Meta.VersionByName(version.(string)); mv != nil {
@@ -291,6 +342,10 @@ func resourceClusterCreate(ctx context.Context, d *schema.ResourceData, meta int
 		return diag.Errorf("failed to read cluster %d: %s", cr.ClusterID, err)
 	}
 
+	if n := len(cluster.Datacenters); n != 1 {
+		return diag.Errorf("clusters without datacenter or multi-datacenter clusters are not currently supported (found %d datacenters)", n)
+	}
+
 	i := cloudProvider.InstanceByIDFromInstances(cluster.Datacenter.InstanceID, instances)
 	if i == nil {
 		return diag.Errorf("unexpected instance ID for cluster %d: %d", cluster.ID, cluster.Datacenter.InstanceID)
@@ -351,8 +406,8 @@ func resourceClusterRead(ctx context.Context, d *schema.ResourceData, meta inter
 		return diag.Errorf("unexpected cloud provider %d for cluster %d", cluster.CloudProviderID, cluster.ID)
 	}
 
-	if n := len(cluster.Datacenters); n > 1 {
-		return diag.Errorf("multi-datacenter clusters are not currently supported (found %d datacenters)", n)
+	if n := len(cluster.Datacenters); n != 1 {
+		return diag.Errorf("clusters without datacenter or multi-datacenter clusters are not currently supported (found %d datacenters)", n)
 	}
 
 	var instanceExternalID string
@@ -368,6 +423,7 @@ func resourceClusterRead(ctx context.Context, d *schema.ResourceData, meta inter
 		}
 		instanceExternalID = i.ExternalID
 	}
+
 	err = setClusterKVs(d, cluster, p.CloudProvider.Name, instanceExternalID)
 	if err != nil {
 		return diag.Errorf("failed to set cluster values for cluster %d: %s", cluster.ID, err)
@@ -424,6 +480,13 @@ func setClusterKVs(d *schema.ResourceData, cluster *model.Cluster, providerName,
 		_ = d.Set("node_disk_size", cluster.Instance.TotalStorage)
 	}
 
+	azIDs := cluster.Datacenter.AvailabilityZoneIDs()
+	if azIDs == nil {
+		// Prevent stale data in case the new value is empty or missing.
+		azIDs = []string{}
+	}
+	_ = d.Set("availability_zone_ids", azIDs)
+
 	return nil
 }
 
@@ -479,8 +542,8 @@ func resourceClusterUpdate(ctx context.Context, d *schema.ResourceData, meta int
 		return diag.Errorf("failed to get the cluster with ID %d: %s", clusterID, err)
 	}
 
-	if n := len(cluster.Datacenters); n > 1 {
-		return diag.Errorf("multi-datacenter clusters are not currently supported (found %d datacenters for cluster %d)", n, clusterID)
+	if n := len(cluster.Datacenters); n != 1 {
+		return diag.Errorf("clusters without datacenter or multi-datacenter clusters are not currently supported (found %d datacenters)", n)
 	}
 
 	// Resize will fail if there is any ongoing cluster request.
@@ -653,3 +716,54 @@ func parseClusterID(d *schema.ResourceData) (int64, diag.Diagnostics) {
 	}
 	return clusterID, nil
 }
+
+// validateAvailabilityZoneIDs validates that the provided AZ IDs are valid for the given region.
+// TODO: When placement groups are supported through the API, revisit the minimum AZ requirement
+// as single-AZ deployments may become valid with placement group configuration.
+func validateAvailabilityZoneIDs(ctx context.Context, c *scylla.Client, cloudAccountID, regionID int64, azIDs []string) error {
+	if l := len(azIDs); l < 2 || l > 3 {
+		return fmt.Errorf("at least 2 and at most 3 availability zone IDs are required, got %d", l)
+	}
+
+	// Check for duplicate AZ IDs.
+	seen := make(map[string]struct{}, len(azIDs))
+	var duplicates []string
+	for _, azID := range azIDs {
+		if _, ok := seen[azID]; ok {
+			duplicates = append(duplicates, azID)
+		} else {
+			seen[azID] = struct{}{}
+		}
+	}
+	if len(duplicates) > 0 {
+		return fmt.Errorf("duplicate availability zone IDs are not allowed: %v", duplicates)
+	}
+
+	// Validate available AZ IDs.
+	availableAZs, err := c.ListAvailabilityZoneIDs(ctx, cloudAccountID, regionID)
+	if err != nil {
+		return fmt.Errorf("failed to list availability zones for region: %w", err)
+	}
+
+	availableSet := make(map[string]struct{}, len(availableAZs))
+	for _, az := range availableAZs {
+		availableSet[az] = struct{}{}
+	}
+
+	var invalidAZs []string
+	for _, azID := range azIDs {
+		if _, ok := availableSet[azID]; !ok {
+			invalidAZs = append(invalidAZs, azID)
+		}
+	}
+
+	if len(invalidAZs) > 0 {
+		return fmt.Errorf(
+			"invalid availability zone IDs %v; available AZ IDs for this region are: %v",
+			invalidAZs,
+			availableAZs,
+		)
+	}
+
+	return nil
+}

internal/provider/cluster/cluster_v2.go

@@ -0,0 +1,141 @@
+package cluster
+
+import (
+	"context"
+
+	"github.com/hashicorp/go-cty/cty"
+	"github.com/hashicorp/terraform-plugin-sdk/v2/diag"
+	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
+)
+
+// resourceClusterV2 returns the schema for cluster resource version 2.
+// This version does not include the availability_zone_ids field.
+func resourceClusterV2() *schema.Resource {
+	return &schema.Resource{
+		Schema: map[string]*schema.Schema{
+			"cluster_id": {
+				Computed: true,
+				Type:     schema.TypeInt,
+			},
+			"cloud": {
+				Optional: true,
+				ForceNew: true,
+				Default:  "AWS",
+				Type:     schema.TypeString,
+			},
+			"name": {
+				Required: true,
+				ForceNew: true,
+				Type:     schema.TypeString,
+			},
+			"region": {
+				Required: true,
+				ForceNew: true,
+				Type:     schema.TypeString,
+			},
+			"node_count": {
+				Computed: true,
+				Type:     schema.TypeInt,
+			},
+			"min_nodes": {
+				Required: true,
+				Type:     schema.TypeInt,
+				ValidateDiagFunc: func(v interface{}, path cty.Path) diag.Diagnostics {
+					value := v.(int)
+					if value < 3 {
+						return diag.Errorf("min_nodes must be at least 3, got %d", value)
+					}
+					if value%3 != 0 {
+						return diag.Errorf("min_nodes must be divisible by 3, got %d", value)
+					}
+					return nil
+				},
+			},
+			"byoa_id": {
+				Optional: true,
+				ForceNew: true,
+				Type:     schema.TypeInt,
+			},
+			"user_api_interface": {
+				Optional: true,
+				ForceNew: true,
+				Type:     schema.TypeString,
+				Default:  "CQL",
+			},
+			"alternator_write_isolation": {
+				Optional: true,
+				ForceNew: true,
+				Type:     schema.TypeString,
+				Default:  "only_rmw_uses_lwt",
+			},
+			"node_type": {
+				Required: true,
+				ForceNew: true,
+				Type:     schema.TypeString,
+			},
+			"node_dns_names": {
+				Computed: true,
+				Type:     schema.TypeSet,
+				Elem:     schema.TypeString,
+				Set:      schema.HashString,
+			},
+			"node_private_ips": {
+				Computed: true,
+				Type:     schema.TypeSet,
+				Elem:     schema.TypeString,
+				Set:      schema.HashString,
+			},
+			"cidr_block": {
+				Optional: true,
+				Computed: true,
+				ForceNew: true,
+				Type:     schema.TypeString,
+			},
+			"scylla_version": {
+				Optional: true,
+				Computed: true,
+				ForceNew: true,
+				Type:     schema.TypeString,
+			},
+			"enable_vpc_peering": {
+				Optional: true,
+				ForceNew: true,
+				Type:     schema.TypeBool,
+				Default:  true,
+			},
+			"enable_dns": {
+				Optional: true,
+				ForceNew: true,
+				Type:     schema.TypeBool,
+				Default:  true,
+			},
+			"request_id": {
+				Computed: true,
+				Type:     schema.TypeInt,
+			},
+			"datacenter": {
+				Computed: true,
+				Type:     schema.TypeString,
+			},
+			"status": {
+				Computed: true,
+				Type:     schema.TypeString,
+			},
+			"node_disk_size": {
+				ForceNew: true,
+				Optional: true,
+				Computed: true,
+				Type:     schema.TypeInt,
+			},
+		},
+	}
+}
+
+// resourceClusterUpgradeV2 migrates state from version 2 to version 3.
+// This migration adds the availability_zone_ids field which will be
+// populated on the next read from the server.
+func resourceClusterUpgradeV2(_ context.Context, rawState map[string]any, _ any) (map[string]any, error) {
+	// availability_zone_ids is a new computed+optional field.
+	// No migration needed - the field will be populated on the next read.
+	return rawState, nil
+}