tfc-client

Terraform Cloud API Python Client

Try to offer a good python object interface to Terraform Cloud API.

Quick start

from tfc_client import TFCClient
from tfc_client.enums import (
    RunStatus,
    NotificationTrigger,
    NotificationsDestinationType,
)
from tfc_client.models import VCSRepoModel

# Instanciate the client
client = TFCClient(token="WXDFR3ZSDFGYTdftredfgtre")

# Retreive any object type by ID from the client
my_org = client.get("organization", id="myorg")
my_ws = client.get("workspace", id="ws-gvcdr54dfd")
my_run = client.get("run", id="run-wvfgkdlz")
my_var = client.get("var", id="var-vcerjvjk")

# If you need to retreive a workspace by name, you need to retreive it from an organization object:
my_ws = my_org.workspace(name="my_workspace")

# Create a ssh key in the org
my_sshkey = my_org.create(
    "ssh-key",
    name="my-ssh-key,
    value="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAm6+JVgl...",
)

# To retreive all workspaces:
for ws in my_org.workspaces:
    print(ws.name)

# To retreive a subset of workspaces:
for ws in my_org.workspaces_search(search="my_"):
    print(ws.name)

# If you need to retreive all workspaces with associated current-run info efficiently (in one api call):
for ws in my_org.workspaces_search(include="current-run"):
    print(f"{ws.name} -> {ws.current_run.status}")

# To create a workspace linked with a github repository

# To create the binding between TFC and GitHub (to create a oauth_token_id):
# See: https://www.terraform.io/docs/cloud/vcs/github.html

# First: Create the repository object:
vcs_repo = VCSRepoModel(
    identifier="github/repo",
    oauth_token_id="ot-fgtredfgtr",
    branch="master",
    default_branch=True,
)

# Finally: Send the workspace object to TFC API:
my_ws = my_org.create(
    "workspace",
    name="my_workspace_test",
    terraform_version="0.11.10",
    working_directory="",
    vcs_repo=vcs_repo,
    source_name="TFC Python Client",
    source_url="https://pypi.org/project/tfc-client/"
)

# Assign a ssh-key to the workspace:
my_ws.assign("ssh-key", my_sshkey)

# Unassign it with:
# my_ws.unassign("ssh-key")

# Create a Notification configuration
my_notification = new_ws.create(
    "notification-configuration",
    enabled=True,
    name="MyNotif",
    url="https://httpstat.us/200",
    destination_type=NotificationsDestinationType.generic,
    token="TestToken",
    triggers=[NotificationTrigger.created],
)

# Launch a run on a workspace:
my_run = my_ws.create("run", message="Run run run")

# Wait for the run plan execution
if my_run.wait_plan(timeout=200, progress_callback=lambda run, duration: print(f"{run.id} status is {run.status}")):
    print(f"{my_run.id} reached the target status ({my_run.status})")
    # Display log of the plan (with ANSI color)
    print(my_run.plan.log_colored)

else:
    print(f"{my_run.id} is pending. Don't wait...")

if RunStatus(my_run.status) == RunStatus.planned:
    # Launch the Apply
    my_run.do_apply(comment="Apply !")
    # Wait for the run apply execution
    if my_run.wait_apply(timeout=200, progress_callback=lambda run, duration: print(f"{run.id} status is {run.status}")):
        print(f"{my_run.id} reached the target status ({my_run.status})")
        # Display log of the apply (with ANSI color)
        print(my_run.apply.log_colored)
    else:
        print(f"{my_run.id} is pending. Don't wait...")

# To retreive all runs of a workspace:
for run in my_ws.runs:
    print(f"{run.id}: {run.status}")

# Delete the workspace
my_org.delete(my_ws)

Current coverage of the TFC API

Currently the following endpoints are supported:

• Account
• Applies
• Configuration Versions
• Cost Estimates
• Notification Configurations
  • List
  • Show
  • Create
  • Update
  • Delete
  • Verify
• OAuth Clients
• OAuth Tokens
• Organizations
  • List
  • Show
  • Create
  • Update
  • Destroy
• Organization Tokens
• Plan Exports
• Plans
• Policies
• Policy Checks
• Policy Sets
• Registry Modules
• Runs
  • Create
  • Apply
  • List runs in a workspace
  • Get details
  • Discard
  • Cancel
  • Force cancel
  • Force execute
• SSH Keys
  • Create
  • Get
  • List
  • Update
  • Delete
• State Versions
• State Version Outputs
• Team Access
• Team Memberships
• Team Tokens
• Teams
• User Tokens
• Users
• Variables
  • Create
  • List
  • Update
  • Delete
• Workspaces
  • List
  • Show
  • Create
  • Update
  • Delete
  • Lock
  • Unlock
  • Force Unlock
  • Assigh SSH key
  • Unassign SSH key