docs: refresh the documentation (#197)

- Update some broken links,
- Split examples into multiple directories,
- Link examples folder in the builder documentation,
- Add tips for keeping images size small.

.github/workflows/test.yml

@@ -68,7 +68,7 @@ jobs:
 
     defaults:
       run:
-        working-directory: example
+        working-directory: example/basic
 
     env:
       PACKER_LOG: "1"
@@ -82,6 +82,6 @@ jobs:
         with:
           version: 1.11.0 # renovate: datasource=github-releases depName=hashicorp/packer extractVersion=v(?<version>.+)
 
-      - run: packer init build.pkr.hcl
-      - run: packer validate build.pkr.hcl
-      - run: packer build build.pkr.hcl
+      - run: packer init .
+      - run: packer validate .
+      - run: packer build .

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

@@ -2,19 +2,22 @@ Type: `hcloud`
 Artifact BuilderId: `hcloud.builder`
 
 The `hcloud` Packer builder is able to create new images for use with [Hetzner
-Cloud](https://www.hetzner.cloud). The builder takes a source image, runs any
+Cloud](https://www.hetzner.com/cloud/). The builder takes a source image, runs any
 provisioning necessary on the image after launching it, then snapshots it into
 a reusable image. This reusable image can then be used as the foundation of new
 servers that are launched within the Hetzner Cloud.
 
 The builder does _not_ manage images. Once it creates an image, it is up to you
 to use it or delete it.
 
+## Connection to the server
+
 The builder will connect to the server using the first available IP, in the following order:
 
-- `public_ipv4`
-- `public_ipv6`
-- `private_ipv4`
+- `public_ipv4`: If enabled, the public IPv4 will be used,
+- `public_ipv6`: If enabled, the public IPv6 will be used,
+- `private_ipv4`: If the server is attached to private networks, the private IPv4 of the
+  first private network will be used.
 
 ## Configuration Reference
 
@@ -62,7 +65,7 @@ builder.
   - `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)
+    [Label Selectors](https://docs.hetzner.cloud/#label-selector)
     for more info.
 
   - `most_recent` (boolean) - Selects the newest created image when true.
@@ -165,3 +168,70 @@ build {
   sources  = ["source.hcloud.basic_example"]
 }
 ```
+
+See the [examples](https://github.com/hetznercloud/packer-plugin-hcloud/tree/main/example) folder in the Packer project for more examples.
+
+## Tips
+
+### Keeping the images size small
+
+To reduce the size of your images, we recommend cleaning up any temporary files that
+were added during the build process and discard the unused blocks from the disk.
+
+Below are a few commands that might useful:
+
+- Clean and reset could-init files:
+
+  ```bash
+  cloud-init clean --logs --machine-id --seed --configs all
+
+  rm -rf /run/cloud-init/*
+  rm -rf /var/lib/cloud/*
+  ```
+
+- Clean apt files:
+
+  ```bash
+  export DEBIAN_FRONTEND=noninteractive
+
+  apt-get -y autopurge
+  apt-get -y clean
+
+  rm -rf /var/lib/apt/lists/*
+  ```
+
+- Clean logs:
+
+  ```bash
+  journalctl --flush
+  journalctl --rotate --vacuum-time=0
+
+  find /var/log -type f -exec truncate --size 0 {} \; # truncate system logs
+  find /var/log -type f -name '*.[1-9]' -delete # remove archived logs
+  find /var/log -type f -name '*.gz' -delete # remove compressed archived logs
+  ```
+
+- Reset host ssh keys:
+
+  ```bash
+  rm -f /etc/ssh/ssh_host_*_key /etc/ssh/ssh_host_*_key.pub
+  ```
+
+Once the cleanup is complete, you must discard the now unused blocks from the disk. This can be done with the following:
+
+```bash
+dd if=/dev/zero of=/zero bs=4M || true
+sync
+rm -f /zero
+```
+
+To speed up the process above, you may configure cloud-init to not grow the system partition to the server disk size during the boot process, leaving you with a 4GB system partition:
+
+```yaml
+#cloud-config
+growpart:
+  mode: "off"
+resize_rootfs: false
+```
+
+See the [docker example](https://github.com/hetznercloud/packer-plugin-hcloud/tree/main/example/docker) in the Packer project for more details.

docs/builders/hcloud.mdx

@@ -15,19 +15,22 @@ Type: `hcloud`
 Artifact BuilderId: `hcloud.builder`
 
 The `hcloud` Packer builder is able to create new images for use with [Hetzner
-Cloud](https://www.hetzner.cloud). The builder takes a source image, runs any
+Cloud](https://www.hetzner.com/cloud/). The builder takes a source image, runs any
 provisioning necessary on the image after launching it, then snapshots it into
 a reusable image. This reusable image can then be used as the foundation of new
 servers that are launched within the Hetzner Cloud.
 
 The builder does _not_ manage images. Once it creates an image, it is up to you
 to use it or delete it.
 
+## Connection to the server
+
 The builder will connect to the server using the first available IP, in the following order:
 
-- `public_ipv4`
-- `public_ipv6`
-- `private_ipv4`
+- `public_ipv4`: If enabled, the public IPv4 will be used,
+- `public_ipv6`: If enabled, the public IPv6 will be used,
+- `private_ipv4`: If the server is attached to private networks, the private IPv4 of the
+  first private network will be used.
 
 ## Configuration Reference
 
@@ -75,7 +78,7 @@ builder.
   - `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)
+    [Label Selectors](https://docs.hetzner.cloud/#label-selector)
     for more info.
 
   - `most_recent` (boolean) - Selects the newest created image when true.
@@ -155,3 +158,70 @@ build {
   sources  = ["source.hcloud.basic_example"]
 }
 ```
+
+See the [examples](https://github.com/hetznercloud/packer-plugin-hcloud/tree/main/example) folder in the Packer project for more examples.
+
+## Tips
+
+### Keeping the images size small
+
+To reduce the size of your images, we recommend cleaning up any temporary files that
+were added during the build process and discard the unused blocks from the disk.
+
+Below are a few commands that might useful:
+
+- Clean and reset could-init files:
+
+  ```bash
+  cloud-init clean --logs --machine-id --seed --configs all
+
+  rm -rf /run/cloud-init/*
+  rm -rf /var/lib/cloud/*
+  ```
+
+- Clean apt files:
+
+  ```bash
+  export DEBIAN_FRONTEND=noninteractive
+
+  apt-get -y autopurge
+  apt-get -y clean
+
+  rm -rf /var/lib/apt/lists/*
+  ```
+
+- Clean logs:
+
+  ```bash
+  journalctl --flush
+  journalctl --rotate --vacuum-time=0
+
+  find /var/log -type f -exec truncate --size 0 {} \; # truncate system logs
+  find /var/log -type f -name '*.[1-9]' -delete # remove archived logs
+  find /var/log -type f -name '*.gz' -delete # remove compressed archived logs
+  ```
+
+- Reset host ssh keys:
+
+  ```bash
+  rm -f /etc/ssh/ssh_host_*_key /etc/ssh/ssh_host_*_key.pub
+  ```
+
+Once the cleanup is complete, you must discard the now unused blocks from the disk. This can be done with the following:
+
+```bash
+dd if=/dev/zero of=/zero bs=4M || true
+sync
+rm -f /zero
+```
+
+To speed up the process above, you may configure cloud-init to not grow the system partition to the server disk size during the boot process, leaving you with a 4GB system partition:
+
+```yaml
+#cloud-config
+growpart:
+  mode: "off"
+resize_rootfs: false
+```
+
+See the [docker example](https://github.com/hetznercloud/packer-plugin-hcloud/tree/main/example/docker) in the Packer project for more details.

example/README.md

@@ -1,20 +1,3 @@
-## The Example Folder
+## Examples
 
-This folder must contain a fully working example of the plugin usage. The example must define the `required_plugins`
-block. A pre-defined GitHub Action will run `packer init`, `packer validate`, and `packer build` to test your plugin 
-with the latest version available of Packer.
-
-The folder can contain multiple HCL2 compatible files. The action will execute Packer at this folder level
-running `packer init -upgrade .` and `packer build .`.
-
-If the plugin requires authentication, the configuration should be provided via GitHub Secrets and set as environment
-variables in the [test-plugin-example.yml](/.github/workflows/test-plugin-example.yml) file. Example:
-
-```yml
-  - name: Build
-    working-directory: ${{ github.event.inputs.folder }}
-    run: PACKER_LOG=${{ github.event.inputs.logs }} packer build .
-    env:
-      AUTH_KEY: ${{ secrets.AUTH_KEY }}
-      AUTH_PASSWORD: ${{ secrets.AUTH_PASSWORD }}
-```
+This folder contain fully working examples of the plugin usage.

example/build.pkr.hcl → example/basic/build.pkr.hcl

@@ -5,7 +5,7 @@ packer {
   required_plugins {
     hcloud = {
       source  = "github.com/hetznercloud/hcloud"
-      version = ">=1.1.0"
+      version = ">=1.5.1"
     }
   }
 }
@@ -22,21 +22,22 @@ source "hcloud" "example" {
   location    = "hel1"
   image       = "ubuntu-24.04"
   server_type = "cpx11"
-  server_name = "hcloud-example"
+  server_name = "example-{{ timestamp }}"
 
   ssh_username = "root"
 
-  snapshot_name = "hcloud-example"
+  snapshot_name = "example-{{ timestamp }}"
   snapshot_labels = {
-    app = "hcloud-example"
+    app = "example"
   }
 }
 
 build {
   sources = ["source.hcloud.example"]
 
   provisioner "shell" {
-    inline = ["cloud-init status --wait || test $? -eq 2"]
+    inline           = ["cloud-init status --wait --long"]
+    valid_exit_codes = [0, 2]
   }
 
   provisioner "shell" {

example/docker/build.pkr.hcl

@@ -0,0 +1,57 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+packer {
+  required_plugins {
+    hcloud = {
+      source  = "github.com/hetznercloud/hcloud"
+      version = ">=1.5.1"
+    }
+  }
+}
+
+variable "hcloud_token" {
+  type      = string
+  sensitive = true
+  default   = "${env("HCLOUD_TOKEN")}"
+}
+
+source "hcloud" "docker" {
+  token = var.hcloud_token
+
+  location    = "hel1"
+  image       = "ubuntu-24.04"
+  server_type = "cpx11"
+  server_name = "docker-{{ timestamp }}"
+
+  user_data = <<-EOF
+    #cloud-config
+    growpart:
+      mode: "off"
+    resize_rootfs: false
+  EOF
+
+  ssh_username = "root"
+
+  snapshot_name = "docker-{{ timestamp }}"
+  snapshot_labels = {
+    app = "docker"
+  }
+}
+
+build {
+  sources = ["source.hcloud.docker"]
+
+  provisioner "shell" {
+    inline           = ["cloud-init status --wait --long"]
+    valid_exit_codes = [0, 2]
+  }
+
+  provisioner "shell" {
+    scripts = [
+      "install.sh",
+      "upgrade.sh",
+      "cleanup.sh",
+    ]
+  }
+}