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.