ftf-cli 0.2.10

Facets Terraform Cli

FTF CLI

FTF CLI is a command-line interface (CLI) tool that facilitates module generation, variable management, validation, and registration in Terraform.

Installation

You can install FTF CLI using pip, pipx, or directly from source.

Installing with pip / pipx

Using pipx (recommended)

pipx install ftf-cli

Using pip

pip install ftf-cli

Installing from source

To install FTF CLI from source, follow these steps:

Prerequisites

• Python 3.9 or later
• Virtual environment (recommended)
• jq
• Git Bash

Steps

1. Clone the repository:

   git clone https://github.com/Facets-cloud/module-development-cli.git
   cd module-development-cli
   

2. Create a virtual environment (recommended):

   python -m venv env
   source env/bin/activate   # On Windows use `env\Scripts\activate`
   

3. Install the package:

   pip install -e .[dev]  # Install with development dependencies
   

Usage

After successful installation, you can use the ftf command to access CLI.

Commands:

Validate Facets

Validate the facets YAML file in the specified directory for correctness and schema compliance.

ftf validate-facets [OPTIONS] PATH

Arguments:

• PATH: Filesystem path to directory containing the facets YAML file.

Options:

• --filename TEXT: Name of the facets YAML file to validate (default: facets.yaml).

Notes:

• Checks existence and YAML syntax of the specified facets YAML file.
• Validates adherence to Facets schema including spec fields.
• Prints success message if valid; raises error and message if invalid.

Generate Module

Generate a new Terraform module structured by specifying intent, flavor, cloud provider, title, and description.

ftf generate-module [OPTIONS] /path/to/module

Options:

• -i, --intent: (prompt) The intent or purpose of the module.
• -f, --flavor: (prompt) The flavor or variant of the module.
• -c, --cloud: (prompt) Target cloud provider (e.g. aws, gcp, azure).
• -t, --title: (prompt) Human-readable title of the module.
• -d, --description: (prompt) Description outlining module functionality.

Notes:

• Automatically scaffolds module files based on standard templates.
• Cloud provider selection influences configuration details.
• Module is generated inside the specified path or current directory by default.

Add Variable

Add a new input variable to the Terraform module, supporting nested names and types.

ftf add-variable [OPTIONS] /path/to/module

Options:

• -n, --name: (prompt) Name allowing nested dot-separated variants. Use * for dynamic keys where you want to use regex and pass the regex using --pattern flag For example: 'my_var.*.key'.
• --title: (prompt) Title for the variable in facets.yaml.
• -t, --type: (prompt) Variable type, supports basic JSON schema types like string, number, boolean, enum.
• -d, --description: (prompt) A descriptive text explaining the variable.
• --options: (prompt) Comma-separated options used if the variable type is enum.
• --required: Optional flag to mark variable as required.
• --default: Optional way to provide a default value for the variable.
• -p, --pattern: (prompt) Provide comma separated regex for pattern properties. Number of wildcard keys and patterns must match. Eg: '"^[a-z]+$","^[a-zA-Z0-9._-]+$"'

Notes:

• Preserves terraform formatting while adding variables.
• Performs type validation before addition.
• Nested variables create the necessary nested structure internally.

Validate Directory

Perform validation on Terraform directories including formatting checks and security scans using Checkov.

ftf validate-directory /path/to/module [OPTIONS]

Options:

• --check-only: Only check formatting; does not make any changes.

Notes:

• Runs terraform fmt for formatting verification.
• Runs terraform init to ensure initialization completeness.
• Uses Checkov to scan Terraform files for security misconfigurations.
• Designed for fast feedback on module quality and security.

Login

Authenticate to a control plane and store credentials under a named profile for reuse.

ftf login [OPTIONS]

Options:

• -c, --control-plane-url: (prompt) Base URL of the control plane API (must start with http:// or https://).
• -u, --username: (prompt) Your login username.
• -t, --token: (prompt) Access token or API token (input is hidden).
• -p, --profile: (prompt) Profile name to save credentials under (default: "default").

Notes:

• URL format is validated before saving.
• Credentials are verified via the control plane API before storage.
• The selected profile becomes the default profile for future commands in the current session.
• Profile selection persists across terminal sessions, so you don't need to specify a profile for each command.
• Allows switching between multiple profiles/environments.

Add Input

Add an existing registered output type as an input to your Terraform module.

ftf add-input [OPTIONS] /path/to/module

Options:

• -p, --profile: (prompt) Profile to use for control plane authentication (default: "default").
• -n, --name: (prompt) Name of the input variable to add in facets.yaml and variables.tf.
• -dn, --display-name: (prompt) Human-readable display name for the input variable.
• -d, --description: (prompt) Description for the input variable.
• -o, --output-type: (prompt) The type of registered output to wire as input.

Notes:

• Updates facets.yaml required inputs and variables.tf accordingly.
• Facilitates parametrization of modules using control plane outputs.

Preview (and Publish) Module

Preview or register a Terraform module with the control plane from a specified directory.

ftf preview-module /path/to/module [OPTIONS]

Options:

• -p, --profile: (prompt) Profile to authenticate with (default: "default").
• -a, --auto-create-intent: Automatically create intent in control plane if it doesn't exist.
• -f, --publishable: Marks the module as production-ready and publishable.
• -g, --git-repo-url: Git repository URL where the module source code resides.
• -r, --git-ref: Git ref, branch, or tag for the module version.
• --publish: Flag to publish the module immediately after preview.

Notes:

• Environment variables such as GIT_REPO_URL, GIT_REF, FACETS_PROFILE can be used for automation or CI pipelines.
• If Git info is absent, module versioning defaults to a local testing version format (e.g. 1.0-{username}).

Expose Provider

Expose a Terraform provider as part of the module outputs with configurable name, version, attributes, and output.

ftf expose-provider [OPTIONS] /path/to/module

Options:

• -n, --name: (prompt) Name to assign to the provider.
• -s, --source: (prompt) Provider source URL or address.
• -v, --version: (prompt) Version constraint for the provider.
• -a, --attributes: (prompt) Comma-separated attributes map with equal sign (e.g., "attribute1=val1,depth.attribute2=val2").
• -o, --output: (prompt) Output block to expose the provider under.

Notes:

• Supports nested attribute keys using dot notation.
• If no default output exists, one of type intent "default" under facets.yaml will be created.

Add Import

Add import declarations to the module to specify resources that should be imported.

ftf add-import [OPTIONS] /path/to/module

Automatically discovers resources in the module and prompts for selecting a resource, naming the import, and specifying if it's required.

Options:

• -n, --name: The name of the import to be added. If not provided, will prompt interactively.
• -r, --required: Flag to indicate if this import is required. Default is True.
• --resource: The Terraform resource address to import (e.g., 'aws_s3_bucket.bucket').
• --index: For resources with 'count', specify the index (e.g., '0', '1', or '*' for all).
• --key: For resources with 'for_each', specify the key (e.g., 'my-key' or '*' for all).

Examples:

# Interactive mode
ftf add-import /path/to/module

# Non-interactive mode for regular resource
ftf add-import /path/to/module --name key_vault --resource azurerm_key_vault.key_vault

# Non-interactive mode for count resource
ftf add-import /path/to/module --name count_vault --resource azurerm_key_vault.count_key_vault --index 1

# Non-interactive mode for for_each resource
ftf add-import /path/to/module --name for_each_vault --resource azurerm_key_vault.for_each_key_vault --key my-key

# Non-interactive mode with full resource state address
ftf add-import /path/to/module --name for_each_vault --resource-address 'azurerm_key_vault.for_each_key_vault[0]'

Notes:

• Discovers and lists all resources defined in the module's Terraform files
• Supports resources with count or for_each meta-arguments
• Validates import names and resource addresses
• Updates the facets.yaml file with the import declarations in the format:

  imports:
    - name: s3_bucket
      resource_address: aws_s3_bucket.bucket
      required: true
  

Delete Module

Delete a registered Terraform module from the control plane.

ftf delete-module [OPTIONS]

Options:

• -i, --intent: (prompt) Intent of the module to delete.
• -f, --flavor: (prompt) Flavor of the module.
• -v, --version: (prompt) Version of the module.
• -s, --stage: (prompt) Deployment stage of the module.
• -p, --profile: (prompt) Authentication profile to use (default: "default").

Get Output Types

Retrieve the output types registered in the control plane for the authenticated profile.

ftf get-output-types [OPTIONS]

Options:

• -p, --profile: (prompt) Profile to authenticate as (default: "default").

Get Output Lookup Tree

Retrieve the detailed lookup tree for a registered output type from the control plane.

ftf get-output-lookup-tree [OPTIONS]

Options:

• -o, --output: (prompt) Name of the output type to query.
• -p, --profile: (prompt) Profile to use for authentication (default: "default").

Register Output Type

Register a new output type in the control plane using a YAML definition file.

ftf register-output-type YAML_PATH [OPTIONS]

Arguments:

• YAML_PATH: Path to the YAML definition file for the output type.

Options:

• -p, --profile: Profile name to use, defaults to environment variable FACETS_PROFILE if set, otherwise default.
• --inferred-from-module: Flag to mark the output type as inferred from a module.

Notes:

• The YAML file must include name and properties fields.
• The name should be in the format @namespace/name.
• You can include a providers section in the YAML to specify provider information.
• Ensures you're logged in before attempting to register the output type.

Get Resources

List all Terraform resources in the given module directory.

ftf get-resources /path/to/module

Arguments:

• /path/to/module: Filesystem path to the directory containing Terraform files.

Description:

• Discovers and lists all Terraform resources defined in the module's .tf files.
• Shows the resource address and whether it uses count or for_each.
• Useful for quickly auditing which resources are present in a module.

Example Output:

Found 3 resources:
- aws_s3_bucket.bucket
- aws_instance.web (with count)
- aws_security_group.sg (with for_each)

Contribution

Feel free to fork the repository and submit pull requests for any feature enhancements or bug fixes.

License

This project is licensed under the MIT License - see the LICENSE.md file for more details.