{"id":13505821,"url":"https://github.com/infrablocks/ruby_terraform","last_synced_at":"2025-05-15T12:05:00.150Z","repository":{"id":17800062,"uuid":"82499648","full_name":"infrablocks/ruby_terraform","owner":"infrablocks","description":"A simple Ruby wrapper for invoking terraform commands.","archived":false,"fork":false,"pushed_at":"2025-05-05T07:50:36.000Z","size":1361,"stargazers_count":110,"open_issues_count":1,"forks_count":33,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-05T08:37:49.128Z","etag":null,"topics":["command-line","ruby","ruby-gem","ruby-library","rubygem","terraform"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infrablocks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-02-20T00:20:55.000Z","updated_at":"2025-05-05T07:50:38.000Z","dependencies_parsed_at":"2023-01-16T21:45:30.131Z","dependency_job_id":"dc57710a-f8f3-4d58-8318-2fd11686ddaa","html_url":"https://github.com/infrablocks/ruby_terraform","commit_stats":{"total_commits":647,"total_committers":27,"mean_commits":"23.962962962962962","dds":0.5610510046367851,"last_synced_commit":"060c8d5ebea30458d1cc4c051352fefb25c65ec1"},"previous_names":[],"tags_count":209,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fruby_terraform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fruby_terraform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fruby_terraform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fruby_terraform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infrablocks","download_url":"https://codeload.github.com/infrablocks/ruby_terraform/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","ruby","ruby-gem","ruby-library","rubygem","terraform"],"created_at":"2024-08-01T00:01:14.664Z","updated_at":"2025-05-15T12:04:55.137Z","avatar_url":"https://github.com/infrablocks.png","language":"Ruby","funding_links":[],"categories":["Tools","Ruby"],"sub_categories":["Miscellaneous","Community providers"],"readme":"# RubyTerraform\n\nA simple wrapper around the Terraform binary to allow execution from within\na Ruby program, RSpec test or Rakefile.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'ruby-terraform'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install ruby-terraform\n\n## Usage\n\nTo require `RubyTerraform`:\n\n```ruby\nrequire 'ruby-terraform'\n```\n\n### Supported versions and commands\n\n`RubyTerraform` supports all commands and options up to Terraform 1.5.7, except\n`terraform console`, `terraform test` and `terraform version`.\n\n### Getting started\n\nThere are a couple of ways to call Terraform using `RubyTerraform`.\n\nFirstly, the `RubyTerraform` module includes class methods for each of the\nsupported Terraform commands. Each class method takes a parameter hash\ncontaining options to pass to Terraform.\n\nFor example, to save the plan of changes for a Terraform configuration located\nunder `infra/network` to a file called `network.tfplan` whilst providing some\nvars:\n\n```ruby\nRubyTerraform.plan(\n  chdir: 'infra/network',\n  out: 'network.tfplan',\n  vars: {\n    region: 'eu-central'\n  },\n  var_file: 'defaults.tfvars'\n)\n```\n\nTo apply the generated plan of changes:\n\n```ruby\nRubyTerraform.apply(\n  chdir: 'infra/network',\n  plan: 'network.tfplan',\n  vars: {\n    region: 'eu-central'\n  },\n  var_file: 'defaults.tfvars'\n)\n```\n\n...and to destroy the resulting resources:\n\n```ruby\nRubyTerraform.destroy(\n  chdir: 'infra/network',\n  vars: {\n    region: 'eu-central'\n  },\n  var_file: 'defaults.tfvars'\n)\n```\n\nEach class method also accepts a second hash argument of invocation options to\nuse at command invocation time. Currently, the only supported option is\n`:environment` which allows environment variables to be exposed to Terraform.\n\nFor example, to apply a configuration with trace level logging:\n\n```ruby\nRubyTerraform.apply(\n  {\n    chdir: 'infra/network',\n    plan: 'network.tfplan',\n    vars: {\n      region: 'eu-central'\n    },\n    var_file: 'defaults.tfvars'\n  },\n  {\n    environment: {\n      'TF_LOG' =\u003e 'trace'\n    }\n  }\n)\n```\n\nAdditionally, `RubyTerraform` allows command instances to be constructed and\ninvoked separately. This is useful when you need to override global\nconfiguration on a command by command basis or when you need to pass a command\naround.\n\nUsing the command class approach, the equivalent plan invocation above can be\nachieved using:\n\n```ruby\ncommand = RubyTerraform::Commands::Plan.new\ncommand.execute(\n  chdir: 'infra/network',\n  out: 'network.tfplan',\n  vars: {\n    region: 'eu-central'\n  },\n  var_file: 'defaults.tfvars'\n)\n```\n\nAs with the class methods, the `#execute` method accepts a second hash argument\nof invocation options allowing an environment to be specified.\n\nSee the [API docs](https://infrablocks.github.io/ruby_terraform/index.html) for\nthe\n[`RubyTerraform` module](https://infrablocks.github.io/ruby_terraform/RubyTerraform.html)\nor the\n[`RubyTerraform::Commands` module](https://infrablocks.github.io/ruby_terraform/RubyTerraform/Commands.html)\nmore details on the supported commands.\n\n### Parameters\n\nThe parameter hash passed to each command, whether via the class methods or the\n`#execute` method, supports all the options available on the corresponding\nTerraform command. There are a few different types of options depending on what\nTerraform expects to receive:\n\n* `Boolean` options, accepting `true` or `false`, such as `:input` or `:lock`;\n* `String` options, accepting a single string value, such as `:state` or\n  `:target`;\n* `Array\u003cString\u003e` options, accepting an array of strings, such as `:var_files`\n  or `:targets`; and\n* `Hash\u003cString,Object\u003e` options, accepting a hash of key value pairs, where the\n  value might be complex, such as `:vars` and `:backend_config`.\n\nFor all options that allow multiple values, both a singular and a plural option\nkey are supported. For example, to specify multiple var files during a plan:\n\n```ruby\nRubyTerraform.plan(\n  chdir: 'infra/network',\n  out: 'network.tfplan',\n  var_file: 'defaults.tfvars',\n  var_files: %w[environment.tfvars secrets.tfvars]\n)\n```\n\nIn this case, all three var files are passed to Terraform.\n\nSome options have aliases. For example, the `:out` option can also be provided\nas `:plan` for symmetry with other terraform commands. However, in such\nsituations only one of the aliases should be used in the provided parameters\nhash.\n\nSee the [API docs](https://infrablocks.github.io/ruby_terraform/index.html) for\na more complete listing of available parameter options.\n\n### Configuration\n\n`RubyTerraform` uses sensible defaults for all configuration options. However,\nthere are a couple of ways to override the defaults when they are sufficient.\n\n#### Binary\n\nBy default, `RubyTerraform` looks for the Terraform binary on the system path.\nTo globally configure a specific binary location:\n\n```ruby\nRubyTerraform.configure do |config|\n  config.binary = 'vendor/terraform/bin/terraform'\nend\n```\n\nTo configure the Terraform binary on a command by command basis, for example for\nthe `Plan` command:\n\n```ruby\ncommand = RubyTerraform::Commands::Plan.new(\n  binary: 'vendor/terraform/bin/terraform'\n)\ncommand.execute(\n  # ...\n)\n```\n\n#### Logging\n\nBy default, `RubyTerraform` 's own log statements are logged to `$stdout` with\nlevel `info`.\n\nTo globally configure a custom logger:\n\n```ruby\nrequire 'logger'\n\nlogger = Logger.new($stdout)\nlogger.level = Logger::DEBUG\n\nRubyTerraform.configure do |config|\n  config.logger = logger\nend\n```\n\n`RubyTerraform` supports logging to multiple different outputs at once,\nfor example:\n\n```ruby\nrequire 'logger'\n\nfile_device = Logger::LogDevice.new('/foo/bar.log')\nstdout_device = Logger::LogDevice.new(STDOUT)\nmulti_io = RubyTerraform::MultiIO.new(file_device, stdout_device)\n\nlogger = Logger.new(multi_io, level: :debug)\n\nRubyTerraform.configure do |config|\n  config.binary = '/binary/path/terraform'\n  config.logger = logger\n  config.stdout = multi_io\n  config.stderr = multi_io\nend\n```\n\n\u003e Creating the Logger with a file this way (using `Logger::LogDevice`),\n\u003e guarantees that the buffer content will be saved/written, as it sets\n\u003e **implicit flushing**.\n\nConfigured in this way, any logging performed by `RubyTerraform` will log to\nboth `STDOUT` and to the specified file.\n\nTo configure the logger on a command by command basis, for example for the\n`Show` command:\n\n```ruby\nrequire 'logger'\n\nlogger = Logger.new($stdout)\nlogger.level = Logger::DEBUG\n\ncommand = RubyTerraform::Commands::Show.new(\n  logger: logger\n)\ncommand.execute(\n  # ...\n)\n```\n\n#### Standard streams\n\nBy default, `RubyTerraform` uses streams `$stdin`, `$stdout` and `$stderr`.\n\nTo configure custom output and error streams:\n\n```ruby\nlog_file = File.open('path/to/some/ruby_terraform.log', 'a')\n\nRubyTerraform.configure do |config|\n  config.stdout = log_file\n  config.stderr = log_file\nend\n```\n\nIn this way, both outputs will be redirected to `log_file`.\n\nSimilarly, a custom input stream can be configured:\n\n```ruby\nrequire 'stringio'\n\ninput = StringIO.new(\"user\\ninput\\n\")\n\nRubyTerraform.configure do |config|\n  config.stdin = input\nend\n```\n\nIn this way, terraform can be driven by input from somewhere other than\ninteractive input from the terminal.\n\nTo configure the standard streams on a command by command basis, for example for\nthe `Init` command:\n\n```ruby\nrequire 'logger'\n\ninput = StringIO.new(\"user\\ninput\\n\")\nlog_file = File.open('path/to/some/ruby_terraform.log', 'a')\n\ncommand = RubyTerraform::Commands::Init.new(\n  stdin: input,\n  stdout: log_file,\n  stderr: log_file\n)\ncommand.execute(\n  # ...\n)\n```\n\n## Documentation\n\n* [API docs](https://infrablocks.github.io/ruby_terraform/index.html)\n\n## Development\n\nTo install dependencies and run the build, run the pre-commit build:\n\n```shell script\n./go\n```\n\nThis runs all unit tests and other checks including coverage and code linting /\nformatting.\n\nTo run only the unit tests, including coverage:\n\n```shell script\n./go test:unit\n```\n\nTo attempt to fix any code linting / formatting issues:\n\n```shell script\n./go library:fix\n```\n\nTo check for code linting / formatting issues without fixing:\n\n```shell script\n./go library:check\n```\n\nYou can also run `bin/console` for an interactive prompt that will allow you to\nexperiment.\n\n### Managing CircleCI keys\n\nTo encrypt a GPG key for use by CircleCI:\n\n```bash\nopenssl aes-256-cbc \\\n  -e \\\n  -md sha1 \\\n  -in ./config/secrets/ci/gpg.private \\\n  -out ./.circleci/gpg.private.enc \\\n  -k \"\u003cpassphrase\u003e\"\n```\n\nTo check decryption is working correctly:\n\n```bash\nopenssl aes-256-cbc \\\n  -d \\\n  -md sha1 \\\n  -in ./.circleci/gpg.private.enc \\\n  -k \"\u003cpassphrase\u003e\"\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/infrablocks/ruby_terraform. This project is intended to be a\nsafe, welcoming space for collaboration, and contributors are expected to adhere\nto the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfrablocks%2Fruby_terraform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfrablocks%2Fruby_terraform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfrablocks%2Fruby_terraform/lists"}