A simple wrapper around the Terraform binary to allow execution from within a Ruby program, RSpec test or Rakefile.
Add this line to your application's Gemfile:
gem 'ruby-terraform'
And then execute:
$ bundle
Or install it yourself as:
$ gem install ruby-terraform
To require RubyTerraform
:
require 'ruby-terraform'
RubyTerraform
supports all commands and options up to Terraform 0.15, except
terraform console
, terraform test
and terraform version
.
There are a couple of ways to call Terraform using RubyTerraform
.
Firstly, the RubyTerraform
module includes class methods for each of the
supported Terraform commands. Each class method takes a parameter hash
containing options to pass to Terraform.
For example, to save the plan of changes for a Terraform configuration located
under infra/network
to a file called network.tfplan
whilst providing some
vars:
RubyTerraform.plan(
chdir: 'infra/network',
out: 'network.tfplan',
vars: {
region: 'eu-central'
},
var_file: 'defaults.tfvars'
)
To apply the generated plan of changes:
RubyTerraform.apply(
chdir: 'infra/network',
plan: 'network.tfplan',
vars: {
region: 'eu-central'
},
var_file: 'defaults.tfvars'
)
...and to destroy the resulting resources:
RubyTerraform.destroy(
chdir: 'infra/network',
vars: {
region: 'eu-central'
},
var_file: 'defaults.tfvars'
)
Each class method also accepts a second hash argument of invocation options to
use at command invocation time. Currently, the only supported option is
:environment
which allows environment variables to be exposed to Terraform.
For example, to apply a configuration with trace level logging:
RubyTerraform.apply(
{
chdir: 'infra/network',
plan: 'network.tfplan',
vars: {
region: 'eu-central'
},
var_file: 'defaults.tfvars'
},
{
environment: {
'TF_LOG' => 'trace'
}
}
)
Additionally, RubyTerraform
allows command instances to be constructed and
invoked separately. This is useful when you need to override global
configuration on a command by command basis or when you need to pass a command
around.
Using the command class approach, the equivalent plan invocation above can be achieved using:
command = RubyTerraform::Commands::Plan.new
command.execute(
chdir: 'infra/network',
out: 'network.tfplan',
vars: {
region: 'eu-central'
},
var_file: 'defaults.tfvars'
)
As with the class methods, the #execute
method accepts a second hash argument
of invocation options allowing an environment to be specified.
See the API docs for
the
RubyTerraform
module
or the
RubyTerraform::Commands
module
more details on the supported commands.
The parameter hash passed to each command, whether via the class methods or the
#execute
method, supports all the options available on the corresponding
Terraform command. There are a few different types of options depending on what
Terraform expects to receive:
Boolean
options, accepting true
or false
, such as :input
or :lock
;String
options, accepting a single string value, such as :state
or
:target
;Array<String>
options, accepting an array of strings, such as :var_files
or :targets
; andHash<String,Object>
options, accepting a hash of key value pairs, where the
value might be complex, such as :vars
and :backend_config
.For all options that allow multiple values, both a singular and a plural option key are supported. For example, to specify multiple var files during a plan:
RubyTerraform.plan(
chdir: 'infra/network',
out: 'network.tfplan',
var_file: 'defaults.tfvars',
var_files: %w[environment.tfvars secrets.tfvars]
)
In this case, all three var files are passed to Terraform.
Some options have aliases. For example, the :out
option can also be provided
as :plan
for symmetry with other terraform commands. However, in such
situations only one of the aliases should be used in the provided parameters
hash.
See the API docs for a more complete listing of available parameter options.
RubyTerraform
uses sensible defaults for all configuration options. However,
there are a couple of ways to override the defaults when they are sufficient.
By default, RubyTerraform
looks for the Terraform binary on the system path.
To globally configure a specific binary location:
RubyTerraform.configure do |config|
config.binary = 'vendor/terraform/bin/terraform'
end
To configure the Terraform binary on a command by command basis, for example for
the Plan
command:
command = RubyTerraform::Commands::Plan.new(
binary: 'vendor/terraform/bin/terraform'
)
command.execute(
# ...
)
By default, RubyTerraform
's own log statements are logged to $stdout
with
level info
.
To globally configure a custom logger:
require 'logger'
logger = Logger.new($stdout)
logger.level = Logger::DEBUG
RubyTerraform.configure do |config|
config.logger = logger
end
RubyTerraform
supports logging to multiple different outputs at once,
for example:
require 'logger'
file_device = Logger::LogDevice.new('/foo/bar.log')
stdout_device = Logger::LogDevice.new(STDOUT)
multi_io = RubyTerraform::MultiIO.new(file_device, stdout_device)
logger = Logger.new(multi_io, level: :debug)
RubyTerraform.configure do |config|
config.binary = '/binary/path/terraform'
config.logger = logger
config.stdout = multi_io
config.stderr = multi_io
end
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.
Configured in this way, any logging performed by RubyTerraform
will log to
both STDOUT
and to the specified file.
To configure the logger on a command by command basis, for example for the
Show
command:
require 'logger'
logger = Logger.new($stdout)
logger.level = Logger::DEBUG
command = RubyTerraform::Commands::Show.new(
logger: logger
)
command.execute(
# ...
)
By default, RubyTerraform
uses streams $stdin
, $stdout
and $stderr
.
To configure custom output and error streams:
log_file = File.open('path/to/some/ruby_terraform.log', 'a')
RubyTerraform.configure do |config|
config.stdout = log_file
config.stderr = log_file
end
In this way, both outputs will be redirected to log_file
.
Similarly, a custom input stream can be configured:
require 'stringio'
input = StringIO.new("user\ninput\n")
RubyTerraform.configure do |config|
config.stdin = input
end
In this way, terraform can be driven by input from somewhere other than interactive input from the terminal.
To configure the standard streams on a command by command basis, for example for
the Init
command:
require 'logger'
input = StringIO.new("user\ninput\n")
log_file = File.open('path/to/some/ruby_terraform.log', 'a')
command = RubyTerraform::Commands::Init.new(
stdin: input,
stdout: log_file,
stderr: log_file
)
command.execute(
# ...
)
To install dependencies and run the build, run the pre-commit build:
./go
This runs all unit tests and other checks including coverage and code linting / formatting.
To run only the unit tests, including coverage:
./go test:unit
To attempt to fix any code linting / formatting issues:
./go library:fix
To check for code linting / formatting issues without fixing:
./go library:check
You can also run bin/console
for an interactive prompt that will allow you to
experiment.
To encrypt a GPG key for use by CircleCI:
openssl aes-256-cbc \
-e \
-md sha1 \
-in ./config/secrets/ci/gpg.private \
-out ./.circleci/gpg.private.enc \
-k "<passphrase>"
To check decryption is working correctly:
openssl aes-256-cbc \
-d \
-md sha1 \
-in ./.circleci/gpg.private.enc \
-k "<passphrase>"
Bug reports and pull requests are welcome on GitHub at https://github.com/infrablocks/ruby_terraform. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.