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.