Generate markdown docs from go in-line docs for builder (#227)

linode · May 9, 2024 · 7c51c75 · 7c51c75
1 parent d061dd8
commit 7c51c75
Show file tree

Hide file tree

Showing 7 changed files with 268 additions and 172 deletions.
diff --git a/.web-docs/components/builder/linode/README.md b/.web-docs/components/builder/linode/README.md
@@ -36,104 +36,161 @@ can also be supplied to override the typical auto-generated key:
 
 ### Required
 
-- `linode_token` (string) - The client TOKEN to use to access your account.
-  Alternatively, you can set your token as an environment variable named
-  `LINODE_TOKEN`. Saving the token in the environment or centralized vaults
+<!-- Code generated from the comments of the LinodeCommon struct in helper/common.go; DO NOT EDIT MANUALLY -->
+
+- `linode_token` (string) - The Linode API token required for provision Linode resources.
+  This can also be specified in `LINODE_TOKEN` environment variable.
+  Saving the token in the environment or centralized vaults
   can reduce the risk of the token being leaked from the codebase.
+  `images:read_write`, `linodes:read_write`, and `events:read_only`
+  scopes are required for the API token.
+
+<!-- End of code generated from the comments of the LinodeCommon struct in helper/common.go; -->
+
+<!-- Code generated from the comments of the Config struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
+
+- `region` (string) - The id of the region to launch the Linode instance in. Images are available in all
+  regions, but there will be less delay when deploying from the region where the image
+  was taken. See [regions](https://api.linode.com/v4/regions) for more information on
+  the available regions. Examples are `us-east`, `us-central`, `us-west`, `ap-south`,
+  `ca-east`, `ap-northeast`, `eu-central`, and `eu-west`.
 
-- `image` (string) - An Image ID to deploy the Disk from. Official Linode
-  Images start with `linode/`, while user Images start with `private/`. See
-  [images](https://api.linode.com/v4/images) for more information on the
-  Images available for use. Examples are `linode/debian9`, `linode/fedora28`,
-  `linode/ubuntu18.04`, `linode/arch`, and `private/12345`.
+- `instance_type` (string) - The Linode type defines the pricing, CPU, disk, and RAM specs of the instance. See
+  [instance types](https://api.linode.com/v4/linode/types) for more information on the
+  available Linode instance types. Examples are `g6-nanode-1`, `g6-standard-2`,
+  `g6-highmem-16`, and `g6-dedicated-16`.
 
-- `region` (string) - The id of the region to launch the Linode instance in.
-  Images are available in all regions, but there will be less delay when
-  deploying from the region where the image was taken. See
-  [regions](https://api.linode.com/v4/regions) for more information on the
-  available regions. Examples are `us-east`, `us-central`, `us-west`,
-  `ap-south`, `ca-east`, `ap-northeast`, `eu-central`, and `eu-west`.
+- `image` (string) - An Image ID to deploy the Disk from. Official Linode Images start with `linode/`,
+  while user Images start with `private/`. See [images](https://api.linode.com/v4/images)
+  for more information on the Images available for use. Examples are `linode/debian9`,
+  `linode/fedora28`, `linode/ubuntu18.04`, `linode/arch`, and `private/12345`.
+
+<!-- End of code generated from the comments of the Config struct in builder/linode/config.go; -->
 
-- `instance_type` (string) - The Linode type defines the pricing, CPU, disk,
-  and RAM specs of the instance. See [instance types](https://api.linode.com/v4/linode/types)
-  for more information on the available Linode instance types. Examples are `g6-nanode-1`,
-  `g6-standard-2`, `g6-highmem-16`, and `g6-dedicated-16`.
 
 ### Optional
 
-- `authorized_keys` (list) - Public SSH keys need to be appended to the Linode instance.
+<!-- Code generated from the comments of the Config struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
+
+- `interface` ([]Interface) - Network Interfaces to add to this Linode’s Configuration Profile. Singular repeatable
+  block containing a `purpose`, a `label`, and an `ipam_address` field.
 
-- `authorized_users` (list) - Users whose SSH keys need to be appended to the Linode instance.
+- `authorized_keys` ([]string) - Public SSH keys need to be appended to the Linode instance.
+
+- `authorized_users` ([]string) - Users whose SSH keys need to be appended to the Linode instance.
 
 - `instance_label` (string) - The name assigned to the Linode Instance.
 
-- `instance_tags` (list) - Tags to apply to the instance when it is created.
+- `instance_tags` ([]string) - Tags to apply to the instance when it is created.
 
 - `swap_size` (int) - The disk size (MiB) allocated for swap space.
 
-- `interface` ([](Interface)[#interface]) - Network Interfaces
-  to add to this Linode’s Configuration Profile. Singular repeatable block containing a `purpose`,
-  a `label`, and an `ipam_address` field.
+- `private_ip` (bool) - If true, the created Linode will have private networking enabled and assigned
+  a private IPv4 address.
+
+- `root_pass` (string) - The root password of the Linode instance for building the image. Please note that when
+  you create a new Linode instance with a private image, you will be required to setup a
+  new root password.
 
 - `image_label` (string) - The name of the resulting image that will appear
   in your account. Defaults to `packer-{{timestamp}}` (see [configuration
   templates](/packer/docs/templates/legacy_json_templates/engine) for more info).
 
-- `image_description` (string) - The description of the resulting image that
-  will appear in your account. Defaults to "".
+- `image_description` (string) - The description of the resulting image that will appear in your account. Defaults to "".
 
-- `state_timeout` (string) - The time to wait, as a duration string, for the
-  Linode instance to enter a desired state (such as "running") before timing
-  out. The default state timeout is "5m".
+- `state_timeout` (duration string | ex: "1h5m2s") - The time to wait, as a duration string, for the Linode instance to enter a desired state
+  (such as "running") before timing out. The default state timeout is "5m".
 
-- `image_create_timeout` (string) - The time to wait, as a duration string, for the
-  disk image to be created successfully before timing out.
-  The default image creation timeout is "10m".
+- `stackscript_data` (map[string]string) - This attribute is required only if the StackScript being deployed requires input data from
+  the User for successful completion. See User Defined Fields (UDFs) for more details.
+
+  This attribute is required to be valid JSON.
 
-- `private_ip` (bool) - If true, the created Linode will have private networking
-  enabled and assigned a private IPv4 address.
+- `stackscript_id` (int) - A StackScript ID that will cause the referenced StackScript to be run during deployment
+  of this Linode. A compatible image is required to use a StackScript. To get a list of
+  available StackScript and their permitted Images see /stackscripts. This field cannot
+  be used when deploying from a Backup or a Private Image.
 
-- `root_pass` (string) - The root password of the Linode instance for building the image.
-  Please note that when you create a new Linode instance with a private image, you will
-  be required to setup a new root password.
+- `image_create_timeout` (duration string | ex: "1h5m2s") - The time to wait, as a duration string, for the disk image to be created successfully
+  before timing out. The default image creation timeout is "10m".
 
 - `cloud_init` (bool) - Whether the newly created image supports cloud-init.
 
+- `metadata` (Metadata) - An object containing user-defined data relevant to the creation of Linodes.
+
 - `firewall_id` (int) - The ID of the Firewall to attach this Linode to upon creation.
 
-- `metadata` ((Metadata)[#metadata]) - An object containing user-defined data relevant
-  to the creation of Linodes.
+<!-- End of code generated from the comments of the Config struct in builder/linode/config.go; -->
+
 
 #### Interface
 
 This section outlines the fields configurable for a single interface object.
 
+##### Required Interface Common Attributes
+
+<!-- Code generated from the comments of the Interface struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
+
 - `purpose` (string) - The purpose of this interface. (public, vlan, vpc)
 
+<!-- End of code generated from the comments of the Interface struct in builder/linode/config.go; -->
+
+
+##### Optional Interface Common Attributes
+
+<!-- Code generated from the comments of the Interface struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
+
 - `primary` (bool) - Whether this interface is a primary interface.
 
-VLAN-specific fields:
+<!-- End of code generated from the comments of the Interface struct in builder/linode/config.go; -->
+
+
+##### VLAN-specific Attributes
+
+<!-- Code generated from the comments of the VLANInterfaceAttributes struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
 
 - `label` (string) - The label of the VLAN this interface relates to.
 
 - `ipam_address` (string) - This Network Interface’s private IP address in CIDR notation.
 
-VPC-specific fields:
+<!-- End of code generated from the comments of the VLANInterfaceAttributes struct in builder/linode/config.go; -->
+
+
+##### VPC-specific Attributes
+
+<!-- Code generated from the comments of the VPCInterfaceAttributes struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
+
+- `subnet_id` (\*int) - The ID of the VPC Subnet this interface references.
+
+- `ipv4` (\*InterfaceIPv4) - The IPv4 configuration of this VPC interface.
 
-- `subnet_id` (int) - The ID of the VPC Subnet this interface references.
+- `ip_ranges` ([]string) - The IPv4 ranges of this VPC interface.
 
-- `ipv4` (block) - The IPv4 configuration of this VPC interface.
+<!-- End of code generated from the comments of the VPCInterfaceAttributes struct in builder/linode/config.go; -->
 
-    - `vpc` (string) - The IPv4 address from the VPC subnet to use for this interface.
 
-    - `nat_1_1` (string) - The public IPv4 address assigned to this Linode to be 1:1 NATed with the VPC IPv4 address.
+###### VPC Interface IPv4 configuration object
+
+<!-- Code generated from the comments of the InterfaceIPv4 struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
+
+- `vpc` (string) - The IPv4 address from the VPC subnet to use for this interface.
+
+- `nat_1_1` (\*string) - The public IPv4 address assigned to this Linode to be 1:1 NATed with the VPC IPv4 address.
+
+<!-- End of code generated from the comments of the InterfaceIPv4 struct in builder/linode/config.go; -->
+
 
 #### Metadata
 
 This section outlines the fields configurable for a single metadata object.
 
+<!-- Code generated from the comments of the Metadata struct in builder/linode/config.go; DO NOT EDIT MANUALLY -->
+
 - `user_data` (string) - Base64-encoded (cloud-config)[https://www.linode.com/docs/products/compute/compute-instances/guides/metadata-cloud-config/] data.
 
+<!-- End of code generated from the comments of the Metadata struct in builder/linode/config.go; -->
+
+
 ## Examples
 
 ### Basic Example
@@ -156,7 +213,7 @@ source "linode" "example" {
   instance_label    = "temporary-linode-${local.timestamp}"
   instance_type     = "g6-nanode-1"
   linode_token      = "YOUR API TOKEN"
-  region            = "us-east"
+  region            = "us-mia"
   ssh_username      = "root"
 }
 
@@ -175,7 +232,7 @@ build {
       "example": {
         "image": "linode/debian11",
         "linode_token": "YOUR API TOKEN",
-        "region": "us-east",
+        "region": "us-mia",
         "instance_type": "g6-nanode-1",
         "instance_label": "temporary-linode-{{timestamp}}",
         "image_label": "private-image-{{timestamp}}",
@@ -208,7 +265,7 @@ source "linode" "example" {
   instance_label    = "temporary-linode-${local.timestamp}"
   instance_type     = "g6-nanode-1"
   linode_token      = "YOUR API TOKEN"
-  region            = "us-east"
+  region            = "us-mia"
   ssh_username      = "root"
   private_ip        = true
   firewall_id       = 12345

diff --git a/.web-docs/components/data-source/image/README.md b/.web-docs/components/data-source/image/README.md
@@ -63,7 +63,11 @@ data "linode-image" "ubuntu22_lts" {
 <!-- Code generated from the comments of the LinodeCommon struct in helper/common.go; DO NOT EDIT MANUALLY -->
 
 - `linode_token` (string) - The Linode API token required for provision Linode resources.
-  This can also be specified in LINODE_TOKEN environment variable.
+  This can also be specified in `LINODE_TOKEN` environment variable.
+  Saving the token in the environment or centralized vaults
+  can reduce the risk of the token being leaked from the codebase.
+  `images:read_write`, `linodes:read_write`, and `events:read_only`
+  scopes are required for the API token.
 
 <!-- End of code generated from the comments of the LinodeCommon struct in helper/common.go; -->
 

diff --git a/builder/linode/builder_test.go b/builder/linode/builder_test.go
@@ -479,18 +479,22 @@ func TestBuilderPrepare_NetworkInterfaces(t *testing.T) {
 			Primary: true,
 		},
 		{
-			Purpose:     "vlan",
-			Label:       "vlan-1",
-			IPAMAddress: "10.0.0.1/24",
+			Purpose: "vlan",
+			VLANInterfaceAttributes: VLANInterfaceAttributes{
+				Label:       "vlan-1",
+				IPAMAddress: "10.0.0.1/24",
+			},
 		},
 		{
-			Purpose:  "vpc",
-			SubnetID: &subnetID,
-			IPv4: &InterfaceIPv4{
-				VPC:     "10.0.0.2",
-				NAT1To1: &anyStr,
+			Purpose: "vpc",
+			VPCInterfaceAttributes: VPCInterfaceAttributes{
+				SubnetID: &subnetID,
+				IPRanges: []string{"10.0.0.3/32"},
+				IPv4: &InterfaceIPv4{
+					VPC:     "10.0.0.2",
+					NAT1To1: &anyStr,
+				},
 			},
-			IPRanges: []string{"10.0.0.3/32"},
 		},
 	}