github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/docs/cli/commands/state/rm.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Command: state rm"
     4  sidebar_current: "docs-commands-state-sub-rm"
     5  description: |-
     6    The `terraform state rm` command removes bindings from the Terraform state, causing Terraform to "forget about" existing objects.
     7  ---
     8  
     9  # Command: state rm
    10  
    11  The main function of [Terraform state](/docs/language/state/index.html) is
    12  to track the bindings between resource instance addresses in your configuration
    13  and the remote objects they represent. Normally Terraform automatically
    14  updates the state in response to actions taken when applying a plan, such as
    15  removing a binding for a remote object that has now been deleted.
    16  
    17  You can use `terraform state rm` in the less common situation where you wish
    18  to remove a binding to an existing remote object without first destroying it,
    19  which will effectively make Terraform "forget" the object while it continues
    20  to exist in the remote system.
    21  
    22  ## Usage
    23  
    24  Usage: `terraform state rm [options] ADDRESS...`
    25  
    26  Terraform will search the state for any instances matching the given
    27  [resource address](/docs/cli/state/resource-addressing.html), and remove
    28  the record of each one so that Terraform will no longer be tracking the
    29  corresponding remote objects.
    30  
    31  This means that although the objects will still continue to exist in the
    32  remote system, a subsequent
    33  [`terraform plan`](../plan.html)
    34  will include an action to create a new object for each of the "forgotten"
    35  instances. Depending on the constraints imposed by the remote system, creating
    36  those objects might fail if their names or other identifiers conflict with
    37  the old objects still present.
    38  
    39  This command also accepts the following options:
    40  
    41  * `-dry-run` - Report all of the resource instances that match the given
    42    address without actually "forgetting" any of them.
    43  
    44  * `-lock=false` - Don't hold a state lock during the operation. This is
    45     dangerous if others might concurrently run commands against the same
    46     workspace.
    47  
    48  * `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`,
    49    instructs Terraform to retry acquiring a lock for a period of time before
    50    returning an error. The duration syntax is a number followed by a time
    51    unit letter, such as "3s" for three seconds.
    52  
    53  For configurations using
    54  [the `remote` backend](/docs/language/settings/backends/remote.html)
    55  only, `terraform state rm`
    56  also accepts the option
    57  [`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
    58  
    59  For configurations using
    60  [the `local` state rm](/docs/language/settings/backends/local.html) only,
    61  `terraform state rm` also accepts the legacy options
    62  [`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
    63  
    64  ## Example: Remove all Instances of a Resource
    65  
    66  The following example will cause Terraform to "forget" all of the instances
    67  of the `packet_device` resource named "worker".
    68  
    69  ```shell
    70  $ terraform state rm 'packet_device.worker'
    71  ```
    72  
    73  A resource that doesn't use `count` or `for_each` has only one instance, so
    74  this is also the appropriate syntax to select that single instance.
    75  
    76  ## Example: Remove all Instances of a Resource in a Module
    77  
    78  To select a resource that you've defined in a child module you must specify
    79  the path of that module as part of the resource address:
    80  
    81  ```shell
    82  $ terraform state rm 'module.foo.packet_device.worker'
    83  ```
    84  
    85  ## Example: Remove all Instances of all Resources in a Module
    86  
    87  The following example will cause Terraform to "forget" all of the instances
    88  associated with all resources defined in all instances of the module named
    89  `foo`:
    90  
    91  ```shell
    92  $ terraform state rm 'module.foo'
    93  ```
    94  
    95  ## Example: Remove a Particular Instance of a Resource using `count`
    96  
    97  A resource defined with [the `count` meta-argument](/docs/language/meta-arguments/count.html)
    98  has multiple instances that are each identified by an integer. You can
    99  select a particular instance by including an explicit index in your given
   100  address:
   101  
   102  ```shell
   103  $ terraform state rm 'packet_device.worker[0]'
   104  ```
   105  
   106  Brackets (`[`, `]`) have a special meaning in some shells, so you may need to
   107  quote or escape the address in order to pass it literally to Terraform.
   108  The above shows the typical quoting syntax for Unix-style shells.
   109  
   110  ## Example: Remove a Particular Instance of a Resource using `for_each`
   111  
   112  A resource defined with [the `for_each` meta-argument](/docs/language/meta-arguments/for_each.html)
   113  has multiple instances that are each identified by an string. You can
   114  select a particular instance by including an explicit key in your given
   115  address.
   116  
   117  However, the syntax for strings includes quotes and the quote symbol often
   118  has special meaning in command shells, so you'll need to use the appropriate
   119  quoting and/or escaping syntax for the shell you are using. For example:
   120  
   121  Unix-style shells, such as on Linux or macOS:
   122  
   123  ```shell
   124  $ terraform state rm 'packet_device.worker["example"]'
   125  ```
   126  
   127  Windows Command Prompt (`cmd.exe`):
   128  
   129  ```shell
   130  $ terraform state rm packet_device.worker[\"example\"]
   131  ```
   132  
   133  PowerShell:
   134  
   135  ```shell
   136  $ terraform state rm 'packet_device.worker[\"example\"]'
   137  ```