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 v1.0.0 initiated
usage: terraform-compliance [-h] --features feature directory --planfile
plan_file [--identity [ssh private key]]
[--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 ;
[~] $ 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
In some cases, a plan file that is created by a specific version of terraform might require the same version of that terraform in order to process that. terraform-compliance uses terraform in order to parse any plan/state files that has been created. In these cases you can just provide the same version of terraform via ;
[~] $ terraform-compliance -t /path/to/specific/versin/of/terraform ...
If you are using a Docker version of terraform-compliance, terraform binary is already packaged within the Docker Image. In case, 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.