github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/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] address`
    37  
    38  The `address` argument is the address of the resource to mark as tainted.
    39  The address is in
    40  [the resource address syntax](/docs/internals/resource-addressing.html) syntax,
    41  as shown in the output from other commands, such as:
    42  
    43   * `aws_instance.foo`
    44   * `aws_instance.bar[1]`
    45   * `aws_instance.baz``[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they are not interpreted by your shell)
    46   * `module.foo.module.bar.aws_instance.qux`
    47  
    48  The command-line flags are all optional. The list of available flags are:
    49  
    50  * `-allow-missing` - If specified, the command will succeed (exit code 0)
    51      even if the resource is missing. The command can still error, but only
    52      in critically erroneous cases.
    53  
    54  * `-backup=path` - Path to the backup file. Defaults to `-state-out` with
    55    the ".backup" extension. Disabled by setting to "-".
    56  
    57  * `-lock=true` - Lock the state file when locking is supported.
    58  
    59  * `-lock-timeout=0s` - Duration to retry a state lock.
    60  
    61  * `-state=path` - Path to read and write the state file to. Defaults to "terraform.tfstate".
    62    Ignored when [remote state](/docs/state/remote.html) is used.
    63  
    64  * `-state-out=path` - Path to write updated state file. By default, the
    65    `-state` path will be used. Ignored when
    66    [remote state](/docs/state/remote.html) is used.
    67  
    68  ## Example: Tainting a Single Resource
    69  
    70  This example will taint a single resource:
    71  
    72  ```
    73  $ terraform taint aws_security_group.allow_all
    74  The resource aws_security_group.allow_all in the module root has been marked as tainted.
    75  ```
    76  
    77  ## Example: Tainting a single resource created with for_each
    78  
    79  It is necessary to wrap the resource in single quotes and escape the quotes.
    80  This example will taint a single resource created with for_each:
    81  
    82  ```
    83  $ terraform taint 'module.route_tables.azurerm_route_table.rt[\"DefaultSubnet\"]'
    84  The resource module.route_tables.azurerm_route_table.rt["DefaultSubnet"] in the module root has been marked as tainted.
    85  ```
    86  
    87  
    88  ## Example: Tainting a Resource within a Module
    89  
    90  This example will only taint a resource within a module:
    91  
    92  ```
    93  $ terraform taint "module.couchbase.aws_instance.cb_node[9]"
    94  Resource instance module.couchbase.aws_instance.cb_node[9] has been marked as tainted.
    95  ```
    96  
    97  Although we recommend that most configurations use only one level of nesting
    98  and employ [module composition](/docs/modules/composition.html), it's possible
    99  to have multiple levels of nested modules. In that case the resource instance
   100  address must include all of the steps to the target instance, as in the
   101  following example:
   102  
   103  ```
   104  $ terraform taint "module.child.module.grandchild.aws_instance.example[2]"
   105  Resource instance module.child.module.grandchild.aws_instance.example[2] has been marked as tainted.
   106  ```