github.com/pulumi/terraform@v1.4.0/website/docs/language/resources/provisioners/file.mdx (about)

     1  ---
     2  page_title: 'Provisioner: file'
     3  description: >-
     4    The `file` provisioner is used to copy files or directories from the machine
     5    executing Terraform to the newly created resource. The `file` provisioner
     6    supports both `ssh` and `winrm` type connections.
     7  ---
     8  
     9  # File Provisioner
    10  
    11  The `file` provisioner copies files or directories from the machine
    12  running Terraform to the newly created resource. The `file` provisioner
    13  supports both `ssh` and `winrm` type [connections](/language/resources/provisioners/connection).
    14  
    15  ~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
    16  [Declaring Provisioners](/language/resources/provisioners/syntax) for more details.
    17  
    18  ## Example usage
    19  
    20  ```hcl
    21  resource "aws_instance" "web" {
    22    # ...
    23  
    24    # Copies the myapp.conf file to /etc/myapp.conf
    25    provisioner "file" {
    26      source      = "conf/myapp.conf"
    27      destination = "/etc/myapp.conf"
    28    }
    29  
    30    # Copies the string in content into /tmp/file.log
    31    provisioner "file" {
    32      content     = "ami used: ${self.ami}"
    33      destination = "/tmp/file.log"
    34    }
    35  
    36    # Copies the configs.d folder to /etc/configs.d
    37    provisioner "file" {
    38      source      = "conf/configs.d"
    39      destination = "/etc"
    40    }
    41  
    42    # Copies all files and folders in apps/app1 to D:/IIS/webapp1
    43    provisioner "file" {
    44      source      = "apps/app1/"
    45      destination = "D:/IIS/webapp1"
    46    }
    47  }
    48  ```
    49  
    50  -> **Note:** When the `file` provisioner communicates with a Windows system over SSH, you must configure OpenSSH to run the commands with `cmd.exe` and not PowerShell. PowerShell causes file parsing errors because it is incompatible with both Unix shells and the Windows command interpreter.
    51  
    52  ## Argument Reference
    53  
    54  The following arguments are supported:
    55  
    56  * `source` - The source file or directory. Specify it either relative to the
    57    current working directory or as an absolute path.
    58    This argument cannot be combined with `content`.
    59  
    60  * `content` - The direct content to copy on the destination.
    61    If destination is a file, the content will be written on that file. In case
    62    of a directory, a file named `tf-file-content` is created inside that
    63    directory. We recommend using a file as the destination when using `content`.
    64    This argument cannot be combined with `source`.
    65  
    66  * `destination` - (Required) The destination path to write to on the remote
    67    system. See [Destination Paths](#destination-paths) below for more
    68    information.
    69  
    70  ## Destination Paths
    71  
    72  The path you provide in the `destination` argument will be evaluated by the
    73  remote system, rather than by Terraform itself. Therefore the valid values
    74  for that argument can vary depending on the operating system and remote access
    75  software running on the target.
    76  
    77  When connecting over SSH, the `file` provisioner passes the given destination
    78  path verbatim to the `scp` program on the remote host. By default, OpenSSH's
    79  `scp` implementation runs in the remote user's home directory and so you can
    80  specify a relative path to upload into that home directory, or an absolute
    81  path to upload to some other location. The remote `scp` process will run with
    82  the access level of the user specified in the `connection` block, and so
    83  permissions may prevent writing directly to locations outside of the home
    84  directory.
    85  
    86  Because WinRM has no corresponding file transfer protocol, for WinRM
    87  connections the `file` provisioner uses a more complex process:
    88  
    89  1. Generate a temporary filename in the directory given in the remote system's
    90     `TEMP` environment variable, using a pseudorandom UUID for uniqueness.
    91  2. Use sequential generated `echo` commands over WinRM to gradually append
    92     base64-encoded chunks of the source file to the chosen temporary file.
    93  3. Use an uploaded PowerShell script to read the temporary file, base64-decode,
    94     and write the raw result into the destination file.
    95  
    96  In the WinRM case, the destination path is therefore interpreted by PowerShell
    97  and so you must take care not to use any meta-characters that PowerShell might
    98  interpret. In particular, avoid including any untrusted external input in
    99  your `destination` argument when using WinRM, because it can serve as a vector
   100  for arbitrary PowerShell code execution on the remote system.
   101  
   102  Modern Windows systems support running an OpenSSH server, so we strongly
   103  recommend choosing SSH over WinRM whereever possible, and using WinRM only as
   104  a last resort when working with obsolete Windows versions.
   105  
   106  ## Directory Uploads
   107  
   108  The `file` provisioner can upload a complete directory to the remote machine.
   109  When uploading a directory, there are some additional considerations.
   110  
   111  When using the `ssh` connection type the destination directory must already
   112  exist. If you need to create it, use a remote-exec provisioner just prior to
   113  the file provisioner in order to create the directory
   114  
   115  When using the `winrm` connection type the destination directory will be
   116  created for you if it doesn't already exist.
   117  
   118  The existence of a trailing slash on the source path will determine whether the
   119  directory name will be embedded within the destination, or whether the
   120  destination will be created. For example:
   121  
   122  * If the source is `/foo` (no trailing slash), and the destination is `/tmp`,
   123    then the contents of `/foo` on the local machine will be uploaded to
   124    `/tmp/foo` on the remote machine. The `foo` directory on the remote machine
   125    will be created by Terraform.
   126  
   127  * If the source, however, is `/foo/` (a trailing slash is present), and the
   128    destination is `/tmp`, then the contents of `/foo` will be uploaded directly
   129    into `/tmp`.