From 7c51c75bbf6fadc97f02bd42e7d86ed8f75f0b3b Mon Sep 17 00:00:00 2001 From: Zhiwei Liang <121905282+zliang-akamai@users.noreply.github.com> Date: Wed, 8 May 2024 22:05:04 -0400 Subject: [PATCH] Generate markdown docs from go in-line docs for builder (#227) --- .web-docs/components/builder/linode/README.md | 153 ++++++++++++------ .../components/data-source/image/README.md | 6 +- builder/linode/builder_test.go | 22 +-- builder/linode/config.go | 144 +++++++++++++---- builder/linode/config.hcl2spec.go | 14 +- docs/builders/linode.mdx | 95 ++--------- helper/common.go | 6 +- 7 files changed, 268 insertions(+), 172 deletions(-) diff --git a/.web-docs/components/builder/linode/README.md b/.web-docs/components/builder/linode/README.md index 8fe72fd8..c8915c16 100644 --- 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 + + +- `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. + + + + + +- `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`. + + -- `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. + + +- `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. + + #### Interface This section outlines the fields configurable for a single interface object. +##### Required Interface Common Attributes + + + - `purpose` (string) - The purpose of this interface. (public, vlan, vpc) + + + +##### Optional Interface Common Attributes + + + - `primary` (bool) - Whether this interface is a primary interface. -VLAN-specific fields: + + + +##### VLAN-specific Attributes + + - `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: + + + +##### VPC-specific Attributes + + + +- `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. + - - `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 + + + +- `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. + + + #### Metadata This section outlines the fields configurable for a single metadata object. + + - `user_data` (string) - Base64-encoded (cloud-config)[https://www.linode.com/docs/products/compute/compute-instances/guides/metadata-cloud-config/] data. + + + ## 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 index 90505b43..f96a3b62 100644 --- 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" { - `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. diff --git a/builder/linode/builder_test.go b/builder/linode/builder_test.go index 7c3a087d..c3621def 100644 --- 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"}, }, } diff --git a/builder/linode/config.go b/builder/linode/config.go index 39d2c1be..e9abcc31 100644 --- a/builder/linode/config.go +++ b/builder/linode/config.go @@ -1,3 +1,4 @@ +//go:generate packer-sdc struct-markdown //go:generate packer-sdc mapstructure-to-hcl2 -type Config,Interface,InterfaceIPv4,Metadata package linode @@ -20,22 +21,46 @@ import ( ) type InterfaceIPv4 struct { - VPC string `mapstructure:"vpc"` + // The IPv4 address from the VPC subnet to use for this interface. + VPC string `mapstructure:"vpc"` + + // The public IPv4 address assigned to this Linode to be 1:1 NATed with the VPC IPv4 address. NAT1To1 *string `mapstructure:"nat_1_1"` } type Metadata struct { + // Base64-encoded (cloud-config)[https://www.linode.com/docs/products/compute/compute-instances/guides/metadata-cloud-config/] data. UserData string `mapstructure:"user_data"` } +type VPCInterfaceAttributes struct { + // The ID of the VPC Subnet this interface references. + SubnetID *int `mapstructure:"subnet_id"` + + // The IPv4 configuration of this VPC interface. + IPv4 *InterfaceIPv4 `mapstructure:"ipv4"` + + // The IPv4 ranges of this VPC interface. + IPRanges []string `mapstructure:"ip_ranges"` +} + +type VLANInterfaceAttributes struct { + // The label of the VLAN this interface relates to. + Label string `mapstructure:"label"` + + // This Network Interface’s private IP address in CIDR notation. + IPAMAddress string `mapstructure:"ipam_address"` +} + type Interface struct { - Purpose string `mapstructure:"purpose"` - Label string `mapstructure:"label"` - IPAMAddress string `mapstructure:"ipam_address"` - Primary bool `mapstructure:"primary"` - SubnetID *int `mapstructure:"subnet_id"` - IPv4 *InterfaceIPv4 `mapstructure:"ipv4"` - IPRanges []string `mapstructure:"ip_ranges"` + VLANInterfaceAttributes `mapstructure:",squash"` + VPCInterfaceAttributes `mapstructure:",squash"` + + // The purpose of this interface. (public, vlan, vpc) + Purpose string `mapstructure:"purpose" required:"true"` + + // Whether this interface is a primary interface. + Primary bool `mapstructure:"primary"` } type Config struct { @@ -44,26 +69,89 @@ type Config struct { ctx interpolate.Context Comm communicator.Config `mapstructure:",squash"` - Interfaces []Interface `mapstructure:"interface" required:"false"` - Region string `mapstructure:"region"` - AuthorizedKeys []string `mapstructure:"authorized_keys" required:"false"` - AuthorizedUsers []string `mapstructure:"authorized_users" required:"false"` - InstanceType string `mapstructure:"instance_type"` - Label string `mapstructure:"instance_label" required:"false"` - Tags []string `mapstructure:"instance_tags" required:"false"` - Image string `mapstructure:"image"` - SwapSize int `mapstructure:"swap_size" required:"false"` - PrivateIP bool `mapstructure:"private_ip" required:"false"` - RootPass string `mapstructure:"root_pass" required:"false"` - ImageLabel string `mapstructure:"image_label" required:"false"` - Description string `mapstructure:"image_description" required:"false"` - StateTimeout time.Duration `mapstructure:"state_timeout" required:"false"` - StackScriptData map[string]string `mapstructure:"stackscript_data" required:"false"` - StackScriptID int `mapstructure:"stackscript_id" required:"false"` - ImageCreateTimeout time.Duration `mapstructure:"image_create_timeout" required:"false"` - CloudInit bool `mapstructure:"cloud_init" required:"false"` - Metadata Metadata `mapstructure:"metadata" required:"false"` - FirewallID int `mapstructure:"firewall_id" required:"false"` + // Network Interfaces to add to this Linode’s Configuration Profile. Singular repeatable + // block containing a `purpose`, a `label`, and an `ipam_address` field. + Interfaces []Interface `mapstructure:"interface" required:"false"` + + // 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`. + Region string `mapstructure:"region" required:"true"` + + // Public SSH keys need to be appended to the Linode instance. + AuthorizedKeys []string `mapstructure:"authorized_keys" required:"false"` + + // Users whose SSH keys need to be appended to the Linode instance. + AuthorizedUsers []string `mapstructure:"authorized_users" required:"false"` + + // 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`. + InstanceType string `mapstructure:"instance_type" required:"true"` + + // The name assigned to the Linode Instance. + Label string `mapstructure:"instance_label" required:"false"` + + // Tags to apply to the instance when it is created. + Tags []string `mapstructure:"instance_tags" required:"false"` + + // 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`. + Image string `mapstructure:"image" required:"true"` + + // The disk size (MiB) allocated for swap space. + SwapSize int `mapstructure:"swap_size" required:"false"` + + // If true, the created Linode will have private networking enabled and assigned + // a private IPv4 address. + PrivateIP bool `mapstructure:"private_ip" required:"false"` + + // 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. + RootPass string `mapstructure:"root_pass" required:"false"` + + // 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). + ImageLabel string `mapstructure:"image_label" required:"false"` + + // The description of the resulting image that will appear in your account. Defaults to "". + Description string `mapstructure:"image_description" required:"false"` + + // 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". + StateTimeout time.Duration `mapstructure:"state_timeout" required:"false"` + + // 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. + StackScriptData map[string]string `mapstructure:"stackscript_data" required:"false"` + + // 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. + StackScriptID int `mapstructure:"stackscript_id" required:"false"` + + // 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". + ImageCreateTimeout time.Duration `mapstructure:"image_create_timeout" required:"false"` + + // Whether the newly created image supports cloud-init. + CloudInit bool `mapstructure:"cloud_init" required:"false"` + + // An object containing user-defined data relevant to the creation of Linodes. + Metadata Metadata `mapstructure:"metadata" required:"false"` + + // The ID of the Firewall to attach this Linode to upon creation. + FirewallID int `mapstructure:"firewall_id" required:"false"` } func createRandomRootPassword() (string, error) { diff --git a/builder/linode/config.hcl2spec.go b/builder/linode/config.hcl2spec.go index 20585bc1..63a97488 100644 --- a/builder/linode/config.hcl2spec.go +++ b/builder/linode/config.hcl2spec.go @@ -69,13 +69,13 @@ type FlatConfig struct { WinRMInsecure *bool `mapstructure:"winrm_insecure" cty:"winrm_insecure" hcl:"winrm_insecure"` WinRMUseNTLM *bool `mapstructure:"winrm_use_ntlm" cty:"winrm_use_ntlm" hcl:"winrm_use_ntlm"` Interfaces []FlatInterface `mapstructure:"interface" required:"false" cty:"interface" hcl:"interface"` - Region *string `mapstructure:"region" cty:"region" hcl:"region"` + Region *string `mapstructure:"region" required:"true" cty:"region" hcl:"region"` AuthorizedKeys []string `mapstructure:"authorized_keys" required:"false" cty:"authorized_keys" hcl:"authorized_keys"` AuthorizedUsers []string `mapstructure:"authorized_users" required:"false" cty:"authorized_users" hcl:"authorized_users"` - InstanceType *string `mapstructure:"instance_type" cty:"instance_type" hcl:"instance_type"` + InstanceType *string `mapstructure:"instance_type" required:"true" cty:"instance_type" hcl:"instance_type"` Label *string `mapstructure:"instance_label" required:"false" cty:"instance_label" hcl:"instance_label"` Tags []string `mapstructure:"instance_tags" required:"false" cty:"instance_tags" hcl:"instance_tags"` - Image *string `mapstructure:"image" cty:"image" hcl:"image"` + Image *string `mapstructure:"image" required:"true" cty:"image" hcl:"image"` SwapSize *int `mapstructure:"swap_size" required:"false" cty:"swap_size" hcl:"swap_size"` PrivateIP *bool `mapstructure:"private_ip" required:"false" cty:"private_ip" hcl:"private_ip"` RootPass *string `mapstructure:"root_pass" required:"false" cty:"root_pass" hcl:"root_pass"` @@ -187,13 +187,13 @@ func (*FlatConfig) HCL2Spec() map[string]hcldec.Spec { // FlatInterface is an auto-generated flat version of Interface. // Where the contents of a field with a `mapstructure:,squash` tag are bubbled up. type FlatInterface struct { - Purpose *string `mapstructure:"purpose" cty:"purpose" hcl:"purpose"` Label *string `mapstructure:"label" cty:"label" hcl:"label"` IPAMAddress *string `mapstructure:"ipam_address" cty:"ipam_address" hcl:"ipam_address"` - Primary *bool `mapstructure:"primary" cty:"primary" hcl:"primary"` SubnetID *int `mapstructure:"subnet_id" cty:"subnet_id" hcl:"subnet_id"` IPv4 *FlatInterfaceIPv4 `mapstructure:"ipv4" cty:"ipv4" hcl:"ipv4"` IPRanges []string `mapstructure:"ip_ranges" cty:"ip_ranges" hcl:"ip_ranges"` + Purpose *string `mapstructure:"purpose" required:"true" cty:"purpose" hcl:"purpose"` + Primary *bool `mapstructure:"primary" cty:"primary" hcl:"primary"` } // FlatMapstructure returns a new FlatInterface. @@ -208,13 +208,13 @@ func (*Interface) FlatMapstructure() interface{ HCL2Spec() map[string]hcldec.Spe // The decoded values from this spec will then be applied to a FlatInterface. func (*FlatInterface) HCL2Spec() map[string]hcldec.Spec { s := map[string]hcldec.Spec{ - "purpose": &hcldec.AttrSpec{Name: "purpose", Type: cty.String, Required: false}, "label": &hcldec.AttrSpec{Name: "label", Type: cty.String, Required: false}, "ipam_address": &hcldec.AttrSpec{Name: "ipam_address", Type: cty.String, Required: false}, - "primary": &hcldec.AttrSpec{Name: "primary", Type: cty.Bool, Required: false}, "subnet_id": &hcldec.AttrSpec{Name: "subnet_id", Type: cty.Number, Required: false}, "ipv4": &hcldec.BlockSpec{TypeName: "ipv4", Nested: hcldec.ObjectSpec((*FlatInterfaceIPv4)(nil).HCL2Spec())}, "ip_ranges": &hcldec.AttrSpec{Name: "ip_ranges", Type: cty.List(cty.String), Required: false}, + "purpose": &hcldec.AttrSpec{Name: "purpose", Type: cty.String, Required: false}, + "primary": &hcldec.AttrSpec{Name: "primary", Type: cty.Bool, Required: false}, } return s } diff --git a/docs/builders/linode.mdx b/docs/builders/linode.mdx index 4c2d2a8a..07c00390 100644 --- a/docs/builders/linode.mdx +++ b/docs/builders/linode.mdx @@ -42,103 +42,42 @@ 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 - can reduce the risk of the token being leaked from the codebase. - -- `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`. - -- `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`. - -- `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`. +@include 'helper/LinodeCommon-not-required.mdx' +@include 'builder/linode/Config-required.mdx' ### Optional -- `authorized_keys` (list) - Public SSH keys need to be appended to the Linode instance. - -- `authorized_users` (list) - 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. - -- `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. - -- `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 "". - -- `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". - -- `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". - -- `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. - -- `cloud_init` (bool) - Whether the newly created image supports cloud-init. - -- `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. +@include 'builder/linode/Config-not-required.mdx' #### Interface This section outlines the fields configurable for a single interface object. -- `purpose` (string) - The purpose of this interface. (public, vlan, vpc) +##### Required Interface Common Attributes -- `primary` (bool) - Whether this interface is a primary interface. +@include 'builder/linode/Interface-required.mdx' -VLAN-specific fields: +##### Optional Interface Common Attributes -- `label` (string) - The label of the VLAN this interface relates to. +@include 'builder/linode/Interface-not-required.mdx' -- `ipam_address` (string) - This Network Interface’s private IP address in CIDR notation. +##### VLAN-specific Attributes -VPC-specific fields: +@include 'builder/linode/VLANInterfaceAttributes-not-required.mdx' -- `subnet_id` (int) - The ID of the VPC Subnet this interface references. +##### VPC-specific Attributes -- `ipv4` (block) - The IPv4 configuration of this VPC interface. +@include 'builder/linode/VPCInterfaceAttributes-not-required.mdx' - - `vpc` (string) - The IPv4 address from the VPC subnet to use for this interface. +###### VPC Interface IPv4 configuration object - - `nat_1_1` (string) - The public IPv4 address assigned to this Linode to be 1:1 NATed with the VPC IPv4 address. +@include 'builder/linode/InterfaceIPv4-not-required.mdx' #### Metadata This section outlines the fields configurable for a single metadata object. -- `user_data` (string) - Base64-encoded (cloud-config)[https://www.linode.com/docs/products/compute/compute-instances/guides/metadata-cloud-config/] data. +@include 'builder/linode/Metadata-not-required.mdx' ## Examples @@ -162,7 +101,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" } @@ -181,7 +120,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}}", @@ -214,7 +153,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/helper/common.go b/helper/common.go index bbc13db0..13dfa3e6 100644 --- a/helper/common.go +++ b/helper/common.go @@ -4,6 +4,10 @@ package helper // The common configuration options related to Linode services type LinodeCommon struct { // 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. PersonalAccessToken string `mapstructure:"linode_token"` }