ruby-terraform 0.65.0.pre.12 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. checksums.yaml +4 -4
  2. data/Gemfile.lock +23 -17
  3. data/README.md +148 -414
  4. data/Rakefile +25 -0
  5. data/lib/ruby_terraform.rb +1365 -41
  6. data/lib/ruby_terraform/commands.rb +0 -2
  7. data/lib/ruby_terraform/commands/apply.rb +78 -4
  8. data/lib/ruby_terraform/commands/base.rb +13 -2
  9. data/lib/ruby_terraform/commands/destroy.rb +71 -4
  10. data/lib/ruby_terraform/commands/force_unlock.rb +33 -3
  11. data/lib/ruby_terraform/commands/format.rb +45 -2
  12. data/lib/ruby_terraform/commands/get.rb +35 -2
  13. data/lib/ruby_terraform/commands/graph.rb +48 -2
  14. data/lib/ruby_terraform/commands/import.rb +98 -3
  15. data/lib/ruby_terraform/commands/init.rb +84 -3
  16. data/lib/ruby_terraform/commands/login.rb +26 -2
  17. data/lib/ruby_terraform/commands/logout.rb +23 -2
  18. data/lib/ruby_terraform/commands/output.rb +34 -2
  19. data/lib/ruby_terraform/commands/plan.rb +72 -3
  20. data/lib/ruby_terraform/commands/providers.rb +30 -2
  21. data/lib/ruby_terraform/commands/providers_lock.rb +72 -3
  22. data/lib/ruby_terraform/commands/providers_mirror.rb +44 -2
  23. data/lib/ruby_terraform/commands/providers_schema.rb +21 -2
  24. data/lib/ruby_terraform/commands/refresh.rb +70 -3
  25. data/lib/ruby_terraform/commands/show.rb +26 -3
  26. data/lib/ruby_terraform/commands/state_list.rb +54 -3
  27. data/lib/ruby_terraform/commands/state_move.rb +64 -6
  28. data/lib/ruby_terraform/commands/state_pull.rb +24 -2
  29. data/lib/ruby_terraform/commands/state_push.rb +49 -3
  30. data/lib/ruby_terraform/commands/state_remove.rb +55 -7
  31. data/lib/ruby_terraform/commands/state_replace_provider.rb +39 -6
  32. data/lib/ruby_terraform/commands/state_show.rb +26 -2
  33. data/lib/ruby_terraform/commands/taint.rb +63 -2
  34. data/lib/ruby_terraform/commands/untaint.rb +55 -2
  35. data/lib/ruby_terraform/commands/validate.rb +51 -6
  36. data/lib/ruby_terraform/commands/workspace_delete.rb +29 -7
  37. data/lib/ruby_terraform/commands/workspace_list.rb +21 -6
  38. data/lib/ruby_terraform/commands/workspace_new.rb +28 -7
  39. data/lib/ruby_terraform/commands/workspace_select.rb +23 -7
  40. data/lib/ruby_terraform/commands/workspace_show.rb +17 -2
  41. data/lib/ruby_terraform/options.rb +1 -1
  42. data/lib/ruby_terraform/options/definition.rb +6 -2
  43. data/lib/ruby_terraform/options/definitions.rb +12 -3
  44. data/lib/ruby_terraform/options/{common.rb → global.rb} +2 -1
  45. data/lib/ruby_terraform/options/types.rb +0 -1
  46. data/lib/ruby_terraform/options/types/flag.rb +8 -4
  47. data/lib/ruby_terraform/options/types/standard.rb +20 -6
  48. data/lib/ruby_terraform/version.rb +1 -1
  49. data/ruby_terraform.gemspec +3 -2
  50. metadata +25 -14
  51. data/lib/ruby_terraform/commands/clean.rb +0 -26
  52. data/lib/ruby_terraform/commands/remote_config.rb +0 -25
  53. data/lib/ruby_terraform/options/types/base.rb +0 -19
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1aa09973516552eca1e86476c1a12da268f105a8a78d87ac4366c59e8051e5d4
4
- data.tar.gz: ccfc2afc555c53f30fb61f429e33d9451102aba3d3a39b68e69ebb546406bc10
3
+ metadata.gz: 8e6f8748d4275fd6af4f13f53eb3440b10012bc05895b1f3e7bf1e4f29614720
4
+ data.tar.gz: 315faa89600f7f8d31b92b47e66dc500a71bd5ea5c92ab214195a37738f65237
5
5
  SHA512:
6
- metadata.gz: ed32ad7e4f4b6f98a78cea339ddfc2464d11a892a9ad8d4402a9af7a7d2224bae3cd75384c1a85c210a12efecd40b22bd85b575031ecef390c6da637150756e9
7
- data.tar.gz: 98304e9c66825275ee0891b244bbe5ee47c3073f0b2c845afbb8cd30bd1297e791ab8367e151ebaf9b2452c0490ad3b55e013416b92f49b6af0dcc305b6ff190
6
+ metadata.gz: a30d286d7565203a82a299f210df2c6293999b11b66e6547cf721610648621550552a50d95b6a54363cdbb7414e1f66f00628b3f3086149162deb5df9d6df77f
7
+ data.tar.gz: 2225cfc75f9233fd5017eee048913ce850c37f85d636f1057786a29c683088a5408c897b3a9845c13381613ac1b12b8b2045d7f69682a0af7081c7b225717f4c
data/Gemfile.lock CHANGED
@@ -1,14 +1,14 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- ruby-terraform (0.65.0.pre.12)
5
- immutable-struct (>= 2.4)
6
- lino (>= 2.5)
4
+ ruby-terraform (1.0.0)
5
+ immutable-struct (~> 2.4)
6
+ lino (~> 2.7)
7
7
 
8
8
  GEM
9
9
  remote: https://rubygems.org/
10
10
  specs:
11
- activesupport (6.1.3.1)
11
+ activesupport (6.1.3.2)
12
12
  concurrent-ruby (~> 1.0, >= 1.0.2)
13
13
  i18n (>= 1.6, < 2)
14
14
  minitest (>= 5.1)
@@ -22,14 +22,18 @@ GEM
22
22
  concurrent-ruby (1.1.8)
23
23
  diff-lcs (1.4.4)
24
24
  docile (1.3.5)
25
- excon (0.79.0)
25
+ excon (0.81.0)
26
26
  faker (2.17.0)
27
27
  i18n (>= 1.6, < 2)
28
- faraday (1.3.0)
28
+ faraday (1.4.1)
29
+ faraday-excon (~> 1.1)
29
30
  faraday-net_http (~> 1.0)
31
+ faraday-net_http_persistent (~> 1.1)
30
32
  multipart-post (>= 1.2, < 3)
31
- ruby2_keywords
33
+ ruby2_keywords (>= 0.0.4)
34
+ faraday-excon (1.1.0)
32
35
  faraday-net_http (1.0.1)
36
+ faraday-net_http_persistent (1.1.0)
33
37
  ffi (1.15.0)
34
38
  formatador (0.2.5)
35
39
  gem-release (2.2.1)
@@ -52,7 +56,7 @@ GEM
52
56
  i18n (1.8.10)
53
57
  concurrent-ruby (~> 1.0)
54
58
  immutable-struct (2.4.1)
55
- lino (2.5.0)
59
+ lino (2.7.0)
56
60
  hamster (~> 3.0)
57
61
  open4 (~> 1.3)
58
62
  listen (3.5.1)
@@ -66,12 +70,12 @@ GEM
66
70
  notiffany (0.1.3)
67
71
  nenv (~> 0.1)
68
72
  shellany (~> 0.0)
69
- octokit (4.20.0)
73
+ octokit (4.21.0)
70
74
  faraday (>= 0.9)
71
75
  sawyer (~> 0.8.0, >= 0.5.3)
72
76
  open4 (1.3.4)
73
77
  parallel (1.20.1)
74
- parser (3.0.1.0)
78
+ parser (3.0.1.1)
75
79
  ast (~> 2.4.1)
76
80
  pry (0.14.1)
77
81
  coderay (~> 1.1)
@@ -117,20 +121,20 @@ GEM
117
121
  diff-lcs (>= 1.2.0, < 2.0)
118
122
  rspec-support (~> 3.10.0)
119
123
  rspec-support (3.10.2)
120
- rubocop (1.12.1)
124
+ rubocop (1.14.0)
121
125
  parallel (~> 1.10)
122
126
  parser (>= 3.0.0.0)
123
127
  rainbow (>= 2.2.2, < 4.0)
124
128
  regexp_parser (>= 1.8, < 3.0)
125
129
  rexml
126
- rubocop-ast (>= 1.2.0, < 2.0)
130
+ rubocop-ast (>= 1.5.0, < 2.0)
127
131
  ruby-progressbar (~> 1.7)
128
132
  unicode-display_width (>= 1.4.0, < 3.0)
129
- rubocop-ast (1.4.1)
130
- parser (>= 2.7.1.5)
133
+ rubocop-ast (1.5.0)
134
+ parser (>= 3.0.1.1)
131
135
  rubocop-rake (0.5.1)
132
136
  rubocop
133
- rubocop-rspec (2.2.0)
137
+ rubocop-rspec (2.3.0)
134
138
  rubocop (~> 1.0)
135
139
  rubocop-ast (>= 1.1.0)
136
140
  ruby-progressbar (1.11.0)
@@ -146,12 +150,13 @@ GEM
146
150
  simplecov-html (~> 0.11)
147
151
  simplecov_json_formatter (~> 0.1)
148
152
  simplecov-html (0.12.3)
149
- simplecov_json_formatter (0.1.2)
153
+ simplecov_json_formatter (0.1.3)
150
154
  sshkey (2.0.0)
151
155
  thor (1.1.0)
152
156
  tzinfo (2.0.4)
153
157
  concurrent-ruby (~> 1.0)
154
158
  unicode-display_width (2.0.0)
159
+ yard (0.9.26)
155
160
  zeitwerk (2.4.2)
156
161
 
157
162
  PLATFORMS
@@ -174,6 +179,7 @@ DEPENDENCIES
174
179
  rubocop-rspec (~> 2.2)
175
180
  ruby-terraform!
176
181
  simplecov (~> 0.21)
182
+ yard (~> 0.9)
177
183
 
178
184
  BUNDLED WITH
179
- 2.2.16
185
+ 2.2.17
data/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # RubyTerraform
2
2
 
3
3
  A simple wrapper around the Terraform binary to allow execution from within
4
- a Ruby program or Rakefile.
4
+ a Ruby program, RSpec test or Rakefile.
5
5
 
6
6
 
7
7
  ## Installation
@@ -23,468 +23,161 @@ Or install it yourself as:
23
23
 
24
24
  ## Usage
25
25
 
26
- RubyTerraform needs to know where the terraform binary is located before it
27
- can do anything. By default, RubyTerraform looks on the path however this can
28
- be configured with:
26
+ To require `RubyTerraform`:
29
27
 
30
28
  ```ruby
31
- RubyTerraform.configure do |config|
32
- config.binary = 'vendor/terraform/bin/terraform'
33
- end
34
- ```
35
-
36
- In addition, each command that requires the terraform binary (all except
37
- `clean`) takes a `binary` keyword argument at initialisation that overrides the
38
- global configuration value.
39
-
40
- Currently, there is partial support for the following commands:
41
- * `RubyTerraform::Commands::Clean`: clean up all locally held terraform state
42
- and modules.
43
- * `RubyTerraform::Commands::Init`: executes `terraform init`
44
- * `RubyTerraform::Commands::Get`: executes `terraform get`
45
- * `RubyTerraform::Commands::Plan`: executes `terraform plan`
46
- * `RubyTerraform::Commands::Apply`: executes `terraform apply`
47
- * `RubyTerraform::Commands::Show`: executes `terraform show`
48
- * `RubyTerraform::Commands::Destroy`: executes `terraform destroy`
49
- * `RubyTerraform::Commands::Output`: executes `terraform output`
50
- * `RubyTerraform::Commands::Refresh`: executes `terraform refresh`
51
- * `RubyTerraform::Commands::Import`: executes `terraform import`
52
- * `RubyTerraform::Commands::RemoteConfig`: executes `terraform remote config`
53
- * `RubyTerraform::Commands::Format`: executes `terraform fmt`
54
- * `RubyTerraform::Commands::Validate`: executes `terraform validate`
55
- * `RubyTerraform::Commands::Workspace`: executes `terraform workspace`
56
-
57
- ### RubyTerraform::Commands::Clean
58
-
59
- The clean command can be called in the following ways:
60
-
61
- ```ruby
62
- RubyTerraform.clean
63
- RubyTerraform.clean(directory: 'infra/.terraform')
64
- RubyTerraform::Commands::Clean.new(directory: 'infra/.terraform').execute
65
- RubyTerraform::Commands::Clean.new.execute(directory: 'infra/.terraform')
29
+ require 'ruby-terraform'
66
30
  ```
67
31
 
68
- When called, it removes the contents of the .terraform directory in the
69
- working directory by default. If another directory is specified, it instead
70
- removes the specified directory.
71
-
72
-
73
- ### RubyTerraform::Commands::Init
32
+ ### Supported versions and commands
74
33
 
75
- The init command will initialise a terraform environment. It can be called in
76
- the following ways:
77
-
78
- ```ruby
79
- RubyTerraform.init
80
- RubyTerraform.init(from_module: 'some/module/path', path: 'infra/module')
81
- RubyTerraform::Commands::Init.new.execute
82
- RubyTerraform::Commands::Init.new.execute(
83
- from_module: 'some/module/path',
84
- path: 'infra/module')
85
- ```
34
+ `RubyTerraform` supports all commands and options up to Terraform 0.15, except
35
+ `terraform console`, `terraform test` and `terraform version`.
86
36
 
87
- The init command supports the following options passed as keyword arguments:
88
- * `from_module`: the source module to use to initialise; required if `path` is
89
- specified
90
- * `path`: the path to initialise.
91
- * `backend`: `true`/`false`, whether or not to configure the backend.
92
- * `get`: `true`/`false`, whether or not to get dependency modules.
93
- * `backend_config`: a map of backend specific configuration parameters.
94
- * `no_color`: whether or not the output from the command should be in color;
95
- defaults to `false`.
96
- * `plugin_dir`: directory containing plugin binaries. Overrides all default;
97
- search paths for plugins and prevents the automatic installation of plugins.
37
+ ### Getting started
98
38
 
39
+ There are a couple of ways to call Terraform using `RubyTerraform`.
99
40
 
100
- ### RubyTerraform::Commands::Get
41
+ Firstly, the `RubyTerraform` module includes class methods for each of the
42
+ supported Terraform commands. Each class method takes a parameter hash
43
+ containing options to pass to Terraform.
101
44
 
102
- The get command will fetch any modules referenced in the provided terraform
103
- configuration directory. It can be called in the following ways:
104
-
105
- ```ruby
106
- RubyTerraform.get(directory: 'infra/networking')
107
- RubyTerraform::Commands::Get.new.execute(directory: 'infra/networking')
108
- ```
109
-
110
- The get command supports the following options passed as keyword arguments:
111
- * `directory`: the directory containing terraform configuration; required.
112
- * `update`: whether or not already downloaded modules should be updated;
113
- defaults to `false`.
114
- * `no_color`: whether or not the output from the command should be in color;
115
- defaults to `false`.
116
-
117
-
118
- ### RubyTerraform::Commands::Plan
119
-
120
- The plan command will generate the execution plan in the provided
121
- configuration directory. It can be called in the following ways:
45
+ For example, to save the plan of changes for a Terraform configuration located
46
+ under `infra/network` to a file called `network.tfplan` whilst providing some
47
+ vars:
122
48
 
123
49
  ```ruby
124
50
  RubyTerraform.plan(
125
- directory: 'infra/networking',
126
- vars: {
127
- region: 'eu-central'
128
- })
129
- RubyTerraform::Commands::Plan.new.execute(
130
- directory: 'infra/networking',
51
+ chdir: 'infra/network',
52
+ out: 'network.tfplan',
131
53
  vars: {
132
54
  region: 'eu-central'
133
- })
55
+ },
56
+ var_file: 'defaults.tfvars'
57
+ )
134
58
  ```
135
59
 
136
- The plan command supports the following options passed as keyword arguments:
137
- * `directory`: the directory containing terraform configuration; required.
138
- * `vars`: a map of vars to be passed in to the terraform configuration.
139
- * `var_file`: the path to a terraform var file; if both `var_file` and
140
- `var_files` are provided, all var files will be passed to terraform.
141
- * `var_files`: an array of paths to terraform var files; if both `var_file` and
142
- `var_files` are provided, all var files will be passed to terraform.
143
- * `target`: the address of a resource to target; if both `target` and
144
- `targets` are provided, all targets will be passed to terraform.
145
- * `targets`: and array of resource addresses to target; if both `target` and
146
- `targets` are provided, all targets will be passed to terraform.
147
- * `state`: the path to the state file in which to store state; defaults to
148
- terraform.tfstate in the working directory or the remote state if configured.
149
- * `plan`: the name of the file in which to save the generated plan.
150
- * `input`: when `false`, will not ask for input for variables not directly set;
151
- defaults to `true`.
152
- * `destroy`: when `true`, a plan will be generated to destroy all resources
153
- managed by the given configuration and state; defaults to `false`.
154
- * `no_color`: whether or not the output from the command should be in color;
155
- defaults to `false`.
156
-
157
-
158
- ### RubyTerraform::Commands::Apply
159
-
160
- The apply command applies terraform configuration in the provided terraform
161
- configuration directory. It can be called in the following ways:
60
+ To apply the generated plan of changes:
162
61
 
163
62
  ```ruby
164
63
  RubyTerraform.apply(
165
- directory: 'infra/networking',
166
- vars: {
167
- region: 'eu-central'
168
- })
169
- RubyTerraform::Commands::Apply.new.execute(
170
- directory: 'infra/networking',
64
+ chdir: 'infra/network',
65
+ plan: 'network.tfplan',
171
66
  vars: {
172
67
  region: 'eu-central'
173
- })
68
+ },
69
+ var_file: 'defaults.tfvars'
70
+ )
174
71
  ```
175
72
 
176
- The apply command supports the following options passed as keyword arguments:
177
- * `directory`: the directory containing terraform configuration; required.
178
- * `vars`: a map of vars to be passed in to the terraform configuration.
179
- * `var_file`: the path to a terraform var file; if both `var_file` and
180
- `var_files` are provided, all var files will be passed to terraform.
181
- * `var_files`: an array of paths to terraform var files; if both `var_file` and
182
- `var_files` are provided, all var files will be passed to terraform.
183
- * `target`: the address of a resource to target; if both `target` and
184
- `targets` are provided, all targets will be passed to terraform.
185
- * `targets`: and array of resource addresses to target; if both `target` and
186
- `targets` are provided, all targets will be passed to terraform.
187
- * `state`: the path to the state file in which to store state; defaults to
188
- terraform.tfstate in the working directory or the remote state if configured.
189
- * `backup`: the path to the backup file in which to store the state backup.
190
- * `input`: when `false`, will not ask for input for variables not directly set;
191
- defaults to `true`.
192
- * `no_backup`: when `true`, no backup file will be written; defaults to `false`.
193
- * `no_color`: whether or not the output from the command should be in color;
194
- defaults to `false`.
195
- * `auto_approve`: if `true`, the command applys without prompting the user to
196
- confirm the changes; defaults to `false`.
197
-
198
-
199
- ### RubyTerraform::Commands::Show
200
-
201
- The show command produces human-readable output from a state file or a plan
202
- file. It can be called in the following ways:
203
-
204
- ```ruby
205
- RubyTerraform.show(
206
- path: 'infra/networking')
207
- RubyTerraform::Commands::Show.new.execute(
208
- path: 'infra/networking')
209
- ```
210
-
211
- The show command supports the following options passed as keyword arguments:
212
- * `path`: the path to a state or plan file; required.
213
- * `no_color`: whether or not the output from the command should be in color;
214
- defaults to `false`.
215
- * `module_depth`: the depth of modules to show in the output; defaults to
216
- showing all modules.
217
- * `json`: whether or not the output from the command should be in json format;
218
- defaults to `false`.
219
-
220
- ### RubyTerraform::Commands::Destroy
221
-
222
- The destroy command destroys all resources defined in the terraform
223
- configuration in the provided terraform configuration directory. It can be
224
- called in the following ways:
73
+ ...and to destroy the resulting resources:
225
74
 
226
75
  ```ruby
227
76
  RubyTerraform.destroy(
228
- directory: 'infra/networking',
77
+ chdir: 'infra/network',
229
78
  vars: {
230
79
  region: 'eu-central'
231
- })
232
- RubyTerraform::Commands::Destroy.new.execute(
233
- directory: 'infra/networking',
234
- vars: {
235
- region: 'eu-central'
236
- })
237
- ```
238
-
239
- The destroy command supports the following options passed as keyword arguments:
240
- * `directory`: the directory containing terraform configuration; required.
241
- * `vars`: a map of vars to be passed in to the terraform configuration.
242
- * `var_file`: the path to a terraform var file; if both `var_file` and
243
- `var_files` are provided, all var files will be passed to terraform.
244
- * `var_files`: an array of paths to terraform var files; if both `var_file` and
245
- `var_files` are provided, all var files will be passed to terraform.
246
- * `target`: the address of a resource to target; if both `target` and
247
- `targets` are provided, all targets will be passed to terraform.
248
- * `targets`: and array of resource addresses to target; if both `target` and
249
- `targets` are provided, all targets will be passed to terraform.
250
- * `state`: the path to the state file containing the current state; defaults to
251
- terraform.tfstate in the working directory or the remote state if configured.
252
- * `force`: if `true`, the command destroys without prompting the user to confirm
253
- the destruction; defaults to `false`.
254
- * `backup`: the path to the backup file in which to store the state backup.
255
- * `no_backup`: when `true`, no backup file will be written; defaults to `false`.
256
- * `no_color`: whether or not the output from the command should be in color;
257
- defaults to `false`.
258
-
259
-
260
- ### RubyTerraform::Commands::Output
261
-
262
- The output command retrieves an output from a state file. It can be called in
263
- the following ways:
264
-
265
- ```ruby
266
- RubyTerraform.output(name: 'vpc_id')
267
- RubyTerraform::Commands::Destroy.new.execute(name: 'vpc_id')
80
+ },
81
+ var_file: 'defaults.tfvars'
82
+ )
268
83
  ```
269
84
 
270
- The output command supports the following options passed as keyword arguments:
271
- * `name`: the name of the output to retrieve; required.
272
- * `state`: the path to the state file containing the current state; defaults to
273
- terraform.tfstate in the working directory or the remote state if configured.
274
- * `no_color`: whether or not the output from the command should be in color;
275
- defaults to `false`.
276
- * `module`: the name of a module to retrieve output from.
277
-
278
-
279
- ### RubyTerraform::Commands::Refresh
85
+ Additionally, `RubyTerraform` allows command instances to be constructed and
86
+ invoked separately. This is useful when you need to override global
87
+ configuration on a command by command basis or when you need to pass a command
88
+ around.
280
89
 
281
- The refresh command will reconcile state with resources found in the target
282
- environment. It can be called in the following ways:
90
+ Using the command class approach, the equivalent plan invocation above can be
91
+ achieved using:
283
92
 
284
93
  ```ruby
285
- RubyTerraform.refresh(
286
- directory: 'infra/networking',
94
+ command = RubyTerraform::Commands::Plan.new
95
+ command.execute(
96
+ chdir: 'infra/network',
97
+ out: 'network.tfplan',
287
98
  vars: {
288
99
  region: 'eu-central'
289
- })
290
- RubyTerraform::Commands::Refresh.new.execute(
291
- directory: 'infra/networking',
292
- vars: {
293
- region: 'eu-central'
294
- })
100
+ },
101
+ var_file: 'defaults.tfvars'
102
+ )
295
103
  ```
296
104
 
297
- The refresh command supports the following options passed as keyword arguments:
298
- * `directory`: the directory containing terraform configuration; required.
299
- * `vars`: a map of vars to be passed in to the terraform configuration.
300
- * `var_file`: the path to a terraform var file; if both `var_file` and
301
- `var_files` are provided, all var files will be passed to terraform.
302
- * `var_files`: an array of paths to terraform var files; if both `var_file` and
303
- `var_files` are provided, all var files will be passed to terraform.
304
- * `target`: the address of a resource to target; if both `target` and
305
- `targets` are provided, all targets will be passed to terraform.
306
- * `targets`: and array of resource addresses to target; if both `target` and
307
- `targets` are provided, all targets will be passed to terraform.
308
- * `state`: the path to the state file in which to store state; defaults to
309
- terraform.tfstate in the working directory or the remote state if configured.
310
- * `input`: when `false`, will not ask for input for variables not directly set;
311
- defaults to `true`.
312
- * `no_color`: whether or not the output from the command should be in color;
313
- defaults to `false`.
314
-
315
-
316
- ### RubyTerraform::Commands::Import
317
-
318
- The import command imports existing infrastructure into your terraform state.
319
- It can be called in the following ways:
105
+ See the [API docs](https://infrablocks.github.io/ruby_terraform/index.html) for
106
+ more details on the supported commands.
320
107
 
321
- ```ruby
322
- RubyTerraform.import(
323
- directory: 'infra/networking',
324
- address: 'a.resource.address',
325
- id: 'a-resource-id',
326
- vars: {
327
- region: 'eu-central'
328
- }))
329
- RubyTerraform::Commands::Import.new.execute(
330
- directory: 'infra/networking',
331
- address: 'a.resource.address',
332
- id: 'a-resource-id',
333
- vars: {
334
- region: 'eu-central'
335
- }))
336
- ```
108
+ ### Parameters
337
109
 
338
- The import command supports the following options passed as keyword arguments:
339
- * `directory`: the directory containing terraform configuration; required.
340
- * `address`: a valid resource address; required.
341
- * `id`: id of resource being imported; required.
342
- * `vars`: a map of vars to be passed in to the terraform configuration.
343
- * `var_file`: the path to a terraform var file; if both `var_file` and
344
- `var_files` are provided, all var files will be passed to terraform.
345
- * `var_files`: an array of paths to terraform var files; if both `var_file` and
346
- `var_files` are provided, all var files will be passed to terraform.
347
- * `input`: when `false`, will not ask for input for variables not directly set;
348
- defaults to `true`.
349
- * `state`: the path to the state file containing the current state; defaults to
350
- terraform.tfstate in the working directory or the remote state if configured.
351
- * `no_backup`: when `true`, no backup file will be written; defaults to `false`.
352
- * `backup`: the path to the backup file in which to store the state backup.
353
- * `no_color`: whether or not the output from the command should be in color;
354
- defaults to `false`.
355
-
356
-
357
- ### RubyTerraform::Commands::RemoteConfig
358
-
359
- The remote config command configures storage of state using a remote backend. It
360
- has been deprecated and since removed from terraform but is retained in this
361
- library for backwards compatibility. It can be called in the following ways:
110
+ The parameter hash passed to each command, whether via the class methods or the
111
+ `#execute` method, supports all the options available on the corresponding
112
+ Terraform command. There are a few different types of options depending on what
113
+ Terraform expects to receive:
114
+
115
+ * `Boolean` options, accepting `true` or `false`, such as `:input` or `:lock`;
116
+ * `String` options, accepting a single string value, such as `:state` or
117
+ `:target`;
118
+ * `Array<String>` options, accepting an array of strings, such as `:var_files`
119
+ `:targets`; and
120
+ * `Hash<String,Object>` options, accepting a hash of key value pairs, where the
121
+ value might be complex, such as `:vars` and `:backend_config`.
122
+
123
+ For all options that allow multiple values, both a singular and a plural option
124
+ key are supported. For example, to specify multiple var files during a plan:
362
125
 
363
126
  ```ruby
364
- RubyTerraform.remote_config(
365
- backend: 's3',
366
- backend_config: {
367
- bucket: 'example-state-bucket',
368
- key: 'infra/terraform.tfstate',
369
- region: 'eu-west-2'
370
- })
371
- RubyTerraform::Commands::RemoteConfig.new.execute(
372
- backend: 's3',
373
- backend_config: {
374
- bucket: 'example-state-bucket',
375
- key: 'infra/terraform.tfstate',
376
- region: 'eu-west-2'
377
- })
127
+ RubyTerraform.plan(
128
+ chdir: 'infra/network',
129
+ out: 'network.tfplan',
130
+ var_file: 'defaults.tfvars',
131
+ var_files: %w[environment.tfvars secrets.tfvars]
132
+ )
378
133
  ```
379
134
 
380
- The remote config command supports the following options passed as keyword
381
- arguments:
382
- * `backend`: the type of backend to use; required.
383
- * `backend_config`: a map of backend specific configuration parameters;
384
- required.
385
- * `no_color`: whether or not the output from the command should be in color;
386
- defaults to `false`.
135
+ In this case, all three var files are passed to Terraform.
387
136
 
388
- ### RubyTerraform::Commands::Format
137
+ Some options have aliases. For example, the `:out` option can also be provided
138
+ as `:plan` for symmetry with other terraform commands. However, in such
139
+ situations only one of the aliases should be used in the provided parameters
140
+ hash.
389
141
 
390
- The format command formats the terraform directory specified. It can be called in the following ways:
142
+ See the [API docs](https://infrablocks.github.io/ruby_terraform/index.html) for
143
+ a more complete listing of available parameter options.
391
144
 
392
- ```ruby
393
- RubyTerraform.format(
394
- directory: 'infra/networking',
395
- vars: {
396
- region: 'eu-central'
397
- })
398
- RubyTerraform::Commands::Format.new.execute(
399
- directory: 'infra/networking',
400
- vars: {
401
- region: 'eu-central'
402
- })
403
- ```
145
+ ### Configuration
404
146
 
405
- The format command supports the following options passed as keyword arguments:
406
- * `directory`: the directory containing terraform configuration to be formatted; required.
407
- * `recursive`: Processes files in subdirectories;
408
- defaults to `false`.
409
- * `list`: Don't list files whose formatting differs;
410
- defaults to `false`.
411
- * `write`: Don't write to source files;
412
- defaults to `false`.
413
- * `check`: Checks if the input is formatted, exit status will be 0 if all input is properly formatted and non zero otherwise;
414
- defaults to `false`.
415
- * `diff`: Displays a diff of the formatting changes;
416
- defaults to `false`.
417
- * `no_color`: whether or not the output from the command should be in color;
418
- defaults to `false`.
419
-
420
- ### RubyTerraform::Commands::Validate
147
+ `RubyTerraform` uses sensible defaults for all configuration options. However,
148
+ there are a couple of ways to override the defaults when they are sufficient.
149
+
150
+ #### Binary
421
151
 
422
- The validate command validates terraform configuration in the provided terraform
423
- configuration directory. It can be called in the following ways:
152
+ By default, `RubyTerraform` looks for the Terraform binary on the system path.
153
+ To globally configure a specific binary location:
424
154
 
425
155
  ```ruby
426
- RubyTerraform.validate(
427
- directory: 'infra/networking',
428
- vars: {
429
- region: 'eu-central'
430
- })
431
- RubyTerraform::Commands::Validate.new.execute(
432
- directory: 'infra/networking',
433
- vars: {
434
- region: 'eu-central'
435
- })
156
+ RubyTerraform.configure do |config|
157
+ config.binary = 'vendor/terraform/bin/terraform'
158
+ end
436
159
  ```
437
160
 
438
- The validate command supports the following options passed as keyword arguments:
439
- * `directory`: the directory containing terraform configuration; required.
440
- * `vars`: a map of vars to be passed in to the terraform configuration.
441
- * `var_file`: the path to a terraform var file; if both `var_file` and
442
- `var_files` are provided, all var files will be passed to terraform.
443
- * `var_files`: an array of paths to terraform var files; if both `var_file` and
444
- `var_files` are provided, all var files will be passed to terraform.
445
- * `no_color`: whether or not the output from the command should be in color;
446
- defaults to `false`.
447
- * `check_variables`: if `true`, the command checks whether all variables have
448
- been provided; defaults to `true`.
449
- * `json`: whether or not the output from the command should be in json format;
450
- defaults to `false`.
451
-
452
- ### RubyTerraform::Commands::Workspace
453
-
454
- The `workspace` command configures
455
- [Terraform Workspaces](https://www.terraform.io/docs/state/workspaces.html#using-workspaces).
456
- It can be used as follows:
161
+ To configure the Terraform binary on a command by command basis, for example for
162
+ the `Plan` command:
457
163
 
458
164
  ```ruby
459
- RubyTerraform.workspace(operation: 'list')
460
- RubyTerraform.workspace(operation: 'new', workspace: 'staging')
461
- RubyTerraform.workspace(operation: 'select', workspace: 'staging')
462
- RubyTerraform.workspace(operation: 'list')
463
- RubyTerraform.workspace(operation: 'select', workspace: 'default')
464
- RubyTerraform.workspace(operation: 'delete', workspace: 'staging')
165
+ command = RubyTerraform::Commands::Plan.new(
166
+ binary: 'vendor/terraform/bin/terraform'
167
+ )
168
+ command.execute(
169
+ # ...
170
+ )
465
171
  ```
466
172
 
467
- arguments:
468
- * `directory`: the directory containing terraform configuration, the default is
469
- the current path.
470
- * `operation`: `list`, `select`, `new` or `delete`. default `list`.
471
- * `workspace`: Workspace name.
173
+ #### Logging
472
174
 
175
+ By default, `RubyTerraform` 's own log statements are logged to `$stdout` with
176
+ level `info`.
473
177
 
474
- ## Configuration
178
+ To globally configure a custom logger:
475
179
 
476
- In addition to configuring the location of the terraform binary, RubyTerraform
477
- offers configuration of logging and standard streams. By default standard
478
- streams map to `$stdin`, `$stdout` and `$stderr` and all logging goes to
479
- `$stdout`.
480
-
481
- ### Logging
482
-
483
- By default, RubyTerraform logs to `$stdout` with level `info`.
484
-
485
- To configure a custom logger:
486
-
487
- ``` ruby
180
+ ```ruby
488
181
  require 'logger'
489
182
 
490
183
  logger = Logger.new($stdout)
@@ -495,13 +188,13 @@ RubyTerraform.configure do |config|
495
188
  end
496
189
  ```
497
190
 
498
- RubyTerraform supports logging to multiple different outputs at once,
191
+ `RubyTerraform` supports logging to multiple different outputs at once,
499
192
  for example:
500
193
 
501
- ``` ruby
194
+ ```ruby
502
195
  require 'logger'
503
196
 
504
- log_file = Logger::LogDevice.new('/foo/bar.log') # results in a file with sync true in the background
197
+ log_file = Logger::LogDevice.new('/foo/bar.log')
505
198
  logger = Logger.new(RubyTerraform::MultiIO.new(STDOUT, log_file), level: :debug)
506
199
 
507
200
  RubyTerraform.configure do |config|
@@ -511,18 +204,37 @@ RubyTerraform.configure do |config|
511
204
  config.stderr = logger
512
205
  end
513
206
  ```
514
- > Creating the Logger with a file this way (using `Logger::LogDevice`), guarantees that the buffer content will be saved/written, as it sets **implicit flushing**.
207
+ > Creating the Logger with a file this way (using `Logger::LogDevice`),
208
+ > guarantees that the buffer content will be saved/written, as it sets
209
+ > **implicit flushing**.
210
+
211
+ Configured in this way, any logging performed by `RubyTerraform` will log to
212
+ both `STDOUT` and the provided `log_file`.
515
213
 
516
- Configured in this way, any logging performed by RubyTerraform will log to both
517
- `STDOUT` and the provided `log_file`.
214
+ To configure the logger on a command by command basis, for example for the
215
+ `Show` command:
518
216
 
519
- ### Standard Streams
217
+ ```ruby
218
+ require 'logger'
520
219
 
521
- By default, RubyTerraform uses streams `$stdin`, `$stdout` and `$stderr`.
220
+ logger = Logger.new($stdout)
221
+ logger.level = Logger::DEBUG
222
+
223
+ command = RubyTerraform::Commands::Show.new(
224
+ logger: logger
225
+ )
226
+ command.execute(
227
+ # ...
228
+ )
229
+ ```
230
+
231
+ #### Standard streams
232
+
233
+ By default, `RubyTerraform` uses streams `$stdin`, `$stdout` and `$stderr`.
522
234
 
523
235
  To configure custom output and error streams:
524
236
 
525
- ``` ruby
237
+ ```ruby
526
238
  log_file = File.open('path/to/some/ruby_terraform.log', 'a')
527
239
 
528
240
  RubyTerraform.configure do |config|
@@ -535,7 +247,7 @@ In this way, both outputs will be redirected to `log_file`.
535
247
 
536
248
  Similarly, a custom input stream can be configured:
537
249
 
538
- ``` ruby
250
+ ```ruby
539
251
  require 'stringio'
540
252
 
541
253
  input = StringIO.new("user\ninput\n")
@@ -548,6 +260,28 @@ end
548
260
  In this way, terraform can be driven by input from somewhere other than
549
261
  interactive input from the terminal.
550
262
 
263
+ To configure the standard streams on a command by command basis, for example for
264
+ the `Init` command:
265
+
266
+ ```ruby
267
+ require 'logger'
268
+
269
+ input = StringIO.new("user\ninput\n")
270
+ log_file = File.open('path/to/some/ruby_terraform.log', 'a')
271
+
272
+ command = RubyTerraform::Commands::Init.new(
273
+ stdin: input,
274
+ stdout: log_file,
275
+ stderr: log_file
276
+ )
277
+ command.execute(
278
+ # ...
279
+ )
280
+ ```
281
+
282
+ ## Documentation
283
+
284
+ * [API docs](https://infrablocks.github.io/ruby_terraform/index.html)
551
285
 
552
286
  ## Development
553
287