github.com/pdecat/terraform@v0.11.9-beta1/website/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  ```hcl
    18  resource "aws_instance" "web" {
    19    # ...
    20  
    21    provisioner "local-exec" {
    22      command = "echo ${self.private_ip} > 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  Destroy-time provisioners can only run if they remain in the configuration
    59  at the time a resource is destroyed. If a resource block with a destroy-time
    60  provisioner is removed entirely from the configuration, its provisioner
    61  configurations are removed along with it and thus the destroy provisioner
    62  won't run. To work around this, a multi-step process can be used to safely
    63  remove a resource with a destroy-time provisioner:
    64  
    65  * Update the resource configuration to include `count = 0`.
    66  * Apply the configuration to destroy any existing instances of the resource, including running the destroy provisioner.
    67  * Remove the resource block entirely from configuration, along with its `provisioner` blocks.
    68  * Apply again, at which point no further action should be taken since the resources were already destroyed.
    69  
    70  This limitation may be addressed in future versions of Terraform. For now,
    71  destroy-time provisioners must be used sparingly and with care.
    72  
    73  ## Multiple Provisioners
    74  
    75  Multiple provisioners can be specified within a resource. Multiple provisioners
    76  are executed in the order they're defined in the configuration file.
    77  
    78  You may also mix and match creation and destruction provisioners. Only
    79  the provisioners that are valid for a given operation will be run. Those
    80  valid provisioners will be run in the order they're defined in the configuration
    81  file.
    82  
    83  Example of multiple provisioners:
    84  
    85  ```hcl
    86  resource "aws_instance" "web" {
    87    # ...
    88  
    89    provisioner "local-exec" {
    90      command = "echo first"
    91    }
    92  
    93    provisioner "local-exec" {
    94      command = "echo second"
    95    }
    96  }
    97  ```
    98  
    99  ## Failure Behavior
   100  
   101  By default, provisioners that fail will also cause the Terraform apply
   102  itself to error. The `on_failure` setting can be used to change this. The
   103  allowed values are:
   104  
   105  - `"continue"` - Ignore the error and continue with creation or destruction.
   106  
   107  - `"fail"` - Error (the default behavior). If this is a creation provisioner,
   108      taint the resource.
   109  
   110  Example:
   111  
   112  ```hcl
   113  resource "aws_instance" "web" {
   114    # ...
   115  
   116    provisioner "local-exec" {
   117      command    = "echo ${self.private_ip} > file.txt"
   118      on_failure = "continue"
   119    }
   120  }
   121  ```