tfx is a standalone CLI for Terraform Cloud and Terraform Enterprise.
The initial focus of tfx is to execute the API-Driven workflow for a Workspace, but will expand to other common workflows that, in the past, have required API wrappers.
Note: This CLI is still under active development, subject to change, and not officially supported by HashiCorp.
As a consumer of TFC/TFE I want to leverage the full capabilities without having to write curl/python/(insert other) libraries to call the API. Often times these tasks are part of my pipeline, but could also be administrative tasks that are done from a local machine.
Common API-Driven Workflow Challenges:
- The CLI-Driven workflow presents several challenges when creating more advanced pipelines for a Workspace run, specifically the inability to insert a gate check between a plan and apply, (in other words you must run a
terraform apply -auto-approve
). - The CLI driven workflow requires a
terraform init
that forces a download of providers before a plan can be called remotely, these providers are never actually used on the local host and can be difficult to source airgapped environments. - Implementing an API-Driven workflow requires several API calls to perform a plan/apply.
- It is unlikely that the full range of features will be built into Terraform.
- Developing CI/CD specific plugins for even the most common tools is not feasible, and ignores the ability to run the commands locally.
Binaries are created as part of release, check out the Release Page for the latest release.
MacOs Installation
version="0.0.3-dev"
curl -L -o tfx "https://github.com/straubt1/tfx/releases/download/${version}/tfx_darwin_amd64"
chmod +x tfx
Linux Installation
version="0.0.3-dev"
curl -L -o tfx "https://github.com/straubt1/tfx/releases/download/${version}/tfx_linux_amd64"
chmod +x tfx
Windows Installation
version="0.0.3-dev"
curl -L -o tfx.exe "https://github.com/straubt1/tfx/releases/download/${version}/tfx_windows_amd64"
Each command has the ability to pass in parameters via flags, several are required for every command.
Example:
--tfeHostname string The hostname of TFE without the schema. Can also be set with the environment variable TFE_HOSTNAME. (default "app.terraform.io")
--tfeOrganization string The name of the TFx Organization. Can also be set with the environment variable TFE_ORGANIZATION.
--tfeToken string The API token used to authenticate to TFx. Can also be set with the environment variable TFE_TOKEN.
Flags can also be created in a configuration file with the file name ".tfx.hcl". Flags can also be set via environment values by using a key that is capitalized version of the flag.
For convenience this file will automatically load if it is in the hosts home directory or current working directory.
Example:
./.tfx.hcl
tfeHostname = "tfe.rocks" (omit to default to Terraform Cloud)
tfeOrganization = "my-awesome-org"
tfeToken = "<Generated from Terraform Enterprise or Terraform Cloud>"
You can also specify this file via the --config
flag.
Create a Plan
# Create a speculative plan that can not be applied
tfx plan -w tfx-test -s
# Create a plan that can be applied
tfx plan -w tfx-test
# Create a Configuration Version based on terraform in the current directory
tfx cv create -w tfx-test
# Create a Configuration Version based on terraform in a supplied directory
tfx cv create -w tfx-test -d ./myterraformfolder/
# Create a plan based on a configuration version
tfx plan -w tfx-test -i cv-HKE8gevVtGBXapcq
Create an Apply
tfx apply -r <run-id>
Create a plan to execute on TFx.
tfx plan
- Create a Workspace plan based on a current directory
tfx plan export
- Create and download a Sentinel Mock from a plan
Create an apply to execute on TFx.
tfx apply
- Apply a Workspace plan based on a plan
Managing Workspace Runs.
tfx run list
- List all Runs for a supplied Workspace
tfx run create
- Create a Run for a supplied Workspace
tfx run show
- Show Run details for a supplied Run
Managing Workspace Configuration Versions.
tfx cv list
- List all Configuration Versions for a supplied Workspace
tfx cv create
- Create a Configuration Version for a supplied Workspace
tfx cv show
- Show Configuration Version details for a supplied Configuration
Managing Private Module Registry modules.
tfx pmr list
- List all modules in the PMR
tfx pmr create
- Create a module in the PMR
tfx pmr create version
- Create a version of a module in the PMR
tfx pmr show
- Show module details for a supplied module
tfx pmr show versions
- Show modules versions for a supplied module
tfx pmr delete
- Delete a module from the PMR
tfx pmr delete version
- Delete a specific module version from the PMR
tfx pmr download
- Download a specific module version of TF code
Managing Workspace State Files (State Versions).
tfx state list
- List all State Versions for a supplied Workspace
tfx state show
- Show state details for a supplied State Version
tfx state download
- Download a specific State Version
tfx state create
- Create a new State Version with a supplied state file
- There is no way to delete State Versions
- The LAST State Version to be created is the "current" state file that will be used by the Workspace
- A Workspace must be locked to create new State Versions
- The "serial" attribute must be incremented
- The "lineage" attribute must be the same for any newly created State Version
- The API does not return a state versions lineage, you must download the file and parse to get the lineage
Managing Terraform Versions in a Terraform Enterprise install (TFE only).
tfx tfv list
- List all Terraform Versions for a TFE install
tfx tfv show
- Show version details for a supplied Terraform Version or Version Id
tfx tfv delete
- Delete a version of a supplied Terraform Version or Version Id
tfx tfv create
- Create a Terraform Version
tfx tfv create official
- Create an official Terraform Version from releases.hashicorp.com
tfx tfv disable
- Disable a Terraform Version(s), accepts comma separated list
tfx tfv disable all
- Disable all Terraform Versions
tfx tfv enable
- Enables a Terraform Version(s), accepts comma separated list
tfx tfv enable all
- Enables all Terraform Versions
tfx workspace list
- Using the "--search" flag allows filtering by workspaces with a given string
- Using the "--run-status" flag allows filtering by workspaces with a current run with a given status (full list of available run statuses can be found here)
tfx workspace list all
- Using the "--search" flag allows filtering by workspaces with a given string
tfx workspace lock
- Lock a given workspace by name, in a given organization
tfx workspace lock all
- Lock all workspaces in a given organization
tfx workspace unlock
- Unlock a given workspace by name, in a given organization
tfx workspace unlock all
- Unlock all workspaces in a given organization
Additional commands to implement.
-
tfx run
-
cancel
, cancel, discard, force cancel a run
-
-
tfx pmr
-
search
find a module https://www.terraform.io/docs/registry/api.html#search-modules
-
-
tfe sentinel
-
list
, list policy sets -
create
, create a policy set -
delete
, deletes a policy set -
assign
, assigns a WS(s) to the policy set
-
Thank you for your interest in contributing!
Contributing guide coming soon
https://github.com/hashicorp/go-tfe