Usage

Only for ~>1.* versions

Independent from how you install terraform-compliance, you need to provide some of the cli parameters.

[~] $ terraform-compliance -h

  terraform-compliance v[...] initiated
  
  usage: terraform-compliance [-h] --features feature directory --planfile
                              plan_file [--identity [ssh private key]]
                              [--terraform [terraform_file]]
                              [--version]
  
  BDD Test Framework for Hashicorp terraform
  
  optional arguments:
    -h, --help            show this help message and exit
    --features feature directory, -f feature directory
                          Directory (or git repository with 'git:' prefix)
                          consists of BDD features
    --planfile plan_file, -p plan_file
                          Plan output file generated by Terraform
    --identity [ssh private key], -i [ssh private key]
                          SSH Private key that will be use on git
                          authentication.
    --terraform [terraform_file], -t [terraform_file]
                          The absolute path to the terraform executable.  
    --version, -v         show program's version number and exit

CLI Reference

-f / –features

REQUIRED

This parameter is used to provide feature files to terraform-compliance. It must be a directory or a git repository. All files within the directory (or repository) will be processed non-recursively.

[~] $ terraform-compliance -f /path/to/feature/files/ ...

or for a git repository ; (highly recommended for segregation of duties and having immutable features!)

If the repository is a public repository or credentials are available in the configured git credential manager ;

[~] $ terraform-compliance -f git:https://github.com/user/repo ...

or if the repository is a private repository ;

[~] $ terraform-compliance -f git:ssh://github.com/user/repo.git ...

The authentication to that git repository will be handled via your ~/.ssh/config. If you are using a different ssh key for this repository then you also need to provide -i parameter to pointing your private key.

New in 1.2.4, a repository can be referenced by branch name and directory. This uses syntax similar to Terraform Modules in Package Sub-directories. The reference must include // after .git and end with ?ref=<branch-name> or ?ref=<tag>.

[~] $ terraform-compliance -f git:ssh://github.com/user/repo.git//directory?ref=v1.0.0 ...

The directory is optional.

[~] $ terraform-compliance -f git:ssh://github.com/user/repo.git//?ref=staging ...

-p / –planfile

REQUIRED

terraform-compliance requires a plan or state output to run against. In order to create this plan file, you can run terraform ;

[~] $ terraform plan -out=plan.out

then you can provide this plan.out to terraform-compliance via ;

[~] $ terraform-compliance -p plan.out ...

terraform-compliance also supports parsing your state files. Your state file might be in your local, or in a remote entity. In order to download your state file ;

[~] $ terraform state pull > state.out

and then you can run your features against this state.out file via ;

[~] $ terraform-compliance -p state.out ...

-i / –identity

OPTIONAL

In case you need to authenticate to a private git repository as also described in -f parameter, then you may need to provide a private ssh key.

You can use -i parameter to do that ;

[~] $ terraform-compliance -i /path/to/ssh/private/key ...

Please note that, if the host that you are trying to authenticate already defined in ~/ssh/config, then terraform-compliance will use that key for authentication.

-t / –terraform

OPTIONAL

terraform-compliance will attempt to auto-detect the terraform version that is used while creating the plan. It will attempt to downlod that specific terraform version while converting the plan file into JSON format.

In case this detection attempt fails, you can also provide a local terraform executable

[~] $ terraform-compliance -t /path/to/specific/versin/of/terraform ...

If you are using a Docker version of terraform-compliance, the latest version of terraform binary is already packaged within the Docker Image. In case the auto-detection failed and you may need to use another version of terraform binary, you can still use -t to point the local version.

terraform executable is used to transform plan.out file produced from terraform plan to plan.out.json by running terraform show -json plan.out > plan.out.json. In case you are having version conflicts of terraform while using the Docker image of terraform-compliance, you can just avoid this problem and the need of terraform executable in your CI/CD container by running ;

[~] $ terraform plan -out plan.out                           # To create the plan
[~] $ terraform show -json plan.out > plan.out.json          # To convert the plan.out to JSON format just after the plan

-q / –quit-early

OPTIONAL

1.1.+

This option will disable default behaviour of terraform-compliance where the execution of the Scenario and Step (not Feature) will exit immediately upon first failure.

-n / –no-failures

OPTIONAL

1.1.+

This option will enforce to have 0 exit code independent of the test results. It is different than passing --wip since, that parameter only returns 0 if the test fails. This option will make terarform-compliance to report all errors, but always return 0 exit code.

-S / –silent

OPTIONAL

1.1.+

This option will surpress the output of Feature, Scenario and Steps. Only the summary and the Failure messages will be shown - if applicable.

-d / –debug

OPTIONAL

1.2.+

This option will let you peek in the stash or run IPython on the current step.

Commands

  • s: prints stash
  • d: opens Interactive Python.
  • h: prints commands

In Python shell, context can be accessed via step.context.stash. Note that modifications to step object will carry over to the steps below.

It is usually a better idea to inspect the stash before the step being debugged.


Table of contents


terraform-compliance made with . Distributed by an MIT license.