diff --git a/provisioner/file/provisioner.go b/provisioner/file/provisioner.go
index f8fcc403a..45a1f6618 100644
--- a/provisioner/file/provisioner.go
+++ b/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 local path of the file to upload.
- Source string
- Sources []string
-
- // The remote path where the local file will be uploaded to.
- Destination string
-
- // Direction
- Direction string
-
- // False if the sources have to exist.
- Generated bool
+ // 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.
+ Source string `mapstructure:"source" required:"true"`
+ // 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.
+ Sources []string `mapstructure:"sources" required:"false"`
+ // 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
}
diff --git a/provisioner/file/provisioner.hcl2spec.go b/provisioner/file/provisioner.hcl2spec.go
index ad9e76099..0d17615b3 100644
--- a/provisioner/file/provisioner.hcl2spec.go
+++ b/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"`
- Sources []string `cty:"sources" hcl:"sources"`
- Destination *string `cty:"destination" hcl:"destination"`
- Direction *string `cty:"direction" hcl:"direction"`
- Generated *bool `cty:"generated" hcl:"generated"`
+ Source *string `mapstructure:"source" required:"true" cty:"source" hcl:"source"`
+ Sources []string `mapstructure:"sources" required:"false" cty:"sources" hcl:"sources"`
+ Destination *string `mapstructure:"destination" required:"true" cty:"destination" hcl:"destination"`
+ Direction *string `mapstructure:"direction" required:"false" cty:"direction" hcl:"direction"`
+ Generated *bool `mapstructure:"generated" required:"false" cty:"generated" hcl:"generated"`
}
// FlatMapstructure returns a new FlatConfig.
diff --git a/website/pages/docs/provisioners/file.mdx b/website/pages/docs/provisioners/file.mdx
index 99bb028b6..904522d8b 100644
--- a/website/pages/docs/provisioners/file.mdx
+++ b/website/pages/docs/provisioners/file.mdx
@@ -27,6 +27,9 @@ The file provisioner can upload both single files and complete directories.
## Basic Example
+
+
+
```json
{
"type": "file",
@@ -35,42 +38,32 @@ The file provisioner can upload both single files and complete directories.
}
```
+
+
+
+```hcl
+provisioner "file"{
+ source = "app.tar.gz"
+ destination = "/tmp/app.tar.gz"
+}
+```
+
+
+
+
## 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
- 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.
+Required Parameters:
-- `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.
+@include 'provisioner/file/Config-required.mdx'
-- `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"
+Optional Parameters:
-### Optional
-
-- `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 '/provisioner/file/Config-not-required.mdx'
@include 'provisioners/common-config.mdx'
@@ -131,6 +124,9 @@ total 0
-rw-r--r-- 1 mwhooker staff 0 Jan 27 17:10 files.tar
```
+
+
+
```json
{
"provisioners": [
@@ -154,6 +150,34 @@ total 0
}
```
+
+
+
+```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"
+ ]
+ }
+}
+```
+
+
+
+
## Slowness when transferring large files over WinRM.
Because of the way our WinRM transfers works, it can take a very long time to
diff --git a/website/pages/partials/provisioner/file/Config-not-required.mdx b/website/pages/partials/provisioner/file/Config-not-required.mdx
new file mode 100644
index 000000000..fddfbcefd
--- /dev/null
+++ b/website/pages/partials/provisioner/file/Config-not-required.mdx
@@ -0,0 +1,19 @@
+
+
+- `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.
diff --git a/website/pages/partials/provisioner/file/Config-required.mdx b/website/pages/partials/provisioner/file/Config-required.mdx
new file mode 100644
index 000000000..86f9016eb
--- /dev/null
+++ b/website/pages/partials/provisioner/file/Config-required.mdx
@@ -0,0 +1,18 @@
+
+
+- `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.