github.com/nathanielks/terraform@v0.6.1-0.20170509030759-13e1a62319dc/website/source/intro/getting-started/provision.html.md (about)

     1  ---
     2  layout: "intro"
     3  page_title: "Provision"
     4  sidebar_current: "gettingstarted-provision"
     5  description: |-
     6    Introduces provisioners that can initialize instances when they're created.
     7  ---
     8  
     9  # Provision
    10  
    11  You're now able to create and modify infrastructure. Now let's see
    12  how to use provisioners to initialize instances when they're created.
    13  
    14  If you're using an image-based infrastructure (perhaps with images
    15  created with [Packer](https://www.packer.io)), then what you've
    16  learned so far is good enough. But if you need to do some initial
    17  setup on your instances, then provisioners let you upload files,
    18  run shell scripts, or install and trigger other software like
    19  configuration management tools, etc.
    20  
    21  ## Defining a Provisioner
    22  
    23  To define a provisioner, modify the resource block defining the
    24  "example" EC2 instance to look like the following:
    25  
    26  ```hcl
    27  resource "aws_instance" "example" {
    28    ami           = "ami-b374d5a5"
    29    instance_type = "t2.micro"
    30  
    31    provisioner "local-exec" {
    32      command = "echo ${aws_instance.example.public_ip} > ip_address.txt"
    33    }
    34  }
    35  ```
    36  
    37  This adds a `provisioner` block within the `resource` block. Multiple
    38  `provisioner` blocks can be added to define multiple provisioning steps.
    39  Terraform supports
    40  [multiple provisioners](/docs/provisioners/index.html),
    41  but for this example we are using the `local-exec` provisioner.
    42  
    43  The `local-exec` provisioner executes a command locally on the machine
    44  running Terraform. We're using this provisioner versus the others so
    45  we don't have to worry about specifying any
    46  [connection info](/docs/provisioners/connection.html) right now.
    47  
    48  ## Running Provisioners
    49  
    50  Provisioners are only run when a resource is _created_. They
    51  are not a replacement for configuration management and changing
    52  the software of an already-running server, and are instead just
    53  meant as a way to bootstrap a server. For configuration management,
    54  you should use Terraform provisioning to invoke a real configuration
    55  management solution.
    56  
    57  Make sure that your infrastructure is
    58  [destroyed](/intro/getting-started/destroy.html) if it isn't already,
    59  then run `apply`:
    60  
    61  ```
    62  $ terraform apply
    63  aws_instance.example: Creating...
    64    ami:           "" => "ami-b374d5a5"
    65    instance_type: "" => "t2.micro"
    66  aws_eip.ip: Creating...
    67    instance: "" => "i-213f350a"
    68  
    69  Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
    70  ```
    71  
    72  Terraform will output anything from provisioners to the console,
    73  but in this case there is no output. However, we can verify
    74  everything worked by looking at the `ip_address.txt` file:
    75  
    76  ```
    77  $ cat ip_address.txt
    78  54.192.26.128
    79  ```
    80  
    81  It contains the IP, just as we asked!
    82  
    83  ## Failed Provisioners and Tainted Resources
    84  
    85  If a resource successfully creates but fails during provisioning,
    86  Terraform will error and mark the resource as "tainted." A
    87  resource that is tainted has been physically created, but can't
    88  be considered safe to use since provisioning failed.
    89  
    90  When you generate your next execution plan, Terraform will not attempt to restart
    91  provisioning on the same resource because it isn't guaranteed to be safe. Instead,
    92  Terraform will remove any tainted resources and create new resources, attempting to
    93  provision them again after creation.
    94  
    95  Terraform also does not automatically roll back and destroy the resource
    96  during the apply when the failure happens, because that would go
    97  against the execution plan: the execution plan would've said a
    98  resource will be created, but does not say it will ever be deleted.
    99  If you create an execution plan with a tainted resource, however, the
   100  plan will clearly state that the resource will be destroyed because
   101  it is tainted.
   102  
   103  ## Destroy Provisioners
   104  
   105  Provisioners can also be defined that run only during a destroy
   106  operation. These are useful for performing system cleanup, extracting
   107  data, etc.
   108  
   109  For many resources, using built-in cleanup mechanisms is recommended
   110  if possible (such as init scripts), but provisioners can be used if
   111  necessary.
   112  
   113  The getting started guide won't show any destroy provisioner examples.
   114  If you need to use destroy provisioners, please
   115  [see the provisioner documentation](/docs/provisioners).
   116  
   117  ## Next
   118  
   119  Provisioning is important for being able to bootstrap instances.
   120  As another reminder, it is not a replacement for configuration
   121  management. It is meant to simply bootstrap machines. If you use
   122  configuration management, you should use the provisioning as a way
   123  to bootstrap the configuration management tool.
   124  
   125  In the next section, we start looking at [variables as a way to
   126  parameterize our configurations](/intro/getting-started/variables.html).