Kitchen-Terraform for Testing: Legacy Maintenance and Migration Guide

TL;DR

• Kitchen-Terraform was archived October 2024—don’t use it for new projects
• If you inherited a Kitchen-Terraform codebase, this guide helps you maintain it while planning migration
• The InSpec compliance patterns are still valuable—migrate them to Terraform native tests or standalone InSpec

Best for: Teams maintaining legacy Kitchen-Terraform setups or planning migration Skip if: Starting fresh—use Terraform native tests or Terratest instead Read time: 10 minutes

Let’s address the elephant in the room: Kitchen-Terraform is deprecated and archived. The repository went read-only on October 22, 2024, following Terraform 1.6’s native test framework release.

But here’s reality: thousands of organizations still run Kitchen-Terraform in production. If you’ve inherited one of these codebases, you need to understand how it works, keep it running, and plan your migration. That’s what this guide is for.

Understanding Kitchen-Terraform Architecture

Kitchen-Terraform combined three tools:

The workflow was: Test Kitchen orchestrates → Terraform provisions → InSpec verifies.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Test Kitchen  │────▶│    Terraform    │────▶│     InSpec      │
│   (Orchestrate) │     │   (Provision)   │     │    (Verify)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Prerequisites for Legacy Maintenance

If you’re maintaining an existing Kitchen-Terraform setup:

• Ruby 2.7+ with Bundler
• Terraform < 2.0 (Kitchen-Terraform supports >= 0.11.4, < 2.0.0)
• kitchen-terraform gem (version 7.x was the last major release)
• InSpec 4.x or 5.x

Check your current versions:

ruby --version
terraform version
bundle exec kitchen version
inspec version

Anatomy of a Kitchen-Terraform Project

A typical structure looks like:

terraform-module/
├── main.tf
├── variables.tf
├── outputs.tf
├── kitchen.yml              # Test Kitchen configuration
├── Gemfile                  # Ruby dependencies
└── test/
    └── integration/
        └── default/
            ├── controls/
            │   └── example.rb   # InSpec controls
            └── inspec.yml       # InSpec profile

The kitchen.yml File

driver:
  name: terraform
  root_module_directory: .
  parallelism: 4

provisioner:
  name: terraform

verifier:
  name: terraform
  systems:
    - name: default
      backend: aws
      controls:
        - example

platforms:
  - name: terraform

suites:
  - name: default
    driver:
      variables:
        instance_type: t3.micro
        environment: test

InSpec Control Example

# test/integration/default/controls/example.rb

control 's3-bucket-encryption' do
  impact 1.0
  title 'S3 bucket must have encryption enabled'
  desc 'Verify that the S3 bucket has server-side encryption configured'

  describe aws_s3_bucket(bucket_name: input('output_bucket_name')) do
    it { should exist }
    it { should have_default_encryption_enabled }
  end
end

control 's3-bucket-versioning' do
  impact 0.7
  title 'S3 bucket should have versioning enabled'

  describe aws_s3_bucket(bucket_name: input('output_bucket_name')) do
    it { should have_versioning_enabled }
  end
end

Notice how Terraform outputs (prefixed with output_) become InSpec inputs automatically.

Running Legacy Tests

The Kitchen-Terraform workflow:

# Install dependencies
bundle install

# Create infrastructure and run tests
bundle exec kitchen test

# Or step by step:
bundle exec kitchen create    # Initialize Terraform
bundle exec kitchen converge  # Apply Terraform
bundle exec kitchen verify    # Run InSpec tests
bundle exec kitchen destroy   # Clean up

Debugging Failed Tests

# Keep infrastructure after test failure
bundle exec kitchen verify --destroy=never

# Run specific suite
bundle exec kitchen test default-terraform

# Verbose output
bundle exec kitchen test -l debug

Why Migration is Necessary

Beyond the archived status, Kitchen-Terraform has practical limitations:

Migration Path 1: Terraform Native Tests

For most teams, migrate to Terraform’s built-in test framework (Terraform 1.6+).

Before (Kitchen-Terraform InSpec)

# test/integration/default/controls/s3.rb
control 's3-encryption' do
  describe aws_s3_bucket(bucket_name: input('output_bucket_name')) do
    it { should have_default_encryption_enabled }
  end
end

After (Terraform Native Test)

# tests/s3_bucket.tftest.hcl
run "create_s3_bucket" {
  command = apply

  assert {
    condition     = aws_s3_bucket_server_side_encryption_configuration.this.rule[0].apply_server_side_encryption_by_default[0].sse_algorithm == "AES256"
    error_message = "S3 bucket must have AES256 encryption enabled"
  }
}

run "verify_versioning" {
  command = apply

  assert {
    condition     = aws_s3_bucket_versioning.this.versioning_configuration[0].status == "Enabled"
    error_message = "S3 bucket versioning must be enabled"
  }
}

Run with:

terraform test

Migration Script Pattern

#!/bin/bash
# migrate-kitchen-to-native.sh

# 1. Extract InSpec controls
CONTROLS_DIR="test/integration/default/controls"

# 2. Create Terraform test directory
mkdir -p tests

# 3. Generate migration report
echo "Controls to migrate:"
grep -r "^control" $CONTROLS_DIR | while read line; do
  echo "  - $line"
done

# 4. Reminder
echo ""
echo "Manual steps required:"
echo "1. Convert each InSpec control to Terraform assert blocks"
echo "2. Map input('output_*') to Terraform resource attributes"
echo "3. Remove kitchen.yml and Gemfile dependencies"

Migration Path 2: Standalone InSpec

If your InSpec controls are complex or test more than Terraform state, run InSpec independently:

# Install InSpec
gem install inspec-bin

# Run against deployed infrastructure
inspec exec test/integration/default \
  --input output_bucket_name=my-bucket-name \
  --target aws://us-west-2

Create a wrapper script for CI/CD:

#!/bin/bash
# run-compliance-tests.sh

# Deploy with Terraform
terraform init
terraform apply -auto-approve

# Extract outputs for InSpec
BUCKET_NAME=$(terraform output -raw bucket_name)

# Run InSpec compliance tests
inspec exec ./compliance \
  --input output_bucket_name=$BUCKET_NAME \
  --target aws://$AWS_REGION \
  --reporter cli json:reports/compliance.json

# Cleanup
terraform destroy -auto-approve

AI-Assisted Migration

In 2026, AI tools can accelerate your migration significantly.

What AI does well:

• Converting InSpec Ruby syntax to Terraform HCL assertions
• Identifying equivalent Terraform resource attributes for InSpec checks
• Generating migration checklists from kitchen.yml files
• Writing wrapper scripts for standalone InSpec execution

What still needs humans:

• Deciding which controls are still relevant
• Understanding compliance requirements behind each control
• Validating that migrated tests maintain the same coverage
• Handling custom InSpec resources that have no Terraform equivalent

Useful prompt:

Convert this InSpec control to a Terraform native test:

control 'ec2-instance-type' do
  impact 1.0
  title 'EC2 instance must use approved instance type'

  describe aws_ec2_instance(name: input('output_instance_id')) do
    its('instance_type') { should be_in ['t3.micro', 't3.small'] }
    its('image_id') { should match /^ami-/ }
  end
end

The Terraform resource is defined as:
resource "aws_instance" "main" {
  ami           = var.ami_id
  instance_type = var.instance_type
}

Generate the equivalent .tftest.hcl file with proper assertions.

Decision Framework

Keep Kitchen-Terraform If:

• You have extensive custom InSpec resources
• Migration timeline is 12+ months away
• Team has strong Ruby expertise
• Compliance frameworks specifically require InSpec reports

Migrate to Native Tests If:

• You’re testing Terraform configuration, not cloud state
• You want faster test execution
• You’re reducing CI/CD dependencies
• Starting fresh or major refactoring anyway

Migrate to Standalone InSpec If:

• You need CIS benchmark compliance reports
• Testing goes beyond Terraform-managed resources
• Regulatory requirements mandate InSpec
• Multi-tool infrastructure (not just Terraform)

Measuring Migration Success

Warning signs migration isn’t working:

• Tests pass but compliance audits fail — coverage gaps
• Execution time increased — over-complicated assertions
• More false positives — assertions too strict

Common Pitfalls

1. Losing Compliance Coverage

# BAD: Only checks Terraform state
assert {
  condition = aws_s3_bucket.this.bucket != ""
  error_message = "Bucket must exist"
}

# BETTER: Checks actual configuration
assert {
  condition = aws_s3_bucket_versioning.this.versioning_configuration[0].status == "Enabled"
  error_message = "Versioning must be enabled for compliance"
}

2. Ignoring InSpec’s Cloud State Testing

Native Terraform tests check state, not reality. For actual cloud verification, keep InSpec or use Terratest:

# InSpec tests actual AWS resources
inspec exec compliance/ --target aws://

# Terraform tests check Terraform state
terraform test

3. Rushing Migration

Migrate incrementally:

1. First: Run both Kitchen-Terraform AND native tests in parallel
2. Then: Verify coverage parity
3. Finally: Remove Kitchen-Terraform

What’s Next

If you’re maintaining Kitchen-Terraform, start your migration plan now. The framework won’t receive new features, and Terraform 2.x compatibility is uncertain.

For new projects, skip Kitchen-Terraform entirely. Use Terraform native tests for configuration validation and Terratest or standalone InSpec for real infrastructure verification.

The InSpec patterns you learned are still valuable—compliance-as-code thinking transfers directly to any testing framework.

Related articles:

• Terraform Testing and Validation Strategies
• Terratest: Testing Infrastructure as Code
• Pulumi Testing Best Practices
• Test Automation Pyramid Strategy

External resources:

• Kitchen-Terraform GitHub (Archived)
• Terraform Test Documentation
• Chef InSpec Documentation