removed block reference

The removed block specifies a resource to remove from state without changing the underlying infrastructure. Refer to Remove a resource from state for instructions.

Configuration model

The removed block supports the following arguments.

• removed   block
  • from   address
  • lifecycle   block | required
    • destroy   boolean
  • connection   block
  • provisioner "<TYPE>"   block
    • when   | keyword
    • command   string
    • interpreter   list
    • working_dir   string
    • on_failure   keyword
    • quiet   boolean
    • connection   block
    • inline   list | mutually exclusive with script and script
    • script   string | mutually exclusive with inline and scripts
    • scripts   list | mutually exclusive with inline and script

Complete configuration

The following removed block defines all supported arguments.

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.

removed {
  from = <TYPE>.<NAME>
}

For instructions on how to retrieve the address from state, refer to Inspect Infrastructure Commands Overview. For information about forming addresses, refer to 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.

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 for more information.

Summary

• Data type: Block.
• Default: None.

connection

The connection block specifies settings that let provisioners connect to resources you are removing.

You can add the connection block to either the removed block or the 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.

removed {
  # . . .
  connection {
    <settings for all provisioners in the resource>
  }
}

When added to a provisioner block, the connection block defines settings specific to the provisioner.

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 to Manage sensitive data 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.

The following table describes the arguments you can use in the connection block:

Summary

• Data type: Block.
• Default: None.

provisioner

The provisioner block defines actions to perform on the local machine or resource you are removing.

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 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:

Use the self type to reference provisioner block values when the provisioner is nested in a removed block. Refer to Block-Local Values for more information.

when

The when argument specifies a Terraform command that triggers actions specified in the provisioner.

resource {
  provisioner "local-exec" {
    when = <Terraform command>
  }
}

When you run the specified Terraform command, Terraform performs run the command specified in the command argument. Refer to 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.

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.

Only destroy-time provisioners are supported in removed blocks. As a result, you must include the when 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 argument. You can specify a relative path to the current working directory or an absolute path. The directory must already exist.

resource {
  provisioner "local-exec" {
    working_dir = "<path>"
  }
}

Only destroy-time provisioners are supported in removed blocks. As a result, you must include the when 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 argument.

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 are supported in removed blocks. As a result, you must include the when 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 argument.

resource {
  provisioner "local-exec" {
    environment {
      <KEY> = <VALUE>
    }
  }
}

Only destroy-time provisioners are supported in removed blocks. As a result, you must include the when in the provisioner block to configure all other provisioner arguments.

Summary

• Data type: Block.
• Default: None.

quiet

The quiet argument disables printing the command argument's output to stdout.

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 are supported in removed blocks. As a result, you must include the when 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.

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 are supported in removed blocks. As a result, you must include the when 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.

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 are supported in removed blocks. As a result, you must include the when 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.

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 are supported in removed blocks. As a result, you must include the when 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:

removed {
  from = aws_instance.example

  lifecycle {
    destroy = true
  }

  provisioner "local-exec" {
    when    = destroy
    command = "echo 'Instance ${self.id} has been destroyed.'"
  }
}