builder: improve documentation on virtual_name

The `virtual_name` attribute for block devices did not have a clear
documentation, which led to confusion for users of the plugin.

This commit enhances this to clarify these are expected to have a
specific format, and are only for instance-based (ephemeral) volumes.

.web-docs/components/builder/chroot/README.md

@@ -500,8 +500,14 @@ https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concept
   [Throughput](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
   for more information
 
-- `virtual_name` (string) - The virtual device name. See the documentation on Block Device Mapping
+- `virtual_name` (string) - The virtual device name. See the documentation on
+  [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   for more information.
+
+  Note: virtual_name only applies for ephemeral (instance) volumes. Any
+  EBS-backed volume will have a `snapshot_id` instead.
+
+  The volume virtual_name should be in the `ephemeral[0-23]` form, e.g. ephemeral1
 
 - `volume_type` (string) - The volume type. gp2 & gp3 for General Purpose (SSD) volumes, io1 & io2
   for Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD,

.web-docs/components/builder/ebs/README.md

@@ -1362,8 +1362,14 @@ https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concept
   [Throughput](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
   for more information
 
-- `virtual_name` (string) - The virtual device name. See the documentation on Block Device Mapping
+- `virtual_name` (string) - The virtual device name. See the documentation on
+  [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   for more information.
+
+  Note: virtual_name only applies for ephemeral (instance) volumes. Any
+  EBS-backed volume will have a `snapshot_id` instead.
+
+  The volume virtual_name should be in the `ephemeral[0-23]` form, e.g. ephemeral1
 
 - `volume_type` (string) - The volume type. gp2 & gp3 for General Purpose (SSD) volumes, io1 & io2
   for Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD,

.web-docs/components/builder/ebssurrogate/README.md

@@ -1362,8 +1362,14 @@ https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concept
   [Throughput](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
   for more information
 
-- `virtual_name` (string) - The virtual device name. See the documentation on Block Device Mapping
+- `virtual_name` (string) - The virtual device name. See the documentation on
+  [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   for more information.
+
+  Note: virtual_name only applies for ephemeral (instance) volumes. Any
+  EBS-backed volume will have a `snapshot_id` instead.
+
+  The volume virtual_name should be in the `ephemeral[0-23]` form, e.g. ephemeral1
 
 - `volume_type` (string) - The volume type. gp2 & gp3 for General Purpose (SSD) volumes, io1 & io2
   for Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD,

.web-docs/components/builder/ebsvolume/README.md

@@ -392,8 +392,14 @@ https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concept
   [Throughput](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
   for more information
 
-- `virtual_name` (string) - The virtual device name. See the documentation on Block Device Mapping
+- `virtual_name` (string) - The virtual device name. See the documentation on
+  [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   for more information.
+
+  Note: virtual_name only applies for ephemeral (instance) volumes. Any
+  EBS-backed volume will have a `snapshot_id` instead.
+
+  The volume virtual_name should be in the `ephemeral[0-23]` form, e.g. ephemeral1
 
 - `volume_type` (string) - The volume type. gp2 & gp3 for General Purpose (SSD) volumes, io1 & io2
   for Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD,

.web-docs/components/builder/instance/README.md

@@ -1261,8 +1261,14 @@ https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concept
   [Throughput](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
   for more information
 
-- `virtual_name` (string) - The virtual device name. See the documentation on Block Device Mapping
+- `virtual_name` (string) - The virtual device name. See the documentation on
+  [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   for more information.
+
+  Note: virtual_name only applies for ephemeral (instance) volumes. Any
+  EBS-backed volume will have a `snapshot_id` instead.
+
+  The volume virtual_name should be in the `ephemeral[0-23]` form, e.g. ephemeral1
 
 - `volume_type` (string) - The volume type. gp2 & gp3 for General Purpose (SSD) volumes, io1 & io2
   for Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD,

builder/common/block_device.go

@@ -92,8 +92,14 @@ type BlockDevice struct {
 	// [Throughput](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
 	// for more information
 	Throughput *int64 `mapstructure:"throughput" required:"false"`
-	// The virtual device name. See the documentation on Block Device Mapping
+	// The virtual device name. See the documentation on
+	// [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
 	// for more information.
+	//
+	// Note: virtual_name only applies for ephemeral (instance) volumes. Any
+	// EBS-backed volume will have a `snapshot_id` instead.
+	//
+	// The volume virtual_name should be in the `ephemeral[0-23]` form, e.g. ephemeral1
 	VirtualName string `mapstructure:"virtual_name" required:"false"`
 	// The volume type. gp2 & gp3 for General Purpose (SSD) volumes, io1 & io2
 	// for Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD,

docs-partials/builder/common/BlockDevice-not-required.mdx

@@ -28,8 +28,14 @@
   [Throughput](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_EbsBlockDevice.html)
   for more information
 
-- `virtual_name` (string) - The virtual device name. See the documentation on Block Device Mapping
+- `virtual_name` (string) - The virtual device name. See the documentation on
+  [Block Device Mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html)
   for more information.
+
+  Note: virtual_name only applies for ephemeral (instance) volumes. Any
+  EBS-backed volume will have a `snapshot_id` instead.
+
+  The volume virtual_name should be in the `ephemeral[0-23]` form, e.g. ephemeral1
 
 - `volume_type` (string) - The volume type. gp2 & gp3 for General Purpose (SSD) volumes, io1 & io2
   for Provisioned IOPS (SSD) volumes, st1 for Throughput Optimized HDD,