added removed block reference

content/terraform/v1.12.x/data/language-nav-data.json

@@ -1139,6 +1139,10 @@
         "title": "Output block",
         "path": "block/output"
       },
+      {
+        "title": "removed",
+        "path": "block/removed"
+      },
       {
         "title": "resource",
         "path": "block/resource"

content/terraform/v1.12.x/docs/language/block/removed.mdx

@@ -0,0 +1,387 @@
+---
+page_title: removed block reference
+description: Learn how to configure a `removed` block, which removes a resource from state.
+---
+
+# `removed` block reference
+
+The `removed` block specifies a resource to remove from state. Refer to [Remove a resource](/terraform/language/resources/remove) for instructions on removing resources from both state and configuration.
+
+## Configuration model
+
+The `removed` block supports the following arguments.
+
+- [`removed`](#removed) & nbsp block
+  - [`from`](#from) &nbsp address
+  - [`lifecycle`](#lifecycle) &nbsp block | required
+    - [`destroy`](#lifecycle) &nbsp boolean 
+  - [`connection`](#connection): &nbsp block
+  - [`provisioner "<TYPE>"`](#provisioner) &nbsp block 
+    - [`when`](#when) &nbsp | keyword 
+    - [`command`](#command) &nbsp string
+    - [`interpreter`](#interpreter) &nbsp list
+    - [`working_dir`](#working_dir) &nbsp string
+    - [`on_failure`](#on_failure) &nbsp keyword  
+    - [`quiet`](#quiet) &nbsp boolean
+    - [`connection`](#connection): &nbsp block
+    - [`inline`](#inline) &nbsp list | mutually exclusive with `script` and `script`
+    - [`script`](#script) &nbsp string | mutually exclusive with `inline` and `scripts`
+    - [`scripts`](#script) &nbsp list | mutually exclusive with `inline` and `script`  
+
+## Complete configuration
+
+The following `removed` block defines all supported arguments. 
+
+```hcl
+removed {
+  from = "<resource.address>"
+  lifecycle {
+    destroy = < true || false >
+  }
+  connection {
+    <connection-settings>
+  }
+  provisioner "<TYPE>" {
+    when = destroy
+    <provisioner-type-arguments>  
+  }
+}
+```
+
+## Specification
+
+A `removed` block supports the following configuration.
+
+### `removed` 
+
+The `removed` block instructs Terraform to remove a resource from state. When you remove a resource from state, Terraform no longer manages the actual infrastructure that the configuration represents. 
+
+#### Summary
+
+- Data type: Block.
+- Default: None.
+
+### `from`
+
+The `from` argument specifies the address of the resource you want to remove. 
+
+```hcl
+removed {
+  from = <TYPE>.<NAME>
+}
+```
+
+For instructions on how to retrieve the address from state, refer to [Inspect Infrastructure Commands Overview](/terraform/cli/inspect). For information about forming addresses, refer to [Resource addressing](/terraform/cli/state/resource-addressing).
+
+#### Summary
+
+- Data type: String.
+- Default: None.
+- This argument is required. 
+
+### `lifecycle`
+
+The `lifecycle` block defines rules for how Terraform removes the resource. For `removed` blocks, the only supported `lifecycle` argument is `destroy`. 
+
+```hcl
+removed {
+  # …
+  lifecycle { 
+    destroy = <boolean>
+  }
+}
+```
+
+By default, Terraform removes the resource from state and destroys the actual resource. Set `destroy` to `false` to remove the resource from state without destroying the actual resource. This allows you to hand off management responsibilities to another tool or team after using Terraform for the initial provisioning.   
+
+The `lifecycle` block is a meta-argument. Meta-arguments are built-in arguments that control how Terraform creates resources. Refer to [Meta-arguments](/terraform/language/meta-arguments) for more information.
+
+#### Summary
+
+- Data type: Block.
+- Default: None.
+
+### `connection`
+
+The `connection` block specifies settings that let provisioners connect to resources you are removing.
+
+<Warning>
+
+We recommend using configuration management tools to perform actions on the local or remote machine instead of using provisioners. Refer to [Provisioners](/terraform/language/manage-resource/run-command) for more information.
+
+</Warning>
+
+You can add the `connection` block to either the [`removed`](#removed) block or the [`provisioner`](#provisioner) block nested in the `removed` block. When added to the `removed` block, the `connection` block sets default connection settings for all provisioners defined for the resource you are removing. This lets provisioners connect to the remote resource during removal.
+
+```hcl
+removed {
+  # . . .
+  connection {
+    <settings for all provisioners in the resource>
+  }
+}
+``` 
+
+When added to a `provisioner` block, the `connection` block defines settings specific to the provisioner.
+
+```hcl
+removed {
+  # . . .
+  provisioner "<TYPE>" {
+    # . . .
+    connection {
+      <settings for all provisioners in the resource>
+    }
+  }
+}
+```
+
+For SSH connections, Terraform does not validate SSH host keys by default. To validate SSH host keys, you can establish a separate mechanism for key distribution and explicitly set the `host_key` argument to verify against a specific key or signing CA.
+
+You can use ephemeral values for arguments in the `connection` block. Refer [Ephemerality in resources](/terraform/language/resources/ephemeral) for more information.
+
+Expressions in `connection` blocks cannot refer to their parent resource by resource address. References create dependencies, and referring to a resource by resource address within its own block would create a dependency cycle. Instead, use the `self` object in expressions to refer to the `connection` block's parent block, including all of its attributes. For example, use `self.public_ip` to reference the `public_ip` attribute in an `aws_instance`. 
+
+<span id="connection-arguments"/>
+
+The following table describes the arguments you can use in the `connection` block:
+
+@include 'provisioner-connection-settings.mdx'
+
+#### Summary
+
+- Data type: Block.
+- Default: None.
+
+### `provisioner`
+
+The `provisioner` block defines actions to perform on the local machine or resource you are removing. 
+
+```hcl
+removed {
+  # . . .
+  provisioner "<TYPE>" {
+    <arguments>
+  }
+}
+```
+
+You can declare either `local-exec` or `remote-exec` as the provisioner type. The `local-exec` provisioner performs operations on the machine where Terraform is running. The `remote-exec` type performs operations on the resource you are removing. 
+
+The [`when`](#when) argument is required to configure a provisioner nested in a `removed` block. The following table describes the arguments you can specify for each type of provisioner:
+
+| Provisioner type | Arguments |
+|---| -- |
+| `local-exec` | <li>[`command`](#command)</li> <li>[`working_dir`](#working_dir)</li> <li>[`interpreter`](#interpreter)</li> <li>[`quiet`](#quiet)</li> <li>[`connection`](#connection)</li>  <li>[`on_failure`](#on_failure)</li> |
+| `remote-exec` | <li>[`inline`](#inline)</li> <li>[`script`](#script)</li> <li>[`scripts`](#scripts)</li> |
+| All types | <li>[`when`](#when). This argument is required to use any other argument in a `provisioner` block nested in a `removed` block. </li> <li>[`connection`](#connection)</li>  <li>[`on_failure`](#on_failure)</li> |
+
+Use the `self` type to reference `provisioner` block values when the provisioner is nested in a `removed` block. Refer to [Block-Local Values](/terraform/language/expressions/references#block-local-values) for more information. 
+
+### `when`
+
+The `when` argument specifies a Terraform command that triggers actions specified in the provisioner. 
+
+```hcl
+resource {
+  provisioner "local-exec" {
+    when = <Terraform command>
+  }
+}
+```
+
+When you run the specified Terraform command, Terraform performs run the command specified in the [`command`](#command) argument. Refer to [Destroy-time provisioners](terraform/language/resources/provisioners/syntax#destroy-time-provisioners) for instructions on using the `when` argument.
+
+#### Summary
+
+- Data type: Terraform command.
+- Default: None.
+- Required to use any other `provisioner` argument. 
+
+
+### `command`
+
+The `command` argument specifies a command for a local executable to run. You can specify an absolute path or a relative path to the current working directory. 
+
+```hcl
+resource {
+  provisioner "local-exec" {
+    command = "<path>"
+  }
+}
+```
+
+Terraform evaluates the command in a local shell and can use environment variables for variable substitution. We do not recommend using Terraform variables for variable substitution because doing so can lead to shell injection vulnerabilities. Instead, you should pass Terraform variables to a command through the environment parameter and use environment variable substitution instead. Refer to the following OWASP article for more information about injection flaws: [Code Injection](https://owasp.org/www-community/attacks/Code_Injection).
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+#### Summary
+
+- Data type: String.
+- Default: None.
+- This argument is required in the `provisioner "local-exec"` block.
+
+### `working_dir`
+
+The `working_dir` block specifies the working directory where Terraform executes the command specified in the the [`command`](#command) argument. You can specify a relative path to the current working directory or an absolute path. The directory must already exist.
+
+```hcl
+resource {
+  provisioner "local-exec" {
+    working_dir = "<path>"
+  }
+}
+```
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+#### Summary
+
+- Data type: String.
+- Default: None.
+
+### `interpreter`
+
+The `interpreter` block specifies a list of interpreter arguments for running the executable specified in the [`command`](#command) argument. 
+
+```hcl
+resource {
+  provisioner "local-exec" {
+    interpreter = [ "<path/to/interpreter>", "<command argument>" ]
+  }
+}
+```
+
+The first argument in the list is a path to the interpreter. You can specify a relative path to the current working directory or an absolute path. If you do not specify an interpreter, Terraform uses operating system defaults.
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+#### Summary
+
+- Data type: List.
+- Default: None.
+
+### `environment`
+
+The `environment` block specifies a block of key value pairs that represent the environment for running the command specified in the [`command`](#command) argument. 
+
+```hcl
+resource {
+  provisioner "local-exec" {
+    environment {
+      <KEY> = <VALUE>
+    }
+  }
+}
+```
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+#### Summary
+
+- Data type: Block.
+- Default: None.
+
+### `quiet`
+
+The `quiet` argument disables printing the [`command`](#command) argument's output to `stdout`.
+
+
+```hcl
+resource {
+  provisioner "local-exec" {
+    quiet = <boolean>
+  }
+}
+```
+
+When `quiet` is set to `true`, Terraform prints `"Suppressed by quiet=true"` to `stdout`. Terraform still prints the output of the command.
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+#### Summary
+
+- Data type: Boolean.
+- Default: None.
+
+### `inline`
+
+Specifies a list of command strings for the remote resource to run.
+
+
+```hcl
+removed {
+  # ...
+  provisioner "remote-exec" {
+    inline = [ "<command>" ]
+  }
+}
+```
+
+The provisioner uses the remote resource's default shell unless you specify a shell as the first command, for example `#!/bin/bash`. You cannot add an `inline` argument in the same provisioner with `script` or `scripts`.
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+#### Summary
+
+- Data type: List.
+- Default: None.
+
+### `script`
+
+Specifies the relative or absolute path to a script on the local machine to copy and execute on the remote resource.  
+
+
+```hcl
+removed {
+  # ...
+  provisioner "remote-exec" {
+    scripts = "<path-to-script>"
+  }
+}
+```
+
+You cannot add a `script` argument in the same provisioner with `inline` or `scripts`.
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) <!--URL TBD -->are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+#### Summary
+
+- Data type: String.
+- Default: None.
+
+### `scripts`
+
+Specifies a list of relative or absolute paths to scripts on the local machine to copy and execute on the remote resource.  
+
+
+```hcl
+removed {
+  # ...
+  provisioner "remote-exec" {
+    scripts = [ "<path-to-script>" ]
+  }
+}
+```
+You cannot add a `scripts` argument in the same provisioner with `inline` or `script`.
+
+Only [destroy-time provisioners](/terraform/language/{TBD}#destroy-time-provisioners) <!--URL TBD -->are supported in `removed` blocks. As a result, you must include the [`when`](#argument) in the `provisioner` block to configure all other provisioner arguments.  
+
+## Example
+
+The following example includes a provisioner that prints a message on the local machine indicating that Terraform has destroyed the resource:
+
+```hcl
+removed {
+  from = aws_instance.example
+
+  lifecycle {
+    destroy = true
+  }
+
+  provisioner "local-exec" {
+    when    = destroy
+    command = "echo 'Instance ${self.id} has been destroyed.'"
+  }
+}
+```