tfectl

README

tfectl

• CLI Utility to query/manage TFE inspired by tfe-cli

Setup

• Copy the binary (either Windows or Linux) to a path on your machine. Add the .exe extension if using it on Windows

  PS> .\tfectl.exe
  Query TFE from the command line.
  
  Usage:
    tfectl [command]
  
  Available Commands:
    admin        Manage TFE admin operations
    completion   Generate the autocompletion script for the specified shell
    help         Help about any command
    plan         Query TFE Plans
    policy       Query TFE policies
    policy-check Manage policy check workflows of a TFE run
    policy-set   Query TFE policy sets
    run          Manage TFE runs
    tag          Query TFE tags
    team         Manage TFE teams
    variable     Manage TFE workspace variables
    workspace    Manage TFE workspaces
  
  
  Flags:
    -h, --help                  help for tfectl
    -l, --log string            log level (debug, info, warn, error, fatal, panic)
    -o, --organization string   terraform organization or set TFE_ORG
    -q, --query string          JQ compatible query to parse JSON output
    -t, --token string          terraform token or set TFE_TOKEN
    -v, --version               version for tfectl
  
  Use "tfectl [command] --help" for more information about a command.
  

Initialization

• TFE_ADDRESS: TFE URL defaults to https://app.terraform.io/
• TFE_ORG: TFE Organization
• TFE_TOKEN: token with read access to Organization specified in TFE_ORG
• Additionally TFE_ORG and TFE_TOKEN variables can be passed via CLI

Usage

• To see available options

# /sbin/tfectl --help
Query TFE from the command line.

Usage:
  tfectl [command]

Available Commands:
  admin        Manage TFE admin operations
  completion   Generate the autocompletion script for the specified shell
  help         Help about any command
  policy       Query TFE policies
  policy-check Manage policy check workflows of a TFE run
  policy-set   Query TFE policy sets
  run          Manage TFE runs
  tag          Query TFE tags
  team         Manage TFE teams
  variable     Manage TFE workspace variables
  workspace    Manage TFE workspaces


Flags:
  -h, --help                  help for tfectl
  -l, --log string            log level (debug, info, warn, error, fatal, panic)
  -o, --organization string   terraform organization or set TFE_ORG
  -q, --query string          JQ compatible query to parse JSON output
  -t, --token string          terraform token or set TFE_TOKEN
  -v, --version               version for tfectl

Use "tfectl [command] --help" for more information about a command.

Workspace

Workspace Operations

• List

  • Run with no arguments to return the following for all workspaces in the Org

    Field	Description	Type
    name	Name of the workspace	string
    id	ID of the workspace	string
    locked	Status of the workspace	bool
    execution_mode	Whether the workspace runs remotely, locally or on an agent	string
    terraform_version	Version of Terraform CLI running in the workspace	string
    tags	List of tags against workspace	list

  • Run with --filter, which takes a workspace name or a substring of a name to get a filtered list of workspaces

    $ tfectl workspace list --filter workspace-1
    [
      {
        "name": "workspace-1",
        "id": "ws-RZP914jsX1Hmc9Yo"
        "locked": false,
        "execution_mode": "remote",
        "terraform_version": "1.3.0"
        "tags": [
            "tag:1",
            "tag:2"
        ]
      }
    ]
  

  • The --filter flag supports filtering by workspace tags using a prefix of tags|

    $ tfectl workspace list --filter "tags|tag:1,tag:2"
    [
      {
        "name": "workspace-1",
        "id": "ws-RZP914jsX1Hmc9Yo"
        "locked": false,
        "execution_mode": "remote",
        "terraform_version": "1.3.0"
        "tags": [
            "tag:1",
            "tag:2"
        ]
      },
      {
        "name": "workspace-2",
        "id": "ws-eLcff9y8r8bRBYfj"
        "locked": false,
        "execution_mode": "remote",
        "terraform_version": "1.3.7"
        "tags": [
            "tag:1",
            "tag:2"
        ]
      }
    ]
  

  • Run with the --detail flag to return the following details NOTE: This task takes a long time, it rate-limited and it is recommended to run it with the --filter argument

    Field	Description	Type
    name	Name of the workspace	string
    id	ID of the workspace	string
    locked	Status of the workspace	bool
    execution_mode	Whether the workspace runs remotely, locally or on an agent	string
    terraform_version	Version of Terraform CLI running in the workspace	string
    tags	List of tags against workspace	list
    created_days_ago	How many days ago this workspace was created	string
    updated_days_ago	How many days ago this workspace was updated	string
    last_remote_run_days_ago	How many days ago was a remote run performed in this workspace	string
    last_state_update_days_ago	How many days ago was the terraform state updated in this workspace	string
    average_run_duration	Average duration, in seconds, of a planned-and-applied run	string

    $ tfectl workspace list --filter workspace-1 --detail
    [
      {
        "name": "workspace-1",
        "id": "ws-RZP914jsX1Hmc9Yo",
        "locked": false,
        "terraform_version": "1.3.0",
        "tags": [
            "tag:1",
            "tag:2"
        ]
        "created_days_ago": "819.167082",
        "updated_days_ago": "2.279692",
        "last_remote_run_days_ago": "2.281231",
        "last_state_update_days_ago": "30.174812",
        "average_run_duration": "16.334562"
      }
    ]
  

• Lock/Unlock

  • Run with a comma-separated string of workspaceIDs or a workspaceName filter (mutually exclusive)

    $ tfectl workspace lock --ids ws-SxWNNcYPkLD48ZC7
    [
      {
        "id": "ws-SxWNNcYPkLD48ZC7",
        "locked": true,
        "name": "test-workspace-1"
      }
    ] 
  

  • Operation can be run against a workspace that is already locked

    $ tfectl workspace lock --filter dev-workspace
    [
      {
        "id": "ws-5xUNCXVKrryoPcEp",
        "locked": true,
        "name": "dev-workspace"
      }
    ]
  

  • Optionally the lock operation takes a --reason argument

• Lock All/ Unlock All

  • Locks/Unlocks all workspaces in the specified org

    $ tfectl workspace lockall
    [
      {
        "id": "ws-SxWNNcYPkLD48ZC7",
        "locked": true,
        "name": "test-workspace-1"
      },
      {
        "id": "ws-LXkPCWnJKJ1FSgjs",
        "locked": true,
        "name": "uat-workspace"
      },
      {
        "id": "ws-E9o8VitHDAvCp3wj",
        "locked": true,
        "name": "uat-2-workspace"
      },
      {
        "id": "ws-5xUNCXVKrryoPcEp",
        "locked": true,
        "name": "dev-workspace"
      }
    ]
  

Runs

Run Operations

• run sub-command lets you manage runs against one or more workspaces

• List run

  • List runs in workspace specified by workspaceID
  • --status refers to valid Run.Status attributes
  • --operation refers to valid Run.Operation attributes

    $ tfectl run list --workspace-id ws-NMH66XMnUeF8duTx --status "policy_checked"
    [
        {
            "id": "run-zQFc5h2uPhEWW9Sr",
            "status": "policy_checked",
            "workspace_id": "ws-NMH66XMnUeF8duTx",
            "workspace_name": "tfc-infra-workspace",
            "created_at": "2024-09-24T06:12:56Z",
            "run_duration": "54.476822"
        }
    ]
  

• Bulk Queue

  • Bulk queue plans against one or many workspaces

    $ tfectl run queue --filter workspace-sandbox
    [
      {
        "id": "run-pX9Lrq5KCrsgCYFH",
        "workspace_id": "ws-DpeRu7KpazXEWKoJ",
        "workspace_name": "workspace-sandbox",
        "status": "pending",
        "created_at": "2024-09-24T06:12:56Z",
        "run_duration": "NA"
      }
    ]
  

• Apply runs

  • Apply pending plans - takes a comma-separated-string of runIDs

    $ tfectl run apply --ids run-UowKQd1cF7bgNfCp
    [
      {
        "id": "run-UowKQd1cF7bgNfCp",
        "workspace_id": "ws-N2qoyJxF1TkfeRYy",
        "workspace_name": "test-workspace-2",
        "status": "applying",
        "created_at": "2024-09-24T06:12:56Z",
        "run_duration": "NA"
      }
    ]
  

• Query runs

  • Query/Get run-details from runIDs

    $ tfectl run get --ids run-UowKQd1cF7bgNfCp
    [
      {
        "id": "run-UowKQd1cF7bgNfCp",
        "workspace_id": "ws-N2qoyJxF1TkfeRYy",
        "workspace_name": "test-workspace-2",
        "status": "applied",
        "created_at": "2024-09-24T06:12:56Z",
        "run_duration": "180.452271"
      }
    ]
  

Variables

Variable Operations

• CRUD operations on workspace variables

• Query/List workspace variables

    $ tfectl variable list --workspace-filter workspace-sandbox
    [
      {
        "workspace_id": "ws-DpeRu7KpazXEWKoJ",
        "workspace_name": "workspace-sandbox",
        "variables": [
          {
            "id": "var-RH7Q9pyD8gtgabtz",
            "key": "WORKSPACE_VAR_1",
            "value": "",
            "description": "",
            "category": "env",
            "hcl": false,
            "sensitive": false
          },
          {
            "id": "var-wQutb5uQeSb4SwRn",
            "key": "workspace_tf_var",
            "value": "",
            "description": "",
            "category": "terraform",
            "hcl": false,
            "sensitive": true
          },
          {
            "id": "var-cSB5E11TRewuyfd9",
            "key": "WORKSPACE_VAR_2",
            "value": "",
            "description": "",
            "category": "env",
            "hcl": false,
            "sensitive": false
          },
          {
            "id": "var-SP4Lcue83mCKVvHW",
            "key": "WORKSPACE_SECRET_VAR",
            "value": "",
            "description": "",
            "category": "env",
            "hcl": false,
            "sensitive": true
          }
        ]
      }
    ]
  

• Create new workspace variable

    $ tfectl variable create --workspace-id ws-DpeRu7KpazXEWKoJ --description "test" --key "testCLI" --value "testCLI value" --sensitive true --type terraform --hcl
    {
      "id": "var-uCgZrzkPhis6qXTS",
      "key": "testCLI",
      "value": "",
      "description": "test",
      "category": "terraform",
      "hcl": true,
      "sensitive": true
    }
  

• Update existing workspace variable

    $ tfectl variable update --variable-id var-uCgZrzkPhis6qXTS --workspace-id ws-DpeRu7KpazXEWKoJ --value "test CLI Value 2" --key "testCLI" --hcl --sensitive true
    {
      "id": "var-uCgZrzkPhis6qXTS",
      "key": "testCLI",
      "value": "",
      "description": "Variable Updated by tfectl",
      "category": "terraform",
      "hcl": true,
      "sensitive": true
    }
  

• Delete existing workspace variable

    $ tfectl variable delete --variable-id var-uCgZrzkPhis6qXTS --workspace-id ws-DpeRu7KpazXEWKoJ
    # Returns current variables (similar to variable list)
    [
      {
        "workspace_id": "ws-DpeRu7KpazXEWKoJ",
        "workspace_name": "workspace-sandbox",
        "variables": [
          {
            "id": "var-RH7Q9pyD8gtgabtz",
            "key": "WORKSPACE_VAR_1",
            "value": "",
            "description": "",
            "category": "env",
            "hcl": false,
            "sensitive": false
          },
          {
            "id": "var-wQutb5uQeSb4SwRn",
            "key": "workspace_tf_var",
            "value": "",
            "description": "",
            "category": "terraform",
            "hcl": false,
            "sensitive": true
          },
          {
            "id": "var-cSB5E11TRewuyfd9",
            "key": "WORKSPACE_VAR_2",
            "value": "",
            "description": "",
            "category": "env",
            "hcl": false,
            "sensitive": false
          },
          {
            "id": "var-SP4Lcue83mCKVvHW",
            "key": "WORKSPACE_SECRET_VAR",
            "value": "",
            "description": "",
            "category": "env",
            "hcl": false,
            "sensitive": true
          }
        ]
      }
    ]
  

• Create variables from file

    $ tfectl variable create from-file --file variables.json --workspace-id ws-DpeRu7KpazXEWKoJ
    [
      {
        "id": "var-oDNV14eJf9ijjcc2",
        "key": "test1",
        "value": "value1",
        "description": "Test Variable 1",
        "category": "env",
        "hcl": false,
        "sensitive": false
      },
      {
        "id": "var-e1vFqg3ooToLi5xR",
        "key": "test2",
        "value": "",
        "description": "Test Variable 2 - sensitive",
        "category": "env",
        "hcl": false,
        "sensitive": true
      }
    ]
  

Admin

Admin Operations - TFE ONLY

• Perform Admin operations supported by the TFE Admin API.

• NOTE: Admin settings are only available in Terraform Enterprise.

• Runs

  • List - Lists Runs filtered on run status - querying the admin/runs endpoint

    $ tfectl admin run list --filter "plan_queued" --query '.[] | .id'
    [
        "run-4LuSKSss9KH2NAPN",
        "run-HCL7LVz67hVHEgsx",
        "run-ozEfahr1YrDQNokG",
        "run-hqWdU7BMuQPpqFrE",
        "run-BstJ5RJKFGmYnCni",
        "run-7WCMcDf8GZxYGqjN",
        "run-ZtzW7Xb5k6cfmgNK",
        "run-WC4q9Ec3vernx7Sc",
        "run-q9Lak8i1rzS5mXFU",
        "run-gbJyJAT89tzC2ziz",
        "run-MLMzcUuoSZL8Tz8C",
        "run-nbSKBf9CLRjPbj1q",
        "run-faqeyLU2VMBcHPJQ",
        "run-hB6RqJtY1SuGWsHF",
        "run-6HaUc4T31yZsENmC",
        "run-vPvYHNrjBCD6Y3ke",
        "run-ENdFcVpEp2AMLxNr",
        "run-kxgmgdReVzrVopVG"
    ]
  

  • Force-Cancel - Force cancels runIDs

    $ tfectl admin run force-cancel --ids run-UFaNv3rz5XnzPhCh
    [
        {
            "id": "run-UFaNv3rz5XnzPhCh",
            "workspace_id": "ws-ojAyfT3ar4oXt3eA",
            "workspace_name": "workspace-infrastructure-production",
            "status": "cancelling"
        }
    ]
  

Plan

Query plan summary

• Query plan summary in TFE/TFC

• Show

    $ tfectl plan show --ids plan-CRetbA3L01BsxeLq
    [
        {
            "id": "plan-CRetbA3L01BsxeLq",
            "has_changes": true,
            "status": "finished",
            "resource_additions": 2,
            "resource_changes": 0,
            "resource_destructions": 0,
            "resource_imports": 0,
            "changed_resource_properties": null
        }
    ]
  

• Show plan details (--detailed-changes flag)

    $ tfectl plan show --ids plan-v6Li1Qvx3hbaKmGi --detailed-changes
    [
        {
            "id": "plan-v6Li1Qvx3hbaKmGi",
            "has_changes": true,
            "status": "finished",
            "resource_additions": 3,
            "resource_changes": 0,
            "resource_destructions": 2,
            "resource_imports": 0,
            "changed_resource_properties": [
                {
                    "action": [
                        "create"
                    ],
                    "address": "random_password.this",
                    "attribute_changes": {
                        "keepers": "null -> null",
                        "length": "null -> 12",
                        "lower": "null -> true",
                        "min_lower": "null -> 0",
                        "min_numeric": "null -> 0",
                        "min_special": "null -> 0",
                        "min_upper": "null -> 0",
                        "number": "null -> true",
                        "numeric": "null -> true",
                        "override_special": "null -> null",
                        "special": "null -> true",
                        "upper": "null -> true"
                    }
                },
                {
                    "action": [
                        "delete",
                        "create"
                    ],
                    "address": "terraform_data.scratch[0]",
                    "attribute_changes": {
                        "triggers_replace": "(null) -> ({})"
                    }
                },
                {
                    "action": [
                        "delete",
                        "create"
                    ],
                    "address": "terraform_data.scratch[1]",
                    "attribute_changes": {
                        "triggers_replace": "(null) -> ({})"
                    }
                }
            ]
        }
    ]
  

Policy

Policy Operations

• Query policies in TFE/TFC

• List

    $ tfectl policy list --filter "production-tagging"
    [
      {
        "id": "pol-5Qgo4h2mp2z68u3N",
        "name": "production-tagging",
        "kind": "sentinel",
        "enforce": "hard-mandatory",
        "policy_set_count": 1
      }
    ]
  

Tag

Tag Operations

• Query Organization tag information in TFE/TFC

• List

  • The --filter flag takes a comma separated list of workspaceIds, and returns a list of all organization tags excluding the tags associated with these workspaces

    $ tfectl tag list --filter ws-ojAyfT3ar4oXt3eA
    [
    	{
    		"name": "tag:infrastructure",
    		"id": "tag-kuyrvHJPWUNY6BCG",
    		"instance_count": 1
    	},
    	{
    		"name": "tag:application1",
    		"id": "tag-X8oXEEMsNoU61D99",
    		"instance_count": 2
    	},
    	{
    		"name": "tag:application2",
    		"id": "tag-49e9MLKrGFyLS9aT",
    		"instance_count": 2
    	}
    ]
  

  • The --search flag returns details of the specified organization tag

    $ tfectl tag list --search "tag:infrastructure"
    [
    	{
    		"name": "tag:infrastructure",
    		"id": "tag-kuyrvHJPWUNY6BCG",
    		"instance_count": 1
    	}
    ]
  

Policy Set

Policy Set Operations

* Query policy sets in TFE/TFC

• 1. List

  • Lists all policy sets

    $ tfectl policy-set list
    [
        {
            "id": "polset-7586a2UeKeNgPD3s",
            "name": "dev-policy-set",
            "kind": "sentinel",
            "global": false,
            "workspaces": null,
            "workspace_count": 5,
            "workspace_exclusions": null,
            "projects": [
                "prj-LsSPiJnMYl7tSMZ"
            ],
            "project_count": 1,
            "policies": [
                "pol-B3pWfMyAzR2VtQI"
            ],
            "policy_count": 1
        },
        {
            "id": "polset-Q8zN9Q6TfMVs8mu",
            "name": "prod-policy-set",
            "kind": "sentinel",
            "global": false,
            "workspaces": null,
            "workspace_count": 10,
            "workspace_exclusions": null,
            "projects": [
                "prj-yOtqzR2msFUFCDx"
            ],
            "project_count": 1,
            "policies": [
                "pol-Lm0WgxPdwUm2zGE",
                "pol-crBeEEB5b8EZtaB"
            ],
            "policy_count": 2
        }
    ]
  

Policy Check

Policy Check Operations

• Examine the details of a policy check performed against a given RunID

• 1. Show

  • Generates the details of a policy check performed against a RunID

    $ tfectl policy-check show --run-id run-A8PuL0GnIeldng1
    {
        "id": "polchk-ndVuh5Y2abygp5fu",
        "result": {
            "advisory_failed": 2,
            "hard_failed": 0,
            "passed": 46,
            "result": true,
            "soft_failed": 0,
            "total_failed": 2,
            "sentinel": {
                "data": {
                    "policy-set-01": {
                        "error": null,
                        "policies": [
                            {
                                "error": null
                                # OUTPUT TRUNCATED
                            } # OUTPUT TRUNCATED
                        ] # OUTPUT TRUNCATED
                    } # OUTPUT TRUNCATED
                }
            }
        }
    }
  

  • To query only those checks which have failed

    $ tfectl policy-check show --run-id run-Wxk42edRCCLB5fMi --query '.result.sentinel.data | to_entries | .[].value.policies | .[] | select(.result|not) | .policy'
    [
        {
            "enforcement-level": "advisory",
            "name": "policy-set-01/deploy-to-approved-regions"
        },
        {
            "enforcement-level": "advisory",
            "name": "policy-set-02/iaas-allowed-vm-skus"
        }
    ]
  

• 2. Override

  • Where applicable, overrides policy checks with a given PolicyCheckID

  $ tfectl policy-check override --policy-check-id polchk-s6moSXCk5e7dm1oR
  {
      "id": "polchk-s6moSXCk5e7dm1oR",
      "result": {
          "advisory_failed": 0,
          "hard_failed": 0,
          "passed": 0,
          "result": false,
          "soft_failed": 1,
          "total_failed": 1,
          "sentinel": {
              "data": {
                  "": {
                      "duration": 0,
                      "error": null,
                      "policies": [
                      # OUTPUT TRUNCATED
                      ],
                      "result": false,
                      "warnings": null
                  }
              },
              "schema-version": 1
          }
      },
      "status": "overridden", # OVERRIDDEN
      "scope": "organization"
  }
  

Registry Modules

Private Registry Module Operations

• Query Private Modules in the Organization registry

• 1. List

  • List all available Modules in the Organization registry

    $ tfectl registry-module list --query '.[] | select(.provider == "azurerm")'
    [
        {
            "id": "mod-DHAq8Casdas32uC",
            "module_latest_version": "2.0.4",
            "name": "windows-instance",
            "namespace": "MyNamespace",
            "provider": "azurerm",
            "publishing_mechanism": "git_tag",
            "registry_name": "private",
            "status": "setup_complete",
            "test_config": true,
            "vcs_repo": "MyGHOrg/terraform-azurerm-windows-instance"
        }
    ]
  

Registry Providers

Private Provider Registry Operations

• Query Private Providers in Organization Registry

• 1. List

  • List all available Private Providers in the Organization Registry

    $ tfectl registry-provider list
    [
        {
            "id": "prov-5fws9JKkNQZDz2Gf",
            "name": "aws",
            "namespace": "MyTFCOrg",
            "registry_name": "private"
        },
        {
            "id": "prov-bGhLiwy6APQ9r4dZ",
            "name": "azure",
            "namespace": "MyTFCOrg",
            "registry_name": "private"
        }
    ]
  

• 2. Get

  • Get details of given Private provider

    $ tfectl registry-provider get --name aws
    {
        "id": "prov-5fws9JKkNQZDz2Gf",
        "name": "aws",
        "namespace": "MyTFCOrg",
        "registry_name": "private",
        "provider_latest_version": "5.32.2",
        "provider_platforms": [
            {
                "id": "provpltfrm-wCCMzzy91Rfdj6PW",
                "os": "linux",
                "arch": "amd64",
                "filename": "terraform-provider-awx_5.32.2_linux_amd64.zip"
            },
            {
                "id": "provpltfrm-c9jhJ2tmwEbbwuTV",
                "os": "windows",
                "arch": "amd64",
                "filename": "terraform-provider-awx_5.32.2_windows_amd64.zip"
            }
        ]
    }
  

Build

GoReleaser is used to produce binaries for multiple platforms (Windows, Mac, Linux).

To build all binaries locally:

• Install GoReleaser https://goreleaser.com/install/
• Run the build target command:

  $ make build

• Binaries will be built and output to the /dist folder.

Contributing

• see CONTRIBUTING.md