Merge pull request #1029 from Juniper/1027-add-support-for-vn-descrip…

…tion-field-available-since-apstra-50

Add support for `description` field to Virtual Network resource and data sources

apstra/blueprint/datacenter_virtual_network.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"net"
+	"regexp"
 	"strconv"
 
 	"github.com/Juniper/apstra-go-sdk/apstra"
@@ -34,6 +35,7 @@ import (
 type DatacenterVirtualNetwork struct {
 	Id                      types.String `tfsdk:"id"`
 	Name                    types.String `tfsdk:"name"`
+	Description             types.String `tfsdk:"description"`
 	BlueprintId             types.String `tfsdk:"blueprint_id"`
 	Type                    types.String `tfsdk:"type"`
 	RoutingZoneId           types.String `tfsdk:"routing_zone_id"`
@@ -79,6 +81,10 @@ func (o DatacenterVirtualNetwork) DataSourceAttributes() map[string]dataSourceSc
 			Optional:            true,
 			Validators:          []validator.String{stringvalidator.LengthAtLeast(1)},
 		},
+		"description": dataSourceSchema.StringAttribute{
+			MarkdownDescription: "Virtual Network Description",
+			Computed:            true,
+		},
 		"type": dataSourceSchema.StringAttribute{
 			MarkdownDescription: "Virtual Network Type",
 			Computed:            true,
@@ -185,6 +191,10 @@ func (o DatacenterVirtualNetwork) DataSourceFilterAttributes() map[string]dataSo
 			MarkdownDescription: "Virtual Network Name",
 			Optional:            true,
 		},
+		"description": dataSourceSchema.StringAttribute{
+			MarkdownDescription: "Virtual Network Description",
+			Optional:            true,
+		},
 		"type": dataSourceSchema.StringAttribute{
 			MarkdownDescription: "Virtual Network Type",
 			Optional:            true,
@@ -298,6 +308,14 @@ func (o DatacenterVirtualNetwork) ResourceAttributes() map[string]resourceSchema
 				stringvalidator.RegexMatches(apstraregexp.AlphaNumW2HLConstraint, apstraregexp.AlphaNumW2HLConstraintMsg),
 			},
 		},
+		"description": resourceSchema.StringAttribute{
+			MarkdownDescription: "Virtual Network Description",
+			Optional:            true,
+			Validators: []validator.String{
+				stringvalidator.LengthBetween(1, 222),
+				stringvalidator.RegexMatches(regexp.MustCompile(`^[^"<>\\?]+$`), `must not contain the following characters: ", <, >, \, ?`),
+			},
+		},
 		"blueprint_id": resourceSchema.StringAttribute{
 			MarkdownDescription: "Blueprint ID",
 			Required:            true,
@@ -626,6 +644,7 @@ func (o *DatacenterVirtualNetwork) Request(ctx context.Context, diags *diag.Diag
 	}
 
 	return &apstra.VirtualNetworkData{
+		Description:               o.Description.ValueString(),
 		DhcpService:               apstra.DhcpServiceEnabled(o.DhcpServiceEnabled.ValueBool()),
 		Ipv4Enabled:               o.IPv4ConnectivityEnabled.ValueBool(),
 		Ipv4Subnet:                ipv4Subnet,
@@ -659,6 +678,7 @@ func (o *DatacenterVirtualNetwork) LoadApiData(ctx context.Context, in *apstra.V
 	}
 
 	o.Name = types.StringValue(in.Label)
+	o.Description = utils.StringValueOrNull(ctx, in.Description, diags)
 	o.Type = types.StringValue(in.VnType.String())
 	o.RoutingZoneId = types.StringValue(in.SecurityZoneId.String())
 	o.Bindings = newBindingMap(ctx, in.VnBindings, diags)
@@ -705,6 +725,13 @@ func (o *DatacenterVirtualNetwork) Query(resultName string) apstra.QEQuery {
 		})
 	}
 
+	if !o.Description.IsNull() {
+		nodeAttributes = append(nodeAttributes, apstra.QEEAttribute{
+			Key:   "description",
+			Value: apstra.QEStringVal(o.Description.ValueString()),
+		})
+	}
+
 	if !o.Type.IsNull() {
 		nodeAttributes = append(nodeAttributes, apstra.QEEAttribute{
 			Key:   "vn_type",
@@ -922,11 +949,7 @@ func (o DatacenterVirtualNetwork) ValidateConfigBindingsReservation(ctx context.
 func (o DatacenterVirtualNetwork) VersionConstraints() compatibility.ConfigConstraints {
 	var response compatibility.ConfigConstraints
 
-	if o.Bindings.IsUnknown() {
-		return response // cannot validate with unknown bindings
-	}
-
-	if len(o.Bindings.Elements()) == 0 {
+	if !o.Bindings.IsUnknown() && len(o.Bindings.Elements()) == 0 {
 		response.AddAttributeConstraints(
 			compatibility.AttributeConstraint{
 				Path:        path.Root("bindings"),
@@ -935,5 +958,14 @@ func (o DatacenterVirtualNetwork) VersionConstraints() compatibility.ConfigConst
 		)
 	}
 
+	if utils.HasValue(o.Description) {
+		response.AddAttributeConstraints(
+			compatibility.AttributeConstraint{
+				Path:        path.Root("description"),
+				Constraints: compatibility.VnDescriptionOk,
+			},
+		)
+	}
+
 	return response
 }

apstra/compatibility/constraints.go

@@ -12,5 +12,6 @@ var (
 	BpIbaWidgetOk                      = versionconstraints.New(apiversions.LtApstra500)
 	FabricSettingsSetInCreate          = versionconstraints.New(apiversions.GeApstra421)
 	TemplateRequiresAntiAffinityPolicy = versionconstraints.New(apiversions.Apstra420)
+	VnDescriptionOk                    = versionconstraints.New(">= 5.0.0")
 	VnEmptyBindingsOk                  = versionconstraints.New(">= 5.0.0")
 )

apstra/data_source_datacenter_virtual_networks.go

@@ -68,7 +68,7 @@ func (o *dataSourceDatacenterVirtualNetworks) Schema(_ context.Context, _ dataso
 						"name", "type", "routing_zone_id", "vni", "reserve_vlan", "dhcp_service_enabled",
 						"ipv4_connectivity_enabled", "ipv6_connectivity_enabled", "ipv4_subnet", "ipv6_subnet",
 						"ipv4_virtual_gateway_enabled", "ipv6_virtual_gateway_enabled", "ipv4_virtual_gateway",
-						"ipv6_virtual_gateway", "l3_mtu", "import_route_targets", "export_route_targets",
+						"ipv6_virtual_gateway", "l3_mtu", "import_route_targets", "export_route_targets", "description",
 					),
 				},
 				DeprecationMessage: "The `filter` attribute is deprecated and will be removed in a future " +
@@ -89,7 +89,7 @@ func (o *dataSourceDatacenterVirtualNetworks) Schema(_ context.Context, _ dataso
 							"name", "type", "routing_zone_id", "vni", "reserve_vlan", "dhcp_service_enabled",
 							"ipv4_connectivity_enabled", "ipv6_connectivity_enabled", "ipv4_subnet", "ipv6_subnet",
 							"ipv4_virtual_gateway_enabled", "ipv6_virtual_gateway_enabled", "ipv4_virtual_gateway",
-							"ipv6_virtual_gateway", "l3_mtu", "import_route_targets", "export_route_targets",
+							"ipv6_virtual_gateway", "l3_mtu", "import_route_targets", "export_route_targets", "description",
 						),
 					},
 				},

apstra/resource_datacenter_virtual_network_test.go

@@ -28,6 +28,7 @@ const (
 resource %q %q {
   blueprint_id    = %q
   name            = %q
+  description     = %s
   type            = %s
   vni             = %s
   routing_zone_id = %s
@@ -46,6 +47,7 @@ resource %q %q {
 type resourceDatacenterVirtualNetworkTemplate struct {
 	blueprintId   apstra.ObjectId
 	name          string
+	description   string
 	vnType        string
 	vni           *int
 	routingZoneId apstra.ObjectId
@@ -70,6 +72,7 @@ func (o resourceDatacenterVirtualNetworkTemplate) render(rType, rName string) st
 		rType, rName,
 		o.blueprintId,
 		o.name,
+		stringOrNull(o.description),
 		stringOrNull(o.vnType),
 		intPtrOrNull(o.vni),
 		stringOrNull(o.routingZoneId.String()),
@@ -533,6 +536,67 @@ func TestAccDatacenterVirtualNetwork(t *testing.T) {
 				},
 			},
 		},
+		"start_no_description": {
+			apiVersionConstraints: compatibility.VnDescriptionOk,
+			steps: []testStep{
+				{
+					config: resourceDatacenterVirtualNetworkTemplate{
+						blueprintId:   bp.Id(),
+						name:          acctest.RandString(6),
+						vnType:        enum.VnTypeVxlan.String(),
+						routingZoneId: szId,
+					},
+				},
+				{
+					config: resourceDatacenterVirtualNetworkTemplate{
+						blueprintId:   bp.Id(),
+						name:          acctest.RandString(6),
+						description:   acctest.RandString(6),
+						vnType:        enum.VnTypeVxlan.String(),
+						routingZoneId: szId,
+					},
+				},
+				{
+					config: resourceDatacenterVirtualNetworkTemplate{
+						blueprintId:   bp.Id(),
+						name:          acctest.RandString(6),
+						vnType:        enum.VnTypeVxlan.String(),
+						routingZoneId: szId,
+					},
+				},
+			},
+		},
+		"start_with_description": {
+			apiVersionConstraints: compatibility.VnDescriptionOk,
+			steps: []testStep{
+				{
+					config: resourceDatacenterVirtualNetworkTemplate{
+						blueprintId:   bp.Id(),
+						name:          acctest.RandString(6),
+						description:   acctest.RandString(6),
+						vnType:        enum.VnTypeVxlan.String(),
+						routingZoneId: szId,
+					},
+				},
+				{
+					config: resourceDatacenterVirtualNetworkTemplate{
+						blueprintId:   bp.Id(),
+						name:          acctest.RandString(6),
+						vnType:        enum.VnTypeVxlan.String(),
+						routingZoneId: szId,
+					},
+				},
+				{
+					config: resourceDatacenterVirtualNetworkTemplate{
+						blueprintId:   bp.Id(),
+						name:          acctest.RandString(6),
+						description:   acctest.RandString(6),
+						vnType:        enum.VnTypeVxlan.String(),
+						routingZoneId: szId,
+					},
+				},
+			},
+		},
 	}
 
 	resourceType := tfapstra.ResourceName(ctx, &tfapstra.ResourceDatacenterVirtualNetwork)

docs/data-sources/datacenter_virtual_network.md

@@ -43,6 +43,7 @@ locals {
 ### Read-Only
 
 - `bindings` (Attributes Map) Details availability of the virtual network on leaf and access switches (see [below for nested schema](#nestedatt--bindings))
+- `description` (String) Virtual Network Description
 - `dhcp_service_enabled` (Boolean) Enables a DHCP relay agent.
 - `export_route_targets` (Set of String) Export RTs for this Virtual Network.
 - `had_prior_vni_config` (Boolean) Not applicable in data source context. Ignore.

docs/data-sources/datacenter_virtual_networks.md

@@ -64,6 +64,7 @@ data "apstra_datacenter_virtual_networks" "prod_unreserved_with_dhcp" {
 
 Optional:
 
+- `description` (String) Virtual Network Description
 - `dhcp_service_enabled` (Boolean) Enables a DHCP relay agent.
 - `export_route_targets` (Set of String) This is a set of *required* export RTs, not an exact-match list.
 - `import_route_targets` (Set of String) This is a set of *required* import RTs, not an exact-match list.
@@ -99,6 +100,7 @@ Read-Only:
 
 Optional:
 
+- `description` (String) Virtual Network Description
 - `dhcp_service_enabled` (Boolean) Enables a DHCP relay agent.
 - `export_route_targets` (Set of String) This is a set of *required* export RTs, not an exact-match list.
 - `import_route_targets` (Set of String) This is a set of *required* import RTs, not an exact-match list.

docs/resources/datacenter_virtual_network.md

@@ -56,6 +56,7 @@ resource "apstra_datacenter_virtual_network" "test" {
 ### Optional
 
 - `bindings` (Attributes Map) Bindings make a Virtual Network available on Leaf Switches and Access Switches. At least one binding entry is required with Apstra 4.x. With Apstra 5.x, a Virtual Network with no bindings can be created by omitting (or setting `null`) this attribute. The value is a map keyed by graph db node IDs of *either* Leaf Switches (non-redundant Leaf Switches) or Leaf Switch redundancy groups (redundant Leaf Switches). Practitioners are encouraged to consider using the [`apstra_datacenter_virtual_network_binding_constructor`](../data-sources/datacenter_virtual_network_binding_constructor) data source to populate this map. (see [below for nested schema](#nestedatt--bindings))
+- `description` (String) Virtual Network Description
 - `dhcp_service_enabled` (Boolean) Enables a DHCP relay agent.
 - `export_route_targets` (Set of String) Export RTs for this Virtual Network.
 - `import_route_targets` (Set of String) Import RTs for this Virtual Network.

go.mod

@@ -8,7 +8,7 @@ toolchain go1.22.10
 
 require (
 	github.com/IBM/netaddr v1.5.0
-	github.com/Juniper/apstra-go-sdk v0.0.0-20250124235250-52db4d6290b0
+	github.com/Juniper/apstra-go-sdk v0.0.0-20250203165651-ba2625234414
 	github.com/chrismarget-j/go-licenses v0.0.0-20240224210557-f22f3e06d3d4
 	github.com/chrismarget-j/version-constraints v0.0.0-20240925155624-26771a0a6820
 	github.com/google/go-cmp v0.6.0

go.sum

@@ -6,8 +6,8 @@ github.com/BurntSushi/toml v1.4.0 h1:kuoIxZQy2WRRk1pttg9asf+WVv6tWQuBNVmK8+nqPr0
 github.com/BurntSushi/toml v1.4.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
 github.com/IBM/netaddr v1.5.0 h1:IJlFZe1+nFs09TeMB/HOP4+xBnX2iM/xgiDOgZgTJq0=
 github.com/IBM/netaddr v1.5.0/go.mod h1:DDBPeYgbFzoXHjSz9Jwk7K8wmWV4+a/Kv0LqRnb8we4=
-github.com/Juniper/apstra-go-sdk v0.0.0-20250124235250-52db4d6290b0 h1:pRBSM826e9srwLGVGPm0iWC1jzNhjty0foHeIihoI8w=
-github.com/Juniper/apstra-go-sdk v0.0.0-20250124235250-52db4d6290b0/go.mod h1:j0XhEo0IoltyST4cqdLwrDUNLDHC7JWJxBPDVffeSCg=
+github.com/Juniper/apstra-go-sdk v0.0.0-20250203165651-ba2625234414 h1:ILBPq9tKPYWo+p5PDuSX2OMLdRj85azEEPOBADPlrmo=
+github.com/Juniper/apstra-go-sdk v0.0.0-20250203165651-ba2625234414/go.mod h1:j0XhEo0IoltyST4cqdLwrDUNLDHC7JWJxBPDVffeSCg=
 github.com/Kunde21/markdownfmt/v3 v3.1.0 h1:KiZu9LKs+wFFBQKhrZJrFZwtLnCCWJahL+S+E/3VnM0=
 github.com/Kunde21/markdownfmt/v3 v3.1.0/go.mod h1:tPXN1RTyOzJwhfHoon9wUr4HGYmWgVxSQN6VBJDkrVc=
 github.com/Masterminds/goutils v1.1.1 h1:5nUrii3FMTL5diU80unEVvNevw1nH4+ZV4DSLVJLSYI=