Skip to content

Commit 4d3b0bd

Browse files
committed
Add import
1 parent c442cd8 commit 4d3b0bd

File tree

3 files changed

+121
-7
lines changed

3 files changed

+121
-7
lines changed

content/terraform/v1.13.x/docs/language/block/stack/deploy/deployment.mdx

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -153,30 +153,31 @@ We recommend using the `destroy` argument to remove deployments to ensure your c
153153
- Data type: Boolean
154154
- Default: `false`
155155

156-
### `import`
156+
<!-- TODO: Clear this up when we have the migrate docs -->
157157

158-
The `import` argument lets you declare in configuration that the deployment can import existing infrastructure into its state before deploying.
158+
### `import`
159159

160+
The `tf-migrate` CLI can migrate the state of an existing HCP Terraform workspace to a Stack deployment. The `tf-migrate` CLI automatically sets the `import` argument to `true` when importing the state of an existing workspace to a specific deployment.
160161

161162
```hcl
162163
deployment "<LABEL>" {
163164
inputs = {
164165
<VARIABLE_NAME> = <VALUE>
165166
<VARIABLE_NAME_TWO> = <VALUE_TWO>
166167
}
167-
import = true
168+
import = <boolean>
168169
}
169170
```
170171

171-
The `tf-migrate` tool automatically sets the `import` argument to `true` when importing the state of an HCP Ter.
172+
Terraform migrate sets the `import` argument to let HCP Terraform know that the rest of the deployments in a Stack can continue plan as normal while the deployment with `import` is migrating state.
173+
174+
To learn more about migrating a workspace to a Stack deployment, refer to Terraform migrate](/terraform/migrate).
172175

173176
#### Summary
174177

175178
- Data type: Boolean
176179
- Default: `false`
177180

178-
179-
180181
## Examples
181182

182183
The following examples demonstrate common use cases for `deployment` blocks.
Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
page_title: Manage components and resources in Stacks
3+
description: |-
4+
Learn how to update your Stack component configuration to manage components. Also, learn how to manage resources within the Terraform modules that each component sources.
5+
---
6+
7+
# Manage components and resources in Stacks
8+
9+
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.
10+
11+
## Add components
12+
13+
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. You must specify the source module, inputs, and providers for each component. To learn more about the `component` refer to the [`component` block reference](/terraform/language/block/stack/component_configuration/component).
14+
15+
## Remove components
16+
17+
Stacks take a systematic approach to removing components from your configuration. You must use a dedicated `removed` block in your component configuration to ensure Terraform can properly remove your component and the resources associated with that component.
18+
19+
To remove a component, add a `removed` block to your component configuration specifying the component you want to remove. For example, if you want to remove the following `database` component:
20+
21+
<CodeBlockConfig filename="component.tfcomponent.hcl">
22+
23+
```hcl
24+
component "database" {
25+
source = "./modules/database"
26+
27+
inputs = {
28+
instance_class = "db.t3.micro"
29+
}
30+
31+
providers = {
32+
aws = provider.aws.main
33+
}
34+
}
35+
```
36+
</CodeBlockConfig>
37+
38+
You add a `removed` block that specifies the component to remove, module that component sources, and the providers that component uses. The `removed` block also tells Terraform to destroy the resources managed by a component.
39+
40+
<TIP>
41+
42+
Do not remove providers from your component configuration without first removing the components that require those providers. Terraform requires a component's providers to ensure it can successfully remove that component.
43+
44+
</TIP>
45+
46+
In the following example, Terraform removes the `database` component that sources from `./modules/database` and uses the `aws.main` provider:
47+
48+
```hcl
49+
component "database" {
50+
source = "./modules/database"
51+
52+
inputs = {
53+
instance_class = "db.t3.micro"
54+
}
55+
56+
providers = {
57+
aws = provider.aws.main
58+
}
59+
}
60+
61+
removed {
62+
source = "./modules/database"
63+
from = component.database
64+
65+
providers = {
66+
aws = provider.aws.main
67+
}
68+
}
69+
```
70+
71+
After you apply the configuration in HCP Terraform, Terraform removes the `database` component and its resources from the associated Stack deployments. You can then remove both the `component` block and the `removed` block from your component configuration file.
72+
73+
If your `component` block uses the `for_each` meta-argument to define multiple components, you can define a `removed` block with the `for_each` meta-argument to ensure Terraform destroys each component instance.
74+
75+
In the following example, the `removed` block iterates through `local.deprecated_components` to remove the `staging` components and corresponding resources:
76+
77+
```hcl
78+
locals {
79+
components = ["dev", "prod"]
80+
deprecated_components = ["staging"]
81+
}
82+
83+
component "env" {
84+
for_each = toset(local.components)
85+
86+
source = "../local-component"
87+
88+
providers = {
89+
#...
90+
}
91+
#...
92+
}
93+
94+
removed {
95+
for_each = toset(local.deprecated_components)
96+
from = component.env[each.key]
97+
98+
providers = {
99+
#...
100+
}
101+
}
102+
```
103+
104+
In the above example, you can delete a component by removing it from the `local.components` list and adding it to the `local.removed_components` list.
105+
106+
## Manage resources
107+
108+
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.
109+
110+
Use the following blocks in the Terraform configuration files that make up your module to manage individual resources:
111+
112+
- To remove a resource from your module, use the `removed` block. To learn more, refer to [Destroy a resource](/terraform/language/resources/destroy).
113+
- 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](/terraform/language/import).
114+
- To move a resource from one module to another, use the `moved` block. To learn more, refer to [Move a resource](/terraform/language/modules/develop/refactoring#move-a-resource-or-module).

content/terraform/v1.13.x/docs/language/stacks/deploy/conditions.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@ Add the `deployment_group` block to your deployment configuration to create a ne
2424
<CodeBlockConfig filename="deployments.tfdeploy.hcl">
2525

2626
```hcl
27-
2827
deployment_group "staging_group" {
2928
# ...
3029
}

0 commit comments

Comments
 (0)