github.com/wikibal01/hashicorp-terraform@v0.11.12-beta1/website/docs/commands/taint.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Command: taint"
     4  sidebar_current: "docs-commands-taint"
     5  description: |-
     6    The `terraform taint` command manually marks a Terraform-managed resource as tainted, forcing it to be destroyed and recreated on the next apply.
     7  ---
     8  
     9  # Command: taint
    10  
    11  The `terraform taint` command manually marks a Terraform-managed resource
    12  as tainted, forcing it to be destroyed and recreated on the next apply.
    13  
    14  This command _will not_ modify infrastructure, but does modify the
    15  state file in order to mark a resource as tainted. Once a resource is
    16  marked as tainted, the next
    17  [plan](/docs/commands/plan.html) will show that the resource will
    18  be destroyed and recreated and the next
    19  [apply](/docs/commands/apply.html) will implement this change.
    20  
    21  Forcing the recreation of a resource is useful when you want a certain
    22  side effect of recreation that is not visible in the attributes of a resource.
    23  For example: re-running provisioners will cause the node to be different
    24  or rebooting the machine from a base image will cause new startup scripts
    25  to run.
    26  
    27  Note that tainting a resource for recreation may affect resources that
    28  depend on the newly tainted resource. For example, a DNS resource that
    29  uses the IP address of a server may need to be modified to reflect
    30  the potentially new IP address of a tainted server. The
    31  [plan command](/docs/commands/plan.html) will show this if this is
    32  the case.
    33  
    34  ## Usage
    35  
    36  Usage: `terraform taint [options] name`
    37  
    38  The `name` argument is the name of the resource to mark as tainted.
    39  The format of this argument is `TYPE.NAME`, such as `aws_instance.foo`.
    40  
    41  The command-line flags are all optional. The list of available flags are:
    42  
    43  * `-allow-missing` - If specified, the command will succeed (exit code 0)
    44      even if the resource is missing. The command can still error, but only
    45      in critically erroneous cases.
    46  
    47  * `-backup=path` - Path to the backup file. Defaults to `-state-out` with
    48    the ".backup" extension. Disabled by setting to "-".
    49  
    50  * `-lock=true` - Lock the state file when locking is supported.
    51  
    52  * `-lock-timeout=0s` - Duration to retry a state lock.
    53  
    54  * `-module=path` - The module path where the resource to taint exists.
    55      By default this is the root path. Other modules can be specified by
    56      a period-separated list. Example: "foo" would reference the module
    57      "foo" but "foo.bar" would reference the "bar" module in the "foo"
    58      module.
    59  
    60  * `-no-color` - Disables output with coloring
    61  
    62  * `-state=path` - Path to read and write the state file to. Defaults to "terraform.tfstate".
    63    Ignored when [remote state](/docs/state/remote.html) is used.
    64  
    65  * `-state-out=path` - Path to write updated state file. By default, the
    66    `-state` path will be used. Ignored when
    67    [remote state](/docs/state/remote.html) is used.
    68  
    69  ## Example: Tainting a Single Resource
    70  
    71  This example will taint a single resource:
    72  
    73  ```
    74  $ terraform taint aws_security_group.allow_all
    75  The resource aws_security_group.allow_all in the module root has been marked as tainted!
    76  ```
    77  
    78  ## Example: Tainting a Resource within a Module
    79  
    80  This example will only taint a resource within a module:
    81  
    82  ```
    83  $ terraform taint -module=couchbase aws_instance.cb_node.9
    84  The resource aws_instance.cb_node.9 in the module root.couchbase has been marked as tainted!
    85  ```