github.com/vtorhonen/terraform@v0.9.0-beta2.0.20170307220345-5d894e4ffda7/website/source/docs/provisioners/index.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Provisioners"
     4  sidebar_current: "docs-provisioners"
     5  description: |-
     6    Provisioners are used to execute scripts on a local or remote machine as part of resource creation or destruction.
     7  ---
     8  
     9  # Provisioners
    10  
    11  Provisioners are used to execute scripts on a local or remote machine
    12  as part of resource creation or destruction. Provisioners can be used to
    13  bootstrap a resource, cleanup before destroy, run configuration management, etc.
    14  
    15  Provisioners are added directly to any resource:
    16  
    17  ```
    18  resource "aws_instance" "web" {
    19    # ...
    20  
    21    provisioner "local-exec" {
    22      command = "echo ${self.private_ip_address} > file.txt"
    23    }
    24  }
    25  ```
    26  
    27  For provisioners other than local execution, you must specify
    28  [connection settings](/docs/provisioners/connection.html) so Terraform knows
    29  how to communicate with the resource.
    30  
    31  ## Creation-Time Provisioners
    32  
    33  Provisioners by default run when the resource they are defined within is
    34  created. Creation-time provisioners are only run during _creation_, not
    35  during updating or any other lifecycle. They are meant as a means to perform
    36  bootstrapping of a system.
    37  
    38  If a creation-time provisioner fails, the resource is marked as **tainted**.
    39  A tainted resource will be planned for destruction and recreation upon the
    40  next `terraform apply`. Terraform does this because a failed provisioner
    41  can leave a resource in a semi-configured state. Because Terraform cannot
    42  reason about what the provisioner does, the only way to ensure proper creation
    43  of a resource is to recreate it. This is tainting.
    44  
    45  You can change this behavior by setting the `on_failure` attribute,
    46  which is covered in detail below.
    47  
    48  ## Destroy-Time Provisioners
    49  
    50  If `when = "destroy"` is specified, the provisioner will run when the
    51  resource it is defined within is _destroyed_.
    52  
    53  Destroy provisioners are run before the resource is destroyed. If they
    54  fail, Terraform will error and rerun the provisioners again on the next
    55  `terraform apply`. Due to this behavior, care should be taken for destroy
    56  provisioners to be safe to run multiple times.
    57  
    58  ## Multiple Provisioners
    59  
    60  Multiple provisioners can be specified within a resource. Multiple provisioners
    61  are executed in the order they're defined in the configuration file.
    62  
    63  You may also mix and match creation and destruction provisioners. Only
    64  the provisioners that are valid for a given operation will be run. Those
    65  valid provisioners will be run in the order they're defined in the configuration
    66  file.
    67  
    68  Example of multiple provisioners:
    69  
    70  ```
    71  resource "aws_instance" "web" {
    72    # ...
    73  
    74    provisioner "local-exec" {
    75      command = "echo first"
    76    }
    77  
    78    provisioner "local-exec" {
    79      command = "echo second"
    80    }
    81  }
    82  ```
    83  
    84  ## Failure Behavior
    85  
    86  By default, provisioners that fail will also cause the Terraform apply
    87  itself to error. The `on_failure` setting can be used to change this. The
    88  allowed values are:
    89  
    90    * `"continue"` - Ignore the error and continue with creation or destruction.
    91  
    92    * `"fail"` - Error (the default behavior). If this is a creation provisioner,
    93      taint the resource.
    94  
    95  Example:
    96  
    97  ```
    98  resource "aws_instance" "web" {
    99    # ...
   100  
   101    provisioner "local-exec" {
   102      command    = "echo ${self.private_ip_address} > file.txt"
   103      on_failure = "continue"
   104    }
   105  }
   106  ```