Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/newcontext-oss/kitchen-terraform

Test Kitchen plugins for testing Terraform configurations
https://github.com/newcontext-oss/kitchen-terraform

behaviour driver kitchen kitchen-terraform provisioner ruby rubygems terraform terraform-providers test-kitchen verifies

Last synced: 2 months ago
JSON representation

Test Kitchen plugins for testing Terraform configurations

Awesome Lists containing this project

README 

        
# ![Kitchen-Terraform Logo][kitchen-terraform-logo] Kitchen-Terraform



> Kitchen-Terraform enables verification of infrastructure systems provisioned with Terraform.



[![Gem version][gem-version-shield]][kitchen-terraform-gem]

[![Gem downloads version][gem-downloads-version-shield]][kitchen-terraform-gem]

[![Gem downloads total][gem-downloads-total-shield]][kitchen-terraform-gem]



[![Delivery][delivery-shield]][delivery-workflow]

[![Pages Build and Deployment][pages-build-deployment-shield]][pages-build-deployment-workflow]

[![Code coverage][code-coverage-shield]][code-coverage]

[![Maintainability][maintainability-shield]][maintainability]

[![Technical debt][technical-debt-shield]][technical-debt]



[![Gitter chat][gitter-shield]][gitter]



> **Warning**

> Deprecation Notice :warning:

>

> With the

> [announcement](https://www.hashicorp.com/blog/terraform-1-6-adds-a-test-framework-for-enhanced-code-validation) of

> a native test framework with Terraform 1.6 on 2023-10-04, we are excited/saddened/relieved to announce the deprecation

> of Kitchen-Terraform :tada: The project will enter a maintenance-only period for about 1 year, after which time it

> will be archived.

>

> We strongly recommend that users begin to learn about

> [Terraform tests](https://developer.hashicorp.com/terraform/language/tests) and plan their migration to the new

> framework accordingly.

>

> So long, and thanks for all the tests :sparkling_heart:



Kitchen-Terraform provides a set of [Test Kitchen][test-kitchen] plugins

which enable the use of Test Kitchen to converge a [Terraform][terraform]

configuration and verify the resulting infrastructure systems with

[InSpec][inspec] controls.



As Kitchen-Terraform integrates several distinctive technologies in a

nontrivial manner, reviewing the documentation of each of the

aforementioned products is strongly encouraged.



## Installation



### Terraform



Kitchen-Terraform integrates with the

[Terraform command-line interface][terraform-cli] to implement a Test

Kitchen workflow for Terraform modules.



Installation instructions can be found in the

[Terraform: Install Terraform][terraform-install] article.



Kitchen-Terraform supports versions of Terraform in the interval of

`>= 0.11.4, < 2.0.0`.



[tfenv] can be used to manage versions of Terraform on the system.



### Ruby



Kitchen-Terraform is written in [Ruby][ruby] which requires an

interpreter to be installed on the system.



Installation instructions can be found in the

[Ruby: Installing Ruby][ruby-installation] article.



Kitchen-Terraform aims to support all versions of Ruby that are in

["normal" or "security" maintenance][ruby-branches], which is currently

the interval of `>= 2.4, < 2.8`.



[rbenv] can be used to manage versions of Ruby on the system.



### Kitchen-Terraform Ruby Gem



Each version of Kitchen-Terraform is published as a

[Ruby gem][ruby-gems-what-is] to [RubyGems.org][kitchen-terraform-gem]

which makes them readily available for installation on a system.



#### Bundler



[Bundler][bundler] should be used to manage versions of

Kitchen-Terraform on the system. Using Bundler provides easily

reproducible Ruby gem installations that can be shared with other

systems.



First, create a `Gemfile` with contents like the following example. The

pessimistic pinning of the version is recommended to benefit from

the semantic versioning of the Ruby gem.



> Defining Kitchen-Terraform as a dependency for Bundler in a Gemfile



---



```ruby

source "https://rubygems.org/" do

  gem "kitchen-terraform", "~> 7.0"

end

```



---



Second, run the following command.



> Installing Kitchen-Terraform with Bundler



---



```sh

bundle install

```



---



The preceding command will create a `Gemfile.lock` comprising a list

of the resolved Ruby gem dependencies.



More information can be found in the

[Bundler: In Depth][bundler-in-depth] article.



#### RubyGems



RubyGems, the default Ruby package manager, can also be used to install

a version of Kitchen-Terraform by running a command like the following

example.



> Installing Kitchen-Terraform with RubyGems



---



```sh

gem install kitchen-terraform --version 7.0.2

```



---



This approach is not recommended as it requires more effort to install

the gem in a manner that is reproducible and free of dependency

conflicts.



More information can be found in the

[RubyGems: Installing Gems][rubygems-installing-gems] article.



#### Extra Dependencies



The RbNaCl gem may need to be [installed][rbnacl-installation] in order

to use Ed25519-type SSH keys to connect to systems with the SSH backend.

This gem implicitly depends on the system package libsodium, and its

presence when libsodium is not installed causes unexpected errors when

loading InSpec transport plugins like GCP, so it is not included by

default to reduce the burden on users whom do not require support for

Ed25519-type SSH keys.



## Usage



A familiarity with [Test Kitchen][test-kitchen] workflows and commands is required to use Kitchen-Terraform.



### Configuration



Kitchen-Terraform provides four Test Kitchen plugins which must be

configured in a

[Test Kitchen configuration file][kitchen-configuration-file] in

order to successfully test Terraform configuration.



The [Terraform driver][terraform-driver] is the bridge between Test

Kitchen and Terraform. It manages the [state][terraform-state] of the

Terraform root module under test by shelling out and running Terraform commands.



The [Terraform provisioner][terraform-provisioner] applies changes to

the Terraform state based on the configuration of the root module.



The [Terraform transport][terraform-transport] is responsible for the

integration with the Terraform CLI.



The [Terraform verifier][terraform-verifier] utilizes InSpec to verify

the behaviour and state of resources in the Terraform state.



More information can be found in the

[Ruby gem documentation][ruby-gem-documentation].



The `kitchen doctor` command can be used to validate the system and the

configuration file.



### Caveats



Versions of Terraform in the 0.11 series may cause `kitchen test` to

fail if the initial destroy targets an empty Terraform state. A

workaround for this problem is to use

`kitchen verify && kitchen destroy` instead of `kitchen test`. More

details about the problem are available in

[issue #271](issue-271).



### Tutorials and Examples



Several tutorials are available on the

[Kitchen-Terraform Tutorials][kitchen-terraform-tutorials] page.



The integration tests for Kitchen-Terraform can also be viewed as

examples of how it works. The

[integration test Test Kitchen configuration file][int-kitchen-config]

and the [integration test directory][test-directory] provide several

functional examples which exercise various features of

Kitchen-Terraform.



## Contributing



Kitchen-Terraform thrives on community contributions.



Information about contributing to Kitchen-Terraform can be found in the

[Contributing document][contributing-document].



## Changelog



Kitchen-Terraform adheres to semantic versioning and documents all

significant changes accordingly.



Information about changes to Kitchen-Terraform can be found in the

[Changelog][changelog].



## Maintainers



Kitchen-Terraform is maintained by [community contributors][contributors]

and Copado NCS LLC.



Copado logo [copado.com][copado]



Twitter logo [@CopadoSolutions][copado-twitter]



LinkedIn logo [Copado][copado-linkedin]



GitHub logo [@CopadoSolutions][copado-github]



Email logo 



Email logo 



## License



Kitchen-Terraform is distributed under the [Apache License][license].



[bundler-in-depth]: https://bundler.io/gemfile.html

[bundler]: https://bundler.io/index.html#getting-started

[changelog]: https://github.com/newcontext-oss/kitchen-terraform/blob/master/CHANGELOG.md

[code-coverage-shield]: https://img.shields.io/codeclimate/coverage/newcontext-oss/kitchen-terraform.svg

[code-coverage]: https://codeclimate.com/github/newcontext-oss/kitchen-terraform/

[contributing-document]: https://github.com/newcontext-oss/kitchen-terraform/blob/master/CONTRIBUTING.md

[contributors]: https://github.com/newcontext-oss/kitchen-terraform/graphs/contributors

[copado-github]: https://github.com/CopadoSolutions

[copado-linkedin]: https://www.linkedin.com/company/copado-solutions-s.l

[copado-twitter]: https://twitter.com/CopadoSolutions

[copado]: https://copado.com/

[delivery-shield]: https://github.com/newcontext-oss/kitchen-terraform/actions/workflows/delivery.yml/badge.svg

[delivery-workflow]: https://github.com/newcontext-oss/kitchen-terraform/actions/workflows/delivery.yml

[gem-downloads-total-shield]: https://img.shields.io/gem/dt/kitchen-terraform.svg

[gem-downloads-version-shield]: https://img.shields.io/gem/dtv/kitchen-terraform.svg

[gem-version-shield]: https://img.shields.io/gem/v/kitchen-terraform.svg

[gitter-shield]: https://img.shields.io/gitter/room/kitchen-terraform/Lobby.svg

[gitter]: https://gitter.im/kitchen-terraform/Lobby

[inspec]: https://community.chef.io/tools/chef-inspec

[int-kitchen-config]: https://github.com/newcontext-oss/kitchen-terraform/blob/master/kitchen.yml

[kitchen-configuration-file]: https://docs.chef.io/config_yml_kitchen.html

[kitchen-terraform-gem]: https://rubygems.org/gems/kitchen-terraform

[kitchen-terraform-logo]: https://raw.githubusercontent.com/newcontext-oss/kitchen-terraform/master/assets/logo.png

[kitchen-terraform-tutorials]: https://newcontext-oss.github.io/kitchen-terraform/tutorials/

[license]: https://github.com/newcontext-oss/kitchen-terraform/blob/master/LICENSE

[maintainability-shield]: https://img.shields.io/codeclimate/maintainability-percentage/newcontext-oss/kitchen-terraform.svg

[maintainability]: https://codeclimate.com/github/newcontext-oss/kitchen-terraform/

[pages-build-deployment-shield]: https://github.com/newcontext-oss/kitchen-terraform/actions/workflows/pages/pages-build-deployment/badge.svg

[pages-build-deployment-workflow]: https://github.com/newcontext-oss/kitchen-terraform/actions/workflows/pages/pages-build-deployment

[rbenv]: https://github.com/rbenv/rbenv

[rbnacl-installation]: https://github.com/crypto-rb/rbnacl/tree/v4.0.2#installation

[ruby-branches]: https://www.ruby-lang.org/en/downloads/branches/

[ruby-gem-documentation]: http://www.rubydoc.info/github/newcontext-oss/kitchen-terraform/

[ruby-gems-what-is]: http://guides.rubygems.org/ruby-gems-what-is/index.html

[ruby-installation]: https://www.ruby-lang.org/en/documentation/installation/

[ruby]: https://www.ruby-lang.org/en/

[rubygems-installing-gems]: http://guides.rubygems.org/rubygems-basics/#rubygems-installing-gems

[technical-debt-shield]: https://img.shields.io/codeclimate/tech-debt/newcontext-oss/kitchen-terraform.svg

[technical-debt]: https://codeclimate.com/github/newcontext-oss/kitchen-terraform/

[terraform-cli]: https://developer.hashicorp.com/terraform/cli/commands

[terraform-driver]: http://www.rubydoc.info/github/newcontext-oss/kitchen-terraform/Kitchen/Driver/Terraform

[terraform-install]: https://www.terraform.io/intro/getting-started/install.html

[terraform-provisioner]: http://www.rubydoc.info/github/newcontext-oss/kitchen-terraform/Kitchen/Provisioner/Terraform

[terraform-state]: https://developer.hashicorp.com/terraform/language/state

[terraform-transport]: http://www.rubydoc.info/github/newcontext-oss/kitchen-terraform/Kitchen/Transport/Terraform

[terraform-verifier]: http://www.rubydoc.info/github/newcontext-oss/kitchen-terraform/Kitchen/Verifier/Terraform

[terraform]: https://www.terraform.io/

[test-directory]: https://github.com/newcontext-oss/kitchen-terraform/tree/master/test

[test-kitchen]: http://kitchen.ci/

[tfenv]: https://github.com/kamatama41/tfenv