A simple CLI tool to assist HCL generation and debugging with using the DaVinci Terraform provider.

• Supported DaVinci Terraform provider version: v0.4.2+

Only Homebrew is supported initially, for other methods of install please raise an issue.

brew tap patrickcping/dvtf-pingctl
brew install dvtf-pingctl

Test the installation with:

dvtf-pingctl --help

Visit the example to view a full example of generation and validation starting with a multi-flow export.

Help can found by using the --help / -h parameter for any command.

Examples:

dvtf-pingctl generate --help
dvtf-pingctl validate --help

The DaVinci exports can be provided in one of two ways:

• By defining the exportFilePath in the YAML config file. Multiple files can be specified.
• By using the --export-file-path / -e parameter. Multiple files can be specified.
• Piping the output of a command to the dvtf-pingctl tool. Only one JSON payload is accepted.

The --export-file-path / -e parameter can be used to specify the path locations of one or more files. If multiple files are provided, the tool will validate all provided files at once (if using the dvtf-pingctl validate ... command) or generate a single set of Terraform .tf files with combined HCL definitions (if using the dvtf-pingctl generate ... command)

Examples:

dvtf-pingctl generate \
  --export-file-path /path/to/my/export.json

dvtf-pingctl generate \
    -e /path/to/my/export.json

dvtf-pingctl generate \
    --export-file-path /path/to/my/main_flow_export.json \
    --export-file-path /path/to/my/sub_flow_export.json

dvtf-pingctl generate \
    -e /path/to/my/main_flow_export.json \
    -e /path/to/my/sub_flow_export.json

dvtf-pingctl validate \
    --export-file-path /path/to/my/export.json \
    --export-file-path /path/to/my/sub_flow_export.json

A single DaVinci export JSON payload can be piped to the dvtf-pingctl command, useful if using jq to modify the payload before generation/validation.

Examples:

cat /path/to/my/export.json | dvtf-pingctl generate

jq '.name = "abcde"' ./path/to/my/export.json | dvtf-pingctl generate

jq '.name = "abcde"' ./path/to/my/export.json | dvtf-pingctl validate

Generate HCL configuration from a DaVinci service JSON export file using the dvtf-pingctl generate ... command. The command will generate a Terraform module by default, with variables for connector properties and variable values.

The output path for generated resources can be set with the --output-path / -o parameter on the dvtf-pingctl generate ... command. The default, if not provided, is ./generated, meaning it will create a directory generated in the current working directory.

If the output directory already exists and the --overwrite parameter is not set, the generator will return an error. If you want to overwrite the contents of the output directory, use the --overwrite parameter.

Examples:

dvtf-pingctl generate \
    --export-file-path /path/to/my/export.json \
    -o ./my/output/dir

dvtf-pingctl generate \
    -e /path/to/my/export.json \
    -o ./my/output/dir

dvtf-pingctl generate \
    --export-file-path /path/to/my/export.json \
    -o ./my/output/dir \
    --overwrite

dvtf-pingctl generate \
    -e /path/to/my/export.json \
    -o ./my/output/dir \
    --overwrite

Examples where the JSON payload is provided via pipe:

cat /path/to/my/export.json | dvtf-pingctl generate -o ./my/output/dir

cat /path/to/my/export.json | dvtf-pingctl generate -o ./my/output/dir --overwrite

Only davinci_flow, davinci_variable, and davinci_connector resources from the DaVinci Terraform provider are supported and can be generated.

Individual resources can be selected for generation using the --resource flag (-r for short), and if this flag is omitted, all resources will be generated. The flag can be repeated as many times as .needed

Examples where the JSON is provided as a parameter:

dvtf-pingctl generate \
    --export-file-path /path/to/my/export.json \
    -o ./my/output/dir \
    --resource davinci_flow \
    --resource davinci_variable \
    --resource davinci_connector

dvtf-pingctl generate \
    -e /path/to/my/export.json \
    -o ./my/output/dir \
    -r davinci_flow \
    -r davinci_variable \
    -r davinci_connector

Examples where the JSON payload is provided via pipe:

cat /path/to/my/export.json | dvtf-pingctl generate -o ./my/output/dir

cat /path/to/my/export.json | dvtf-pingctl generate -o ./my/output/dir --resource davinci_flow --resource davinci_variable --resource davinci_connector

cat /path/to/my/export.json | dvtf-pingctl generate -o ./my/output/dir -r davinci_flow -r davinci_variable -r davinci_connector

Use the dvtf-pingctl validate ... command to ensure that the flow validates correctly when used with the DaVinci Terraform provider (version v0.4.2+). The validate command will show more detail than the Terraform provider validation, and can be used to debug errors and warnings on terraform plan ... and terraform apply ...

The Terraform provider expects single flows only, and this command contains a validation step to ensure that only one flow is provided in the JSON export contents.

Examples where the JSON is provided as a parameter:

dvtf-pingctl validate \
    --export-file-path /path/to/my/export.json

dvtf-pingctl validate \
    -e /path/to/my/export.json

Example where the JSON is provided via pipe:

cat /path/to/my/export.json | dvtf-pingctl validate

To validate the JSON input for a specific davinci_flow field in the case of debugging state, use the --field flag (-f for short):

Examples where the JSON is provided as a parameter:

dvtf-pingctl validate \
    --export-file-path /path/to/my/export.json \
    --field flow_configuration_json

dvtf-pingctl validate \
    -e /path/to/my/export.json \
    -f flow_configuration_json

Example where the JSON is provided via pipe:

cat /path/to/my/export.json | dvtf-pingctl validate --field flow_configuration_json

cat /path/to/my/export.json | dvtf-pingctl validate -f flow_configuration_json

The dvtf-pingctl validate ... command will return the following return status codes along with a text description of the validation issues:

• 0 - Successful validation, no warnings
• 1 - Unsuccessful validation
• 2 - Successful validation, with warnings

The logging level can be set using the DVTF_LOG environment variable. The possible values that can be set are DEBUG, INFO, WARN, ERROR and NOLEVEL. By default, extra log output is disabled.

A log file can be created using the DVTF_PATH environment variable. This redirects the log output to a file of choice. If not set, the debug output will be printed alongside the command output (stdout).

The following example logs debug output to the file called dvtf.log:

DVTF_LOG=DEBUG DVTF_PATH=`pwd`/dvtf.log dvtf-pingctl validate \
    --export-file-path /path/to/my/export.json \
    --field flow_configuration_json

The parameters described above can be configured in a static configuration file, expected to be named .dvtf-pingctl.yaml in the same directory that the CLI tool is run. The following describe the properties that can be set, and an example can be found at ./dvtf-pingctl.yaml.example

The following are configuration file settings for both dvtf-pingctl generate ... and dvtf-pingctl validate ... commands.

The following are configuration file settings for the dvtf-pingctl generate ... command.

The following are configuration file settings for the dvtf-pingctl validate ... command.

• davinci_connector property blocks are not yet generated and must be defined using the DaVinci Connector Definitions guide
• Homebrew is the only installer currently. Multi-arch install (including Windows) TBD
• Housekeeping: Enhanced Debug logging
• Housekeeping: Unit Testing