Skip to content

docs: load docs from code #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
jooola wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: load docs from code #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 62 additions & 53 deletions .web-docs/components/builder/hcloud/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<!-- Code generated from the comments of the Config struct in builder/hcloud/config.go; DO NOT EDIT MANUALLY -->

- `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`.

<!-- End of code generated from the comments of the Config struct in builder/hcloud/config.go; -->

- `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`.
<!-- Code generated from the comments of the Config struct in builder/hcloud/config.go; DO NOT EDIT MANUALLY -->

- `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.

<!-- Code generated from the comments of the imageFilter struct in builder/hcloud/config.go; DO NOT EDIT MANUALLY -->

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`.
<!-- End of code generated from the comments of the imageFilter struct in builder/hcloud/config.go; -->

- `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.

<!-- Code generated from the comments of the SSHTemporaryKeyPair struct in communicator/config.go; DO NOT EDIT MANUALLY -->
- `ssh_keys` ([]string) - List of SSH keys names or IDs to be added to image on launch.

<!-- Code generated from the comments of the SSHTemporaryKeyPair struct in communicator/config.go; DO NOT EDIT MANUALLY -->

- `temporary_key_pair_type` (string) - `dsa` | `ecdsa` | `ed25519` | `rsa` ( the default )

Expand All @@ -115,15 +125,14 @@ builder.
<!-- End of code generated from the comments of the SSHTemporaryKeyPair struct in communicator/config.go; -->


- `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.
<!-- End of code generated from the comments of the Config struct in builder/hcloud/config.go; -->

- `networks` (array of integers) - List of Network IDs which should be
attached to the server private network interface at creation time.

## Basic Example

Expand Down
90 changes: 73 additions & 17 deletions builder/hcloud/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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) {
Expand Down
8 changes: 4 additions & 4 deletions builder/hcloud/config.hcl2spec.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

59 changes: 59 additions & 0 deletions docs-partials/builder/hcloud/Config-not-required.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<!-- Code generated from the comments of the Config struct in builder/hcloud/config.go; DO NOT EDIT MANUALLY -->

- `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`

<!-- End of code generated from the comments of the Config struct in builder/hcloud/config.go; -->
13 changes: 13 additions & 0 deletions docs-partials/builder/hcloud/Config-required.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<!-- Code generated from the comments of the Config struct in builder/hcloud/config.go; DO NOT EDIT MANUALLY -->

- `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`.

<!-- End of code generated from the comments of the Config struct in builder/hcloud/config.go; -->
11 changes: 11 additions & 0 deletions docs-partials/builder/hcloud/imageFilter-not-required.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<!-- Code generated from the comments of the imageFilter struct in builder/hcloud/config.go; DO NOT EDIT MANUALLY -->

- `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.

<!-- End of code generated from the comments of the imageFilter struct in builder/hcloud/config.go; -->
Loading