File provisioner docs (#9735)

provisioner/file/provisioner.go

@@ -1,4 +1,5 @@
 //go:generate mapstructure-to-hcl2 -type Config
+//go:generate struct-markdown
 
 package file
 
@@ -20,19 +21,41 @@ import (
 
 type Config struct {
 	common.PackerConfig `mapstructure:",squash"`
-
+	// The path to a local file or directory to upload to the
-	// The local path of the file to upload.
+	// machine. The path can be absolute or relative. If it is relative, it is
-	Source  string
+	// relative to the working directory when Packer is executed. If this is a
-	Sources []string
+	// directory, the existence of a trailing slash is important. Read below on
-
+	// uploading directories. Mandatory unless `sources` is set.
-	// The remote path where the local file will be uploaded to.
+	Source string `mapstructure:"source" required:"true"`
-	Destination string
+	// A list of sources to upload. This can be used in place of the `source`
-
+	// option if you have several files that you want to upload to the same
-	// Direction
+	// place. Note that the destination must be a directory with a trailing
-	Direction string
+	// slash, and that all files listed in `sources` will be uploaded to the
-
+	// same directory with their file names preserved.
-	// False if the sources have to exist.
+	Sources []string `mapstructure:"sources" required:"false"`
-	Generated bool
+	// The path where the file will be uploaded to in the machine. This value
+	// must be a writable location and any parent directories
+	// must already exist. If the provisioning user (generally not root) cannot
+	// write to this directory, you will receive a "Permission Denied" error.
+	// If the source is a file, it's a good idea to make the destination a file
+	// as well, but if you set your destination as a directory, at least make
+	// sure that the destination ends in a trailing slash so that Packer knows
+	// to use the source's basename in the final upload path. Failure to do so
+	// may cause Packer to fail on file uploads. If the destination file
+	// already exists, it will be overwritten.
+	Destination string `mapstructure:"destination" required:"true"`
+	// The direction of the file transfer. This defaults to "upload". If it is
+	// set to "download" then the file "source" in the machine will be
+	// downloaded locally to "destination"
+	Direction string `mapstructure:"direction" required:"false"`
+	// For advanced users only. If true, check the file existence only before
+	// uploading, rather than upon pre-build validation. This allows users to
+	// upload files created on-the-fly. This defaults to false. We
+	// don't recommend using this feature, since it can cause Packer to become
+	// dependent on system state. We would prefer you generate your files before
+	// the Packer run, but realize that there are situations where this may be
+	// unavoidable.
+	Generated bool `mapstructure:"generated" required:"false"`
 
 	ctx interpolate.Context
 }

provisioner/file/provisioner.hcl2spec.go

@@ -16,11 +16,11 @@ type FlatConfig struct {
 	PackerOnError       *string           `mapstructure:"packer_on_error" cty:"packer_on_error" hcl:"packer_on_error"`
 	PackerUserVars      map[string]string `mapstructure:"packer_user_variables" cty:"packer_user_variables" hcl:"packer_user_variables"`
 	PackerSensitiveVars []string          `mapstructure:"packer_sensitive_variables" cty:"packer_sensitive_variables" hcl:"packer_sensitive_variables"`
-	Source              *string           `cty:"source" hcl:"source"`
+	Source              *string           `mapstructure:"source" required:"true" cty:"source" hcl:"source"`
-	Sources             []string          `cty:"sources" hcl:"sources"`
+	Sources             []string          `mapstructure:"sources" required:"false" cty:"sources" hcl:"sources"`
-	Destination         *string           `cty:"destination" hcl:"destination"`
+	Destination         *string           `mapstructure:"destination" required:"true" cty:"destination" hcl:"destination"`
-	Direction           *string           `cty:"direction" hcl:"direction"`
+	Direction           *string           `mapstructure:"direction" required:"false" cty:"direction" hcl:"direction"`
-	Generated           *bool             `cty:"generated" hcl:"generated"`
+	Generated           *bool             `mapstructure:"generated" required:"false" cty:"generated" hcl:"generated"`
 }
 
 // FlatMapstructure returns a new FlatConfig.

website/pages/docs/provisioners/file.mdx

@@ -27,6 +27,9 @@ The file provisioner can upload both single files and complete directories.
 
 ## Basic Example
 
+<Tabs>
+<Tab heading="JSON">
+
 ```json
 {
   "type": "file",
@@ -35,42 +38,32 @@ The file provisioner can upload both single files and complete directories.
 }
 ```
 
+</Tab>
+<Tab heading="HCL2">
+
+```hcl
+provisioner "file"{
+  source = "app.tar.gz"
+  destination = "/tmp/app.tar.gz"
+}
+```
+
+</Tab>
+</Tabs>
+
 ## Configuration Reference
 
 The available configuration options are listed below.
 
-### Required
+## Configuration Reference
 
-- `source` (string) - The path to a local file or directory to upload to the
+Required Parameters:
-  machine. The path can be absolute or relative. If it is relative, it is
-  relative to the working directory when Packer is executed. If this is a
-  directory, the existence of a trailing slash is important. Read below on
-  uploading directories.
 
-- `destination` (string) - The path where the file will be uploaded to in the
+@include 'provisioner/file/Config-required.mdx'
-  machine. This value must be a writable location and any parent directories
-  must already exist. If the provisioning user (generally not root) cannot
-  write to this directory, you will receive a "Permission Denied" error.
-  If the source is a file, it's a good idea to make the
-  destination a file as well, but if you set your destination as a directory,
-  at least make sure that the destination ends in a trailing slash so that
-  Packer knows to use the source's basename in the final upload path. Failure
-  to do so may cause Packer to fail on file uploads. If the destination file
-  already exists, it will be overwritten.
 
-- `direction` (string) - The direction of the file transfer. This defaults to
+Optional Parameters:
-  "upload". If it is set to "download" then the file "source" in the machine
-  will be downloaded locally to "destination"
 
-### Optional
+@include '/provisioner/file/Config-not-required.mdx'
-
-- `generated` (boolean) - For advanced users only. If true, check the file
-  existence only before uploading, rather than upon pre-build validation.
-  This allows to upload files created on-the-fly. This defaults to false. We
-  don't recommend using this feature, since it can cause Packer to become
-  dependent on system state. We would prefer you generate your files before
-  the Packer run, but realize that there are situations where this may be
-  unavoidable.
 
 @include 'provisioners/common-config.mdx'
 
@@ -131,6 +124,9 @@ total 0
 -rw-r--r--  1 mwhooker  staff    0 Jan 27 17:10 files.tar
 ```
 
+<Tabs>
+<Tab heading="JSON">
+
 ```json
 {
   "provisioners": [
@@ -154,6 +150,34 @@ total 0
 }
 ```
 
+</Tab>
+<Tab heading="HCL2">
+
+```hcl
+build {
+  sources = [
+    "source.docker.example"
+  ]
+
+  provisioner "shell-local" {
+    command = "tar cf toupload/files.tar files"
+  }
+  provisioner "file" {
+    destination = "/tmp/"
+    source      = "./toupload"
+  }
+  provisioner "shell" {
+    inline = [
+      "cd /tmp && tar xf toupload/files.tar",
+      "rm toupload/files.tar"
+    ]
+  }
+}
+```
+
+</Tab>
+</Tabs>
+
 ## Slowness when transferring large files over WinRM.
 
 Because of the way our WinRM transfers works, it can take a very long time to

website/pages/partials/provisioner/file/Config-not-required.mdx

@@ -0,0 +1,19 @@
+<!-- Code generated from the comments of the Config struct in provisioner/file/provisioner.go; DO NOT EDIT MANUALLY -->
+
+- `sources` ([]string) - A list of sources to upload. This can be used in place of the `source`
+  option if you have several files that you want to upload to the same
+  place. Note that the destination must be a directory with a trailing
+  slash, and that all files listed in `sources` will be uploaded to the
+  same directory with their file names preserved.
+
+- `direction` (string) - The direction of the file transfer. This defaults to "upload". If it is
+  set to "download" then the file "source" in the machine will be
+  downloaded locally to "destination"
+
+- `generated` (bool) - For advanced users only. If true, check the file existence only before
+  uploading, rather than upon pre-build validation. This allows users to
+  upload files created on-the-fly. This defaults to false. We
+  don't recommend using this feature, since it can cause Packer to become
+  dependent on system state. We would prefer you generate your files before
+  the Packer run, but realize that there are situations where this may be
+  unavoidable.

website/pages/partials/provisioner/file/Config-required.mdx

@@ -0,0 +1,18 @@
+<!-- Code generated from the comments of the Config struct in provisioner/file/provisioner.go; DO NOT EDIT MANUALLY -->
+
+- `source` (string) - The path to a local file or directory to upload to the
+  machine. The path can be absolute or relative. If it is relative, it is
+  relative to the working directory when Packer is executed. If this is a
+  directory, the existence of a trailing slash is important. Read below on
+  uploading directories. Mandatory unless `sources` is set.
+
+- `destination` (string) - The path where the file will be uploaded to in the machine. This value
+  must be a writable location and any parent directories
+  must already exist. If the provisioning user (generally not root) cannot
+  write to this directory, you will receive a "Permission Denied" error.
+  If the source is a file, it's a good idea to make the destination a file
+  as well, but if you set your destination as a directory, at least make
+  sure that the destination ends in a trailing slash so that Packer knows
+  to use the source's basename in the final upload path. Failure to do so
+  may cause Packer to fail on file uploads. If the destination file
+  already exists, it will be overwritten.