Cloudcraft API Client for Python

The Cloudcraft Python library provides convenient access to the Cloudcraft API from applications written in Python.

Requirements

Client requirement...

• Python 3.10
• Requests 2.28

Installation

python -m pip install cloudcraftco

[TBD - standard pypi install, package name is preliminary] [see https://docs.python.org/3/installing/index.html]

Usage

The API is accessed through the Cloudcraft class. An API key available through the Cloudcraft user interface is required when instantiating Cloudcraft. It can be passed to the class as an argument or through the CLOUDCRAFT_API_KEY environment variable:

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft()

profile = cloudcraft.read_user_profile()

Configuration

Initialize with config object

The package can be initialized with several options:

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft({"api_key": "api-key-value", "timeout": 30000})

api_key must be provided via config object or environment variable.

Options may also be specified by environment variable...

Blueprints

List blueprints

cloudcraft = Cloudcraft()

blueprints = cloudcraft.list_blueprints()

Retrieve blueprint

cloudcraft = Cloudcraft()

blueprint_id = "BLUEPRINT-ID" # valid blueprint uuid
blueprint = cloudcraft.read_blueprint(blueprint_id)

Create blueprint

cloudcraft = Cloudcraft()

data = {"data": {"grid": "standard", "name": "New blueprint"}}
blueprint = cloudcraft.create_blueprint(data)

Update blueprint

cloudcraft = Cloudcraft()

blueprint_id = "BLUEPRINT-ID" # valid blueprint uuid
data = {"data": {"grid": "standard", "name": "Updated blueprint"}}
cloudcraft.update_blueprint(blueprint_id, data)

Export blueprint as image

cloudcraft = Cloudcraft()
script_dir = os.path.dirname(os.path.realpath(__file__)) + os.sep

bp_id = "BLUEPRINT-ID" # valid blueprint uuid
bp_format = "svg"
bp_file = script_dir + bp_id + "." + bp_format
export = cloudcraft.export_blueprint(bp_id, bp_format)

with open(bp_file, "wb") as binary_file:
    binary_file.write(export)

Delete blueprint

cloudcraft = Cloudcraft()

blueprint_id = "BLUEPRINT-ID" # valid blueprint uuid
cloudcraft.delete_blueprint(blueprint_id)

AWS Accounts

Add AWS account

cloudcraft = Cloudcraft()

# role must exist and match your api_key/account
role = "arn:aws:iam::{}:role/cloudcraft".format(aws_account_id)
data = {"name": "New AWS Account", "roleArn": role}
result = cloudcraft.create_aws_account(data)

List AWS accounts

cloudcraft = Cloudcraft()

accounts = cloudcraft.list_aws_accounts()

Snapshot AWS account

cloudcraft = Cloudcraft()
script_dir = os.path.dirname(os.path.realpath(__file__)) + os.sep

ss_account = "AWS-ACCOUNT" # valid account uuid for api-key
ss_region = "us-west-2"
ss_format = "png"
ss_file = script_dir + ss_region + "." + ss_format
snapshot = cloudcraft.snapshot_aws_account(ss_account, ss_region, ss_format)

with open(ss_file, "wb") as binary_file:
    binary_file.write(snapshot)

Update AWS account

cloudcraft = Cloudcraft()

account_id = "AWS-ACCOUNT" # valid account uuid for api-key
role = "AWS-ROLE" # valid role for AWS Account
data = {"name": "Updated Playground AWS Account.", "roleArn": role}
result = cloudcraft.update_aws_account(account_id, data)

Delete AWS account

cloudcraft = Cloudcraft()

account_id = "AWS-ACCOUNT" # valid account uuid for api-key
cloudcraft.delete_aws_account(account_id)

Get my AWS IAM Role parameters

cloudcraft = Cloudcraft()

iam_parameters = cloudcraft.read_aws_role_parameters()

Budgets

Export budget for a blueprint

cloudcraft = Cloudcraft()
script_dir = os.path.dirname(os.path.realpath(__file__)) + os.sep

bp_id = "BLUEPRINT-ID" # valid blueprint uuid
bp_format = "csv"
bp_file = script_dir + bp_id + "." + bp_format
export = cloudcraft.export_blueprint_budget(bp_id, bp_format)

with open(bp_file, "wb") as binary_file:
    binary_file.write(export)

Users

Get Cloudcraft account info

cloudcraft = Cloudcraft()

profile = cloudcraft.read_user_profile()

More information

See the Cloudcraft Developer API docs.

Development

Host Environment

cloudcraft-python was developed using...

• Python 3.7.15
• Poetry 1.1.14
• Tox 3.25.1

Host environment was macOS 12, but the other environments should work.

Earlier versions may work, but Python 3.10 is minimum supported version.

Running Playground (Examples)

Development examples showing how Cloudcraft API works running source code.

Testing accounts requires care, since creating an account requires valid role.

% cd {repo-directory}
% poetry env use python3.10
% poetry shell
% export CLOUDCRAFT_API_KEY={{ api-key }}
% export CLOUDCRAFT_TEST_ROLE={{ your-test-role-arn }}
% python3 dev_playgrounds/accounts.py
% python3 dev_playgrounds/blueprints.py
% python3 dev_playgrounds/budgets.py
% python3 dev_playgrounds/exports.py
% python3 dev_playgrounds/snapshots.py
% python3 dev_playgrounds/users.py

Running Tests

% poetry run pytest tests/unit
% poetry run pytest tests/functional
% tox

Formatting Code

% poetry run isort . --profile black
% poetry run black .

Checking Test Coverage

% poetry run coverage run --source=cloudcraftco --branch -m pytest .
% poetry run coverage html