JFryy/terraform-enterprise-api-python-client

Pyterprise

This is an object oriented client API for Terraform Enterprise written in Python. The methods included in this library generally map 1 to 1 in terms of function naming conventions to terraform enterprise documentation, so please review the available methods if you are uncertain on this library's usage.

Although this client library is maintained to a degree, I am not actively improving it. Please feel free to use this if it meets your needs, however if certain endpoints you need aren't covered here, or if upstream changes break any functionality, I heavily suggest using the officially maintained go library for tfe by Hashicorp or an alternative python library terrasnek which is actively maintained to a higher standard of quality than I have the bandwith to provide.

Happy Terraforming!

Installation:

This module can be installed via pip, this library is compatible with python3.7. Install it with pip for python3.

pip3 install --user pyterprise

Usage:

Note: Some examples are covered here, but more are covered in the examples directory for more basic use-cases of this api.

First import the module and authenticate using the init method, you can retrieve a token from the terraform enterprise UI.

import pyterprise

tfe_token = 'TOKENHERE'
client = pyterprise.Client()

# Supply your token as a parameter and the url for the terraform enterprise server.
# If you are not self hosting, use the one provided by hashicorp.
client.init(token=tfe_token, url='https://example-host.com')

After instantiating your client you need to set an organization to access workspaces and more. From the client base-level you can also create/destroy/list organizations:

# Set the organization
org = client.set_organization(id='my-organization')

# Base level Methods:
#organizations = client.list_organizations()
#client.destroy_organization(name='my-safe-to-delete-org')
#client.create_organization(name='test', email='test@test.com')

This organization object org has access to workspaces, ssh keys and other methods (Check source code/examples for more):

# Creating a workspace with VCS example:
vcs_options = {
    "identifier": "my-github-org/my-repo",
    "oauth-token-id": "ot-xxxxxxxxxxx",
    "branch": "master",
    "default-branch": False
}
org.create_workspace(name='test-delete-me2',
                     vcs_repo=vcs_options,
                     auto_apply=False,
                     queue_all_runs=False,
                     working_directory='/',
                     trigger_prefixes=['/'])
                              
# Or Delete a workspace at the organization level by name.
org.delete_workspace(name='my-safe-to-delete-test-workspace')

You can access workspace objects through your organization client object, which gives you access to runs, plans, statefiles, ssh-key additions and variables.

# Get a single workspace client object, 
# you can also list or search all workspace objects using the corresponding methods.
workspace = org.get_workspace('test-workspace')

# Get a list of all workspace objects in an organization.
for workspace in org.list_workspaces():
    print(workspace)

# Print some workspace attributes. Additionally you can access all attributes 
# as a dictionary by printing  the 'workspace' object at top level.                     
print(workspace.name, workspace.id, workspace.created_at)

# Run Workspace, you can destroy by changing the destroy flag.
workspace.run(destroy_flag=False)

# Plan and Apply in workspace with log output
workspace.plan_apply(destroy_flag=False)

# Update workspace, arguments identical to create function. Omit arguments to not alter.
workspace.update(auto_apply=True)

# Create a variable in a workspace
workspace.create_variable(key='foo', value='bar', sensitive=False, category='env')

# Print all variables for a workspace. 
# Variables objects also have functions for updating and deleting.
for variable in workspace.list_variables():
    print(variable)
    

# Apply latest unconfirmed plan in workspace. You can additionally print all attributes by print object at top level.
# or use other runs methods i.e. cancel, discard and get plan output etc.
for run in workspace.list_runs(page=1, page_size=20):
    if run.status == 'planned':
        run.apply(comment='Running latest plan.')

Please consult module contents, examples or terraform enterprise api documentation for more api client usage. This API does not currently cover administrative functions and teams, help is wanted for expanding functionality. Thank you.