Manage components and resources in Stacks

Stacks are made up of components, and each component includes a Terraform module as its source. Learn how to add and remove components from a Stack, and how to manage resources within the module that each component sources.

Add components

The component block defines the pieces that make up your Stack. Add a component block for each top-level module you want to include in the Stack. When you define a component block, you specify the module that component sources its configuration from, any input variables the module requires, and provider configurations.

To learn more about the component refer to the component block reference.

Remove components

Stacks take a systematic approach to removing components from your configuration. To remove a component from your Stack, you must do the following:

1. Delete the component block for the component you want to remove.
2. Add a removed block specifying the component you want to remove.
3. Push your configuration changes to HCP Terraform and apply the changes to your Stack.

In the removed block, you specify the component you want to remove, the module that component sources, and that component's provider configurations. Specifying all of a component's details ensures that Terraform can properly destroy all the resources associated with that component.

For example, if you want to remove the following database component:

component "database" {
  source = "./modules/database"

  inputs = {
    instance_class = "db.t3.micro"
  }

  providers = {
    aws = provider.aws.main
  }
}

Add a removed block that specifies the component to remove, the module that component sources, and the providers that component uses.

The following example deletes the database component block and adds a removed block to tell Terraform to remove that component from your Stack:

removed {
  source = "./modules/database"
  from   = component.database

  providers = {
    aws = provider.aws.main
  }
}

After you apply the configuration in HCP Terraform, Terraform removes the database component and its resources from the associated Stack deployments. You can then delete the removed block from your component configuration file.

Remove multiple components

If your component block uses the for_each meta-argument to define multiple components, use the for_each meta-argument in a removed block to let Terraform destroy multiple component instances. Using for_each in a removed block lets you remove all of the instances of a component, or a subset of those instances.

To remove all of the instances of a component, duplicate the same for_each expression in the removed block that you use in the component block. For example, to remove all of the instances of env components:

component "env" {
  for_each = ["dev", "staging"]

  source = "../local-component"

  providers = {
    #...
  }
  #...
}

Remove the env component block and add a removed block that uses the same for_each expression:

removed {
  for_each = ["dev", "staging"]
  from = component.env[each.key]

  providers = {
    #...
  }
}

After you apply the configuration in HCP Terraform, Terraform removes all of the instances of the env component and its resources from the associated Stack deployments. You can then delete the removed block from your component configuration file.

If you want to remove a subset of component instances, you must keep the component block that defines the instances you want to keep. In the following example, the removed block iterates through local.deprecated_components to remove the staging components and corresponding resources:

locals {
  components = ["dev", "prod"]
  deprecated_components = ["staging"]
}

component "env" {
  for_each = toset(local.components)

  source = "../local-component"

  providers = {
    #...
  }
  #...
}

removed {
  for_each = toset(local.deprecated_components)
  from = component.env[each.key]

  providers = {
    #...
  }
}

After you apply the configuration in HCP Terraform, Terraform removes the staging component but the dev and prod components remain in your Stack. You can additionally delete more components by removing them from the local.components list and adding them to the local.removed_components list.

Manage resources

A Stack component sources its configuration from a module. Module use traditional Terraform configuration files that end with .tf. To interact with individual resources in a component, you must update the module your component sources its configuration from.

Use the following blocks in the Terraform configuration files that make up your module to manage individual resources:

• To remove a resource from your module, use the removed block. To learn more, refer to Destroy a resource.
• To tell Terraform to take over the management of an existing infrastructure resource, use the import block. To learn more, refer to Import a resource.
• To move a resource from one module to another, use the moved block. To learn more, refer to Move a resource.