You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+80-21
Original file line number
Diff line number
Diff line change
@@ -101,39 +101,94 @@ We literally have [*hundreds of terraform modules*][terraform_modules] that are
101
101
Instead pin to the release tag (e.g. `?ref=tags/x.y.z`) of one of our [latest releases](https://github.com/cloudposse/terraform-aws-tfstate-backend/releases).
102
102
103
103
104
-
1. Define the module in your `.tf` file using local state:
104
+
105
+
### Create
106
+
107
+
Follow this procedure just once to create your deployment.
108
+
109
+
1. Add the `terraform_state_backend` module to your `main.tf` file. The
110
+
comment will help you remember to follow this procedure in the future:
105
111
```hcl
112
+
# You cannot create a new backend by simply defining this and then
113
+
# immediately proceeding to "terraform apply". The S3 backend must
114
+
# be bootstrapped according to the simple yet essential procedure in
1.`terraform apply`. This will create the state bucket and locking table.
119
-
120
-
1. Then add a `backend` that uses the new bucket and table:
121
-
```hcl
122
-
backend "s3" {
123
-
region = "us-east-1"
124
-
bucket = "< the name of the S3 bucket >"
125
-
key = "terraform.tfstate"
126
-
dynamodb_table = "< the name of the DynamoDB table >"
127
-
encrypt = true
128
-
}
123
+
terraform_backend_config_file_path = "."
124
+
terraform_backend_config_file_name = "backend.tf"
125
+
force_destroy = false
129
126
}
130
127
128
+
# Your Terraform configuration
131
129
module "another_module" {
132
130
source = "....."
133
131
}
134
132
```
133
+
Module inputs `terraform_backend_config_file_path` and
134
+
`terraform_backend_config_file_name` control the name of the backend
135
+
definition file. Note that when `terraform_backend_config_file_path` is
136
+
empty (the default), no file is created.
137
+
138
+
1.`terraform init`. This downloads Terraform modules and providers.
139
+
140
+
1.`terraform apply -auto-approve`. This creates the state bucket and DynamoDB locking
141
+
table, along with anything else you have defined in your `*.tf` file(s). At
142
+
this point, the Terraform state is still stored locally.
143
+
144
+
Module `terraform_state_backend` also creates a new `backend.tf` file
145
+
that defines the S3 state backend. For example:
146
+
```hcl
147
+
backend "s3" {
148
+
region = "us-east-1"
149
+
bucket = "< the name of the S3 state bucket >"
150
+
key = "terraform.tfstate"
151
+
dynamodb_table = "< the name of the DynamoDB locking table >"
152
+
profile = ""
153
+
role_arn = ""
154
+
encrypt = true
155
+
}
156
+
```
157
+
158
+
Henceforth, Terraform will also read this newly-created backend definition
159
+
file.
160
+
161
+
1.`terraform init -force-copy`. Terraform detects that you want to move your
162
+
Terraform state to the S3 backend, and it does so per `-auto-approve`. Now the
163
+
state is stored in the S3 bucket, and the DynamoDB table will be used to lock
164
+
the state to prevent concurrent modification.
165
+
166
+
This concludes the one-time preparation. Now you can extend and modify your
167
+
Terraform configuration as usual.
135
168
136
-
1.`terraform init`. Terraform will detect that you're trying to move your state into S3 and ask, "Do you want to copy existing state to the new backend?" Enter "yes". Now state is stored in the bucket and the DynamoDB table will be used to lock the state to prevent concurrent modifications.
169
+
### Destroy
170
+
171
+
Follow this procedure to delete your deployment.
172
+
173
+
1. In `main.tf`, change the `terraform_state_backend` module arguments as
| terraform\_backend\_config\_file\_name | Name of terraform backend config file | `string` | `"terraform.tf"` | no |
209
-
| terraform\_backend\_config\_file\_path | The path to terrafrom project directory|`string`|`""`| no |
264
+
| terraform\_backend\_config\_file\_path | Directory for the terraform backend config file, usually `.`. The default is to create no file. | `string` | `""` | no |
210
265
| terraform\_backend\_config\_template\_file | The path to the template used to generate the config file | `string` | `""` | no |
211
266
| terraform\_state\_file | The path to the state file inside the bucket | `string` | `"terraform.tfstate"` | no |
212
267
| terraform\_version | The minimum required terraform version | `string` | `"0.12.2"` | no |
@@ -369,8 +424,8 @@ Check out [our other projects][github], [follow us on twitter][twitter], [apply
369
424
370
425
### Contributors
371
426
372
-
|[![Andriy Knysh][aknysh_avatar]][aknysh_homepage]<br/>[Andriy Knysh][aknysh_homepage]|[![Erik Osterman][osterman_avatar]][osterman_homepage]<br/>[Erik Osterman][osterman_homepage]|[![Maarten van der Hoef][maartenvanderhoef_avatar]][maartenvanderhoef_homepage]<br/>[Maarten van der Hoef][maartenvanderhoef_homepage]|[![Vladimir][SweetOps_avatar]][SweetOps_homepage]<br/>[Vladimir][SweetOps_homepage]|[![Chris Weyl][rsrchboy_avatar]][rsrchboy_homepage]<br/>[Chris Weyl][rsrchboy_homepage]|
373
-
|---|---|---|---|---|
427
+
| [![Andriy Knysh][aknysh_avatar]][aknysh_homepage]<br/>[Andriy Knysh][aknysh_homepage] | [![Erik Osterman][osterman_avatar]][osterman_homepage]<br/>[Erik Osterman][osterman_homepage] | [![Maarten van der Hoef][maartenvanderhoef_avatar]][maartenvanderhoef_homepage]<br/>[Maarten van der Hoef][maartenvanderhoef_homepage] | [![Vladimir][SweetOps_avatar]][SweetOps_homepage]<br/>[Vladimir][SweetOps_homepage] | [![Chris Weyl][rsrchboy_avatar]][rsrchboy_homepage]<br/>[Chris Weyl][rsrchboy_homepage] | [![John McGehee][jmcgeheeiv_avatar]][jmcgeheeiv_homepage]<br/>[John McGehee][jmcgeheeiv_homepage] | [![Oliver L Schoenborn][schollii_avatar]][schollii_homepage]<br/>[Oliver L Schoenborn][schollii_homepage] |
1. `terraform apply`. This will create the state bucket and locking table.
73
-
74
-
1. Then add a `backend` that uses the new bucket and table:
75
-
```hcl
76
-
backend "s3" {
77
-
region = "us-east-1"
78
-
bucket = "< the name of the S3 bucket >"
79
-
key = "terraform.tfstate"
80
-
dynamodb_table = "< the name of the DynamoDB table >"
81
-
encrypt = true
82
-
}
77
+
terraform_backend_config_file_path = "."
78
+
terraform_backend_config_file_name = "backend.tf"
79
+
force_destroy = false
83
80
}
84
81
82
+
# Your Terraform configuration
85
83
module "another_module" {
86
84
source = "....."
87
85
}
88
86
```
87
+
Module inputs `terraform_backend_config_file_path` and
88
+
`terraform_backend_config_file_name` control the name of the backend
89
+
definition file. Note that when `terraform_backend_config_file_path` is
90
+
empty (the default), no file is created.
91
+
92
+
1. `terraform init`. This downloads Terraform modules and providers.
93
+
94
+
1. `terraform apply -auto-approve`. This creates the state bucket and DynamoDB locking
95
+
table, along with anything else you have defined in your `*.tf` file(s). At
96
+
this point, the Terraform state is still stored locally.
97
+
98
+
Module `terraform_state_backend` also creates a new `backend.tf` file
99
+
that defines the S3 state backend. For example:
100
+
```hcl
101
+
backend "s3" {
102
+
region = "us-east-1"
103
+
bucket = "< the name of the S3 state bucket >"
104
+
key = "terraform.tfstate"
105
+
dynamodb_table = "< the name of the DynamoDB locking table >"
106
+
profile = ""
107
+
role_arn = ""
108
+
encrypt = true
109
+
}
110
+
```
89
111
90
-
1. `terraform init`. Terraform will detect that you're trying to move your state into S3 and ask, "Do you want to copy existing state to the new backend?" Enter "yes". Now state is stored in the bucket and the DynamoDB table will be used to lock the state to prevent concurrent modifications.
91
-
112
+
Henceforth, Terraform will also read this newly-created backend definition
113
+
file.
114
+
115
+
1. `terraform init -force-copy`. Terraform detects that you want to move your
116
+
Terraform state to the S3 backend, and it does so per `-auto-approve`. Now the
117
+
state is stored in the S3 bucket, and the DynamoDB table will be used to lock
118
+
the state to prevent concurrent modification.
119
+
120
+
This concludes the one-time preparation. Now you can extend and modify your
121
+
Terraform configuration as usual.
122
+
123
+
### Destroy
124
+
125
+
Follow this procedure to delete your deployment.
126
+
127
+
1. In `main.tf`, change the `terraform_state_backend` module arguments as
Copy file name to clipboardExpand all lines: docs/terraform.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -50,7 +50,7 @@
50
50
| stage | Stage, e.g. 'prod', 'staging', 'dev', OR 'source', 'build', 'test', 'deploy', 'release' |`string`|`""`| no |
51
51
| tags | Additional tags (e.g. `map('BusinessUnit','XYZ')`|`map(string)`|`{}`| no |
52
52
| terraform\_backend\_config\_file\_name | Name of terraform backend config file |`string`|`"terraform.tf"`| no |
53
-
| terraform\_backend\_config\_file\_path | The path to terrafrom project directory|`string`|`""`| no |
53
+
| terraform\_backend\_config\_file\_path |Directory for the terraform backend config file, usually `.`. The default is to create no file.|`string`|`""`| no |
54
54
| terraform\_backend\_config\_template\_file | The path to the template used to generate the config file |`string`|`""`| no |
55
55
| terraform\_state\_file | The path to the state file inside the bucket |`string`|`"terraform.tfstate"`| no |
56
56
| terraform\_version | The minimum required terraform version |`string`|`"0.12.2"`| no |
0 commit comments