aherman
/
packer
mirror of https://github.com/hashicorp/packer
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

File provisioner docs (#9735)

Browse Source
pull/9738/head
Megan Marsh 6 years ago committed by GitHub
parent daccfc42cf
commit d826711e7a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 134 additions and 50 deletions
Show Stats Download Patch File Download Diff File

49
provisioner/file/provisioner.go
Unescape View File

@ -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
}

10
provisioner/file/provisioner.hcl2spec.go
Unescape View File

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

88
website/pages/docs/provisioners/file.mdx
Unescape View File

@ -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
- `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.
- `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.
- `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
- `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.
## Configuration Reference
Required Parameters:
@include 'provisioner/file/Config-required.mdx'
Optional Parameters:
@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
```
<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

19
website/pages/partials/provisioner/file/Config-not-required.mdx
Unescape View File

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

18
website/pages/partials/provisioner/file/Config-required.mdx
Unescape View File

@ -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.
Write Preview
Loading…
Cancel
Save