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.