Manage components and resources in Stacks

After provisioning the infrastructure declared in your Stack, you can update the Stack component configuration to manage its components as well as the resources within modules that each component sources.

Add components

In your tfcomponent.hcl file, configure an additional component block for each top-level module you want to include in the Stack. Each component block must include a source argument that specifies the module that the component sources its configuration from. You must also include any input variables the module requires and provider configurations.

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

Remove components

Terraform systematically removes Stack components from your configuration. To ensure that Terraform can successfully remove a component, the component's provider must be available. Do not remove providers from your component configuration without first removing the components that require those providers.

Complete the following steps to remove a component from your Stack:

Update configuration:
- Delete the component block for the component you want to remove.
- Add a removed block that specifies the component, the component source module, and the component's provider configuration. Specify all component details so that Terraform can properly destroy all associated resources.
Push your configuration changes to HCP Terraform and apply the changes to your Stack.

The following configuration is an example database component you want to remove:

component.tfcomponent.hcl

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

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

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

To remove the database component, add a corresponding removed block that specifies the component to remove, the module that component sources, and the providers that component uses:

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

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

After applying 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. Modules 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. Refer to Creating Modules for more information.

Import a resource

Import resources into modules that Terraform then passes into Stacks components. In addition to importing the resource to the module, you must also declare it in the deployment configuration. When you re-apply the configuration, Terraform provisions instances of the resource across your Stack deployments.

In each deployment block of your tfdeploy.hcl configuration file, add the resource to the inputs argument map. The following example declares an input called bucket_name for the dev and prod deployment environments:

deployment "dev" {
  inputs = {
    ..
    bucket_name = "<name-for-dev>"
    ..
  }
}

deployment "prod" {
  inputs = {
    ..
    bucket_name = "<name-for-prod>"
    ..
  }
}

Add an input variable to your tfcomponent.hcl configuration file that Terraform passes into the component. Refer to Use input variables to add module arguments for instructions on how to define input variables. The following example declares the bucket_name variable:
```
variable "bucket_name" {
  type = string
}
```
In the tfcomponent.hcl configuration file, add a reference to the input variable you declared in the previous step. Reference the variable in the component block for the module you want to import the resource to. The following example references the bucket_name variable for the component that manages resources from the ./components/microservices module:
```
component "instance" {
  source = "./components/microservice"

  inputs = {
    bucket_name = var.bucket_name
    # other inputs
  }
}
```
In the destination module, add an import configuration to specify which resources to import and the destination addresses for them. You can add the configuration to the module's root configuration file, but we recommend creating an import.tf file to keep imports organized. Refer to the import block reference page for more information.
The following example imports an S3 bucket to the ./components/microservice module, which is consumed by the component "instance" block
./components/microservices/import.tf
```
variable "bucket_name" {}

resource "aws_s3_bucket" "example" {
  bucket = var.bucket_name
}

import {
  to = aws_s3_bucket.example
  id = var.bucket_name
}
```
Start a new run in HCP Terraform or Terraform Enterprise to redeploy the infrastructure with the newly imported resource.

You can reuse the same component to import different S3 buckets per deployment by changing the bucket_name input in each environment.

Remove a resource from your module

Deleting a resource configuration in the source module removes it from Terraform management and decommissions the actual infrastructure. Alternatively, you can add a removed block to the source module configuration to remove a resource from Terraform management without decommissioning the actual infrastructure object. Refer to Destroy a resource for more information.

Change a resource address

You can move a resource from one module to another by adding the moved block to the source module configuration. To learn more, refer to Move a resource.