tfectl

command module
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 27, 2023 License: Apache-2.0 Imports: 1 Imported by: 0

README

tfectl

Tests GitHub license GoDoc Go Report Card GitHub issues

  • 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
  policy      Query TFE policies
  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
  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
  • 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 
      $ 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"
    }
  ]
  • 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 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"
      }
  ]
  • 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"
    }
  ]
  • 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"
    }
  ]
  • 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"
    }
  ]
Variables

  • 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

  • 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"
      }
  ]
Policy

  • 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

  • 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
  	}
  ]
Build
  • Using GNU Make
  make build
  • Linux
  $ make linux
  • Windows
  $ make windows

Contributing

  • see CONTRIBUTING.md

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.