diff --git a/.web-docs/components/builder/hcloud/README.md b/.web-docs/components/builder/hcloud/README.md index bc163d30..68e98a6e 100644 --- a/.web-docs/components/builder/hcloud/README.md +++ b/.web-docs/components/builder/hcloud/README.md @@ -22,75 +22,85 @@ builder. ### Required Builder Configuration options: -- `token` (string) - The client TOKEN to use to access your account. It can - also be specified via environment variable `HCLOUD_TOKEN`, if set. + -- `image` (string) - ID or name of image to launch server from. Alternatively - you can use `image_filter`. +- `token` (string) - Configures the client token used for authentication. It can also be specified + with the `HCLOUD_TOKEN` environment variable. -- `location` (string) - The name of the location to launch the server in. +- `location` (string) - Name of the location where to create the server. + +- `server_type` (string) - ID or name of the server type used to create the server. + +- `image` (string) - ID or name of image to launch server from. Alternatively you can use + `image_filter`. + + -- `server_type` (string) - ID or name of the server type this server should - be created with. ### Optional: -- `endpoint` (string) - Non standard api endpoint URL. Set this if you are - using a Hetzner Cloud API compatible service. It can also be specified via - environment variable `HCLOUD_ENDPOINT`. + + +- `endpoint` (string) - Configures the client endpoint. It can also be specified with the + `HCLOUD_ENDPOINT` environment variable. -- `image_filter` (object) - Filters used to populate the `filter` - field. Example: +- `poll_interval` (duration string | ex: "1h5m2s") - Configures the interval at which the API is polled by the client. Default + `500ms`. Increase this interval if you run into rate limiting errors. +- `server_name` (string) - Name assigned to the server. Hetzner Cloud sets the hostname of the server to + this value. + +- `upgrade_server_type` (string) - ID or name of the server type the server should be upgraded to, without changing + the disk size. This improves building performance and the resulting snapshot is + compatible with smaller server types and disk sizes. + +- `image_filter` (\*imageFilter) - Filters used to populate the `image` field. You may set this in place of `image`, + but not both. + + This selects the most recent image with the label `name==my-image`: + ```hcl image_filter { most_recent = true with_selector = ["name==my-image"] } ``` + + NOTE: This will fail unless _exactly_ one image is returned. In the above + example, `most_recent` will cause this to succeed by selecting the newest image. + + - This selects the most recent image with the label `name==my-image`. NOTE: - This will fail unless _exactly_ one AMI is returned. In the above example, - `most_recent` will cause this to succeed by selecting the newest image. - - - `with_selector` (list of strings) - label selectors used to select an - `image`. NOTE: This will fail unless _exactly_ one image is returned. - Check the official hcloud docs on - [Label Selectors](https://docs.hetzner.cloud/#overview-label-selector) - for more info. - - - `most_recent` (boolean) - Selects the newest created image when true. - This is most useful if you base your image on another Packer build image. - - You may set this in place of `image`, but not both. +- `with_selector` ([]string) - Label selectors used to select an `image`. See the [Label Selectors + docs](https://docs.hetzner.cloud/#label-selector) for more info. + + NOTE: This will fail unless _exactly_ one image is returned. -- `server_name` (string) - The name assigned to the server. The Hetzner Cloud - sets the hostname of the machine to this value. +- `most_recent` (bool) - Selects the newest created image when true. This is useful if you base your image + on another Packer build image. -- `snapshot_name` (string) - The name of the resulting snapshot that will - appear in your account as image description. Defaults to `packer-{{timestamp}}` (see - [configuration templates](/packer/docs/templates/legacy_json_templates/engine) for more info). - The snapshot_name must be unique per architecture. - If you want to reference the image as a sample in your terraform configuration please use the image id or the `snapshot_labels`. + -- `snapshot_labels` (map of key/value strings) - Key/value pair labels to - apply to the created image. -- `poll_interval` (string) - Configures the interval in which actions are - polled by the client. Default `500ms`. Increase this interval if you run - into rate limiting errors. +- `snapshot_name` (string) - Name of the resulting snapshot that will appear in your project as image + description. Defaults to `packer-{{timestamp}}` (see [configuration + templates](/packer/docs/templates/legacy_json_templates/engine) for more info). + The `snapshot_name` must be unique per architecture. If you want to reference the + image as a sample in your terraform configuration please use the image id or the + `snapshot_labels`. -- `user_data` (string) - User data to launch with the server. Packer will not - automatically wait for a user script to finish before shutting down the - instance this must be handled in a provisioner. +- `snapshot_labels` (map[string]string) - Key/value pair labels to apply to the created image. -- `user_data_file` (string) - Path to a file that will be used for the user - data when launching the server. +- `user_data` (string) - User data to launch the server with. Packer will not automatically wait for a + user script to finish before shutting down the instance this must be handled in a + provisioner. -- `ssh_keys` (array of strings) - List of SSH keys by name or id to be added - to image on launch. +- `user_data_file` (string) - Path to a file that will be used for the user data when launching the server. See + the `user_data` field. - +- `ssh_keys` ([]string) - List of SSH keys names or IDs to be added to image on launch. + + - `temporary_key_pair_type` (string) - `dsa` | `ecdsa` | `ed25519` | `rsa` ( the default ) @@ -115,15 +125,14 @@ builder. -- `rescue` (string) - Enable and boot in to the specified rescue system. This - enables simple installation of custom operating systems. `linux64` or `linux32` +- `networks` ([]int64) - List of Network IDs to attach to the server private network interface at creation + time. + +- `rescue` (string) - Enable and boot in to the specified rescue system. This enables simple + installation of custom operating systems. `linux64` or `linux32` -- `upgrade_server_type` (string) - ID or name of the server type this server should - be upgraded to, without changing the disk size. Improves building performance. - The resulting snapshot is compatible with smaller server types and disk sizes. + -- `networks` (array of integers) - List of Network IDs which should be - attached to the server private network interface at creation time. ## Basic Example diff --git a/builder/hcloud/config.go b/builder/hcloud/config.go index e195934e..8ecab453 100644 --- a/builder/hcloud/config.go +++ b/builder/hcloud/config.go @@ -1,6 +1,7 @@ // Copyright (c) HashiCorp, Inc. // SPDX-License-Identifier: MPL-2.0 +//go:generate packer-sdc struct-markdown //go:generate packer-sdc mapstructure-to-hcl2 -type Config,imageFilter package hcloud @@ -27,33 +28,88 @@ type Config struct { common.PackerConfig `mapstructure:",squash"` Comm communicator.Config `mapstructure:",squash"` - HCloudToken string `mapstructure:"token"` - Endpoint string `mapstructure:"endpoint"` - + // Configures the client token used for authentication. It can also be specified + // with the `HCLOUD_TOKEN` environment variable. + HCloudToken string `mapstructure:"token" required:"true"` + // Configures the client endpoint. It can also be specified with the + // `HCLOUD_ENDPOINT` environment variable. + Endpoint string `mapstructure:"endpoint"` + // Configures the interval at which the API is polled by the client. Default + // `500ms`. Increase this interval if you run into rate limiting errors. PollInterval time.Duration `mapstructure:"poll_interval"` - ServerName string `mapstructure:"server_name"` - Location string `mapstructure:"location"` - ServerType string `mapstructure:"server_type"` - UpgradeServerType string `mapstructure:"upgrade_server_type"` - Image string `mapstructure:"image"` - ImageFilter *imageFilter `mapstructure:"image_filter"` - - SnapshotName string `mapstructure:"snapshot_name"` + // Name assigned to the server. Hetzner Cloud sets the hostname of the server to + // this value. + ServerName string `mapstructure:"server_name"` + // Name of the location where to create the server. + Location string `mapstructure:"location" required:"true"` + // ID or name of the server type used to create the server. + ServerType string `mapstructure:"server_type" required:"true"` + // ID or name of the server type the server should be upgraded to, without changing + // the disk size. This improves building performance and the resulting snapshot is + // compatible with smaller server types and disk sizes. + UpgradeServerType string `mapstructure:"upgrade_server_type"` + + // ID or name of image to launch server from. Alternatively you can use + // `image_filter`. + Image string `mapstructure:"image" required:"true"` + // Filters used to populate the `image` field. You may set this in place of `image`, + // but not both. + // + // This selects the most recent image with the label `name==my-image`: + // + // ```hcl + // image_filter { + // most_recent = true + // with_selector = ["name==my-image"] + // } + // ``` + // + // NOTE: This will fail unless _exactly_ one image is returned. In the above + // example, `most_recent` will cause this to succeed by selecting the newest image. + // + // @include 'builder/hcloud/imageFilter-not-required.mdx' + ImageFilter *imageFilter `mapstructure:"image_filter"` + + // Name of the resulting snapshot that will appear in your project as image + // description. Defaults to `packer-{{timestamp}}` (see [configuration + // templates](/packer/docs/templates/legacy_json_templates/engine) for more info). + // The `snapshot_name` must be unique per architecture. If you want to reference the + // image as a sample in your terraform configuration please use the image id or the + // `snapshot_labels`. + SnapshotName string `mapstructure:"snapshot_name"` + // Key/value pair labels to apply to the created image. SnapshotLabels map[string]string `mapstructure:"snapshot_labels"` - UserData string `mapstructure:"user_data"` - UserDataFile string `mapstructure:"user_data_file"` - SSHKeys []string `mapstructure:"ssh_keys"` - Networks []int64 `mapstructure:"networks"` - + // User data to launch the server with. Packer will not automatically wait for a + // user script to finish before shutting down the instance this must be handled in a + // provisioner. + UserData string `mapstructure:"user_data"` + // Path to a file that will be used for the user data when launching the server. See + // the `user_data` field. + UserDataFile string `mapstructure:"user_data_file"` + // List of SSH keys names or IDs to be added to image on launch. + // + // @include 'packer-plugin-sdk/communicator/SSHTemporaryKeyPair-not-required.mdx' + SSHKeys []string `mapstructure:"ssh_keys"` + // List of Network IDs to attach to the server private network interface at creation + // time. + Networks []int64 `mapstructure:"networks"` + // Enable and boot in to the specified rescue system. This enables simple + // installation of custom operating systems. `linux64` or `linux32` RescueMode string `mapstructure:"rescue"` ctx interpolate.Context } type imageFilter struct { + // Label selectors used to select an `image`. See the [Label Selectors + // docs](https://docs.hetzner.cloud/#label-selector) for more info. + // + // NOTE: This will fail unless _exactly_ one image is returned. WithSelector []string `mapstructure:"with_selector"` - MostRecent bool `mapstructure:"most_recent"` + // Selects the newest created image when true. This is useful if you base your image + // on another Packer build image. + MostRecent bool `mapstructure:"most_recent"` } func (c *Config) Prepare(raws ...interface{}) ([]string, error) { diff --git a/builder/hcloud/config.hcl2spec.go b/builder/hcloud/config.hcl2spec.go index 3c2f4d9d..64e410dd 100644 --- a/builder/hcloud/config.hcl2spec.go +++ b/builder/hcloud/config.hcl2spec.go @@ -67,14 +67,14 @@ type FlatConfig struct { WinRMUseSSL *bool `mapstructure:"winrm_use_ssl" cty:"winrm_use_ssl" hcl:"winrm_use_ssl"` 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"` - HCloudToken *string `mapstructure:"token" cty:"token" hcl:"token"` + HCloudToken *string `mapstructure:"token" required:"true" cty:"token" hcl:"token"` Endpoint *string `mapstructure:"endpoint" cty:"endpoint" hcl:"endpoint"` PollInterval *string `mapstructure:"poll_interval" cty:"poll_interval" hcl:"poll_interval"` ServerName *string `mapstructure:"server_name" cty:"server_name" hcl:"server_name"` - Location *string `mapstructure:"location" cty:"location" hcl:"location"` - ServerType *string `mapstructure:"server_type" cty:"server_type" hcl:"server_type"` + Location *string `mapstructure:"location" required:"true" cty:"location" hcl:"location"` + ServerType *string `mapstructure:"server_type" required:"true" cty:"server_type" hcl:"server_type"` UpgradeServerType *string `mapstructure:"upgrade_server_type" cty:"upgrade_server_type" hcl:"upgrade_server_type"` - Image *string `mapstructure:"image" cty:"image" hcl:"image"` + Image *string `mapstructure:"image" required:"true" cty:"image" hcl:"image"` ImageFilter *FlatimageFilter `mapstructure:"image_filter" cty:"image_filter" hcl:"image_filter"` SnapshotName *string `mapstructure:"snapshot_name" cty:"snapshot_name" hcl:"snapshot_name"` SnapshotLabels map[string]string `mapstructure:"snapshot_labels" cty:"snapshot_labels" hcl:"snapshot_labels"` diff --git a/docs-partials/builder/hcloud/Config-not-required.mdx b/docs-partials/builder/hcloud/Config-not-required.mdx new file mode 100644 index 00000000..c35e3916 --- /dev/null +++ b/docs-partials/builder/hcloud/Config-not-required.mdx @@ -0,0 +1,59 @@ + + +- `endpoint` (string) - Configures the client endpoint. It can also be specified with the + `HCLOUD_ENDPOINT` environment variable. + +- `poll_interval` (duration string | ex: "1h5m2s") - Configures the interval at which the API is polled by the client. Default + `500ms`. Increase this interval if you run into rate limiting errors. + +- `server_name` (string) - Name assigned to the server. Hetzner Cloud sets the hostname of the server to + this value. + +- `upgrade_server_type` (string) - ID or name of the server type the server should be upgraded to, without changing + the disk size. This improves building performance and the resulting snapshot is + compatible with smaller server types and disk sizes. + +- `image_filter` (\*imageFilter) - Filters used to populate the `image` field. You may set this in place of `image`, + but not both. + + This selects the most recent image with the label `name==my-image`: + + ```hcl + image_filter { + most_recent = true + with_selector = ["name==my-image"] + } + ``` + + NOTE: This will fail unless _exactly_ one image is returned. In the above + example, `most_recent` will cause this to succeed by selecting the newest image. + + @include 'builder/hcloud/imageFilter-not-required.mdx' + +- `snapshot_name` (string) - Name of the resulting snapshot that will appear in your project as image + description. Defaults to `packer-{{timestamp}}` (see [configuration + templates](/packer/docs/templates/legacy_json_templates/engine) for more info). + The `snapshot_name` must be unique per architecture. If you want to reference the + image as a sample in your terraform configuration please use the image id or the + `snapshot_labels`. + +- `snapshot_labels` (map[string]string) - Key/value pair labels to apply to the created image. + +- `user_data` (string) - User data to launch the server with. Packer will not automatically wait for a + user script to finish before shutting down the instance this must be handled in a + provisioner. + +- `user_data_file` (string) - Path to a file that will be used for the user data when launching the server. See + the `user_data` field. + +- `ssh_keys` ([]string) - List of SSH keys names or IDs to be added to image on launch. + + @include 'packer-plugin-sdk/communicator/SSHTemporaryKeyPair-not-required.mdx' + +- `networks` ([]int64) - List of Network IDs to attach to the server private network interface at creation + time. + +- `rescue` (string) - Enable and boot in to the specified rescue system. This enables simple + installation of custom operating systems. `linux64` or `linux32` + + diff --git a/docs-partials/builder/hcloud/Config-required.mdx b/docs-partials/builder/hcloud/Config-required.mdx new file mode 100644 index 00000000..9490d798 --- /dev/null +++ b/docs-partials/builder/hcloud/Config-required.mdx @@ -0,0 +1,13 @@ + + +- `token` (string) - Configures the client token used for authentication. It can also be specified + with the `HCLOUD_TOKEN` environment variable. + +- `location` (string) - Name of the location where to create the server. + +- `server_type` (string) - ID or name of the server type used to create the server. + +- `image` (string) - ID or name of image to launch server from. Alternatively you can use + `image_filter`. + + diff --git a/docs-partials/builder/hcloud/imageFilter-not-required.mdx b/docs-partials/builder/hcloud/imageFilter-not-required.mdx new file mode 100644 index 00000000..90ec168d --- /dev/null +++ b/docs-partials/builder/hcloud/imageFilter-not-required.mdx @@ -0,0 +1,11 @@ + + +- `with_selector` ([]string) - Label selectors used to select an `image`. See the [Label Selectors + docs](https://docs.hetzner.cloud/#label-selector) for more info. + + NOTE: This will fail unless _exactly_ one image is returned. + +- `most_recent` (bool) - Selects the newest created image when true. This is useful if you base your image + on another Packer build image. + + diff --git a/docs/builders/hcloud.mdx b/docs/builders/hcloud.mdx index 45d99f35..9d203f87 100644 --- a/docs/builders/hcloud.mdx +++ b/docs/builders/hcloud.mdx @@ -35,85 +35,11 @@ builder. ### Required Builder Configuration options: -- `token` (string) - The client TOKEN to use to access your account. It can - also be specified via environment variable `HCLOUD_TOKEN`, if set. - -- `image` (string) - ID or name of image to launch server from. Alternatively - you can use `image_filter`. - -- `location` (string) - The name of the location to launch the server in. - -- `server_type` (string) - ID or name of the server type this server should - be created with. +@include 'builder/hcloud/Config-required.mdx' ### Optional: -- `endpoint` (string) - Non standard api endpoint URL. Set this if you are - using a Hetzner Cloud API compatible service. It can also be specified via - environment variable `HCLOUD_ENDPOINT`. - -- `image_filter` (object) - Filters used to populate the `filter` - field. Example: - - ```hcl - image_filter { - most_recent = true - with_selector = ["name==my-image"] - } - ``` - - This selects the most recent image with the label `name==my-image`. NOTE: - This will fail unless _exactly_ one AMI is returned. In the above example, - `most_recent` will cause this to succeed by selecting the newest image. - - - `with_selector` (list of strings) - label selectors used to select an - `image`. NOTE: This will fail unless _exactly_ one image is returned. - Check the official hcloud docs on - [Label Selectors](https://docs.hetzner.cloud/#overview-label-selector) - for more info. - - - `most_recent` (boolean) - Selects the newest created image when true. - This is most useful if you base your image on another Packer build image. - - You may set this in place of `image`, but not both. - -- `server_name` (string) - The name assigned to the server. The Hetzner Cloud - sets the hostname of the machine to this value. - -- `snapshot_name` (string) - The name of the resulting snapshot that will - appear in your account as image description. Defaults to `packer-{{timestamp}}` (see - [configuration templates](/packer/docs/templates/legacy_json_templates/engine) for more info). - The snapshot_name must be unique per architecture. - If you want to reference the image as a sample in your terraform configuration please use the image id or the `snapshot_labels`. - -- `snapshot_labels` (map of key/value strings) - Key/value pair labels to - apply to the created image. - -- `poll_interval` (string) - Configures the interval in which actions are - polled by the client. Default `500ms`. Increase this interval if you run - into rate limiting errors. - -- `user_data` (string) - User data to launch with the server. Packer will not - automatically wait for a user script to finish before shutting down the - instance this must be handled in a provisioner. - -- `user_data_file` (string) - Path to a file that will be used for the user - data when launching the server. - -- `ssh_keys` (array of strings) - List of SSH keys by name or id to be added - to image on launch. - -@include 'packer-plugin-sdk/communicator/SSHTemporaryKeyPair-not-required.mdx' - -- `rescue` (string) - Enable and boot in to the specified rescue system. This - enables simple installation of custom operating systems. `linux64` or `linux32` - -- `upgrade_server_type` (string) - ID or name of the server type this server should - be upgraded to, without changing the disk size. Improves building performance. - The resulting snapshot is compatible with smaller server types and disk sizes. - -- `networks` (array of integers) - List of Network IDs which should be - attached to the server private network interface at creation time. +@include 'builder/hcloud/Config-not-required.mdx' ## Basic Example