Skip to main content

Python SDK for rendering AWS and Azure diagrams using the Cloudcraft API.

Project description

Cloudcraft API Client for Python

License: Apache 2.0 versions Build Status

Cloudcraft diagram

Visualize your cloud architecture with Cloudcraft by Datadog, the best way to create smart AWS and Azure diagrams.

Cloudcraft supports both manual and programmatic diagramming, as well as automatic reverse engineering of existing cloud environments into beautiful system architecture diagrams.

This cloudcraftco Python library provides an easy-to-use native Python SDK for interacting with the Cloudcraft API.

Use case examples:

  • Snapshot and visually compare your live AWS or Azure environment before and after a deployment, in your app or as part of your automated CI pipeline
  • Download an inventory of all your cloud resources from a linked account as JSON
  • Write a converter from a third party data format to Cloudcraft diagrams
  • Backup, export & import your Cloudcraft data
  • Programmatically create Cloudcraft diagrams

This SDK requires a Cloudcraft API key to use. A free trial of Cloudcraft Pro with API access is available.

Requirements

  • Python 3.10
  • Requests 2.28

Installation

python3.10 -m pip install cloudcraftco

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.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

profile = cloudcraft.read_user_profile()

Configuration

Initialize with config object

The package can be initialized with several options:

from cloudcraftco.cloudcraft import Cloudcraft

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

api_key must be provided via config object or environment variable.

Option Default Description
api_key API Key associated with Cloudcraft account
maxNetworkRetries 10 The amount of times a request should be retried
timeout 80000 Maximum time each request can take in ms
host 'api.cloudcraft.co' Host that requests are made to
port 443 Port that requests are made to
protocol 'https' 'https' or 'http'

Options may also be specified by environment variable...

Option Environment Variable
api_key CLOUDCRAFT_API_KEY
maxNetworkRetries CLOUDCRAFT_MAX_NETWORK_RETRIES
timeout CLOUDCRAFT_TIMEOUT
host CLOUDCRAFT_HOST
port CLOUDCRAFT_PORT
protocol CLOUDCRAFT_PROTOCOL

Blueprints

List blueprints

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

blueprints = cloudcraft.list_blueprints()

Retrieve blueprint

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

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

Create blueprint

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

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

Update blueprint

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

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

Delete blueprint

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

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

Export blueprint as image

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
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)

AWS Accounts

Add AWS account

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
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

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

accounts = cloudcraft.list_aws_accounts()

Update AWS account

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
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

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

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

Get my AWS IAM Role parameters

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

iam_parameters = cloudcraft.read_aws_role_parameters()

Snapshot AWS account

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
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)

Azure Accounts

Add Azure account

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

# id and secret values must be valid
data = {
    "name": "Azure Account",
    "subscriptionId": "subscriptionId",
    "directoryId": "directoryId",
    "applicationId": "applicationId",
    "clientSecret": "clientSecret"
}
result = cloudcraft.create_azure_account(data)

List Azure accounts

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

accounts = cloudcraft.list_azure_accounts()

Update Azure account

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

account_id = "AZURE-ACCOUNT" # valid account uuid for api-key
data = {
    "name": "Updated Azure Account",
    "subscriptionId": "subscriptionId",
    "directoryId": "directoryId",
    "applicationId": "applicationId",
}
result = cloudcraft.update_azure_account(account_id, data)

Delete Azure account

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()

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

Snapshot Azure account

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
cloudcraft = Cloudcraft()
script_dir = os.path.dirname(os.path.realpath(__file__)) + os.sep

ss_account = "AZURE-ACCOUNT" # valid account uuid for api-key
ss_location = "canadaeast"
ss_format = "png"
ss_file = script_dir + ss_location + "." + ss_format
snapshot = cloudcraft.snapshot_azure_account(ss_account, ss_location, ss_format)

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

Budgets

Export budget for a blueprint

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
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

from cloudcraftco.cloudcraft import Cloudcraft

# assumes CLOUDCRAFT_API_KEY exported
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
% poetry install
% export CLOUDCRAFT_API_KEY={{ api-key }}
% python3 dev_playgrounds/blueprints.py
% python3 dev_playgrounds/budgets.py
% python3 dev_playgrounds/exports.py
% python3 dev_playgrounds/snapshots_aws.py
% python3 dev_playgrounds/snapshots_azure.py
% python3 dev_playgrounds/users.py
% export CLOUDCRAFT_TEST_ROLE={{ your-role-arn }}
% python3 dev_playgrounds/accounts_aws.py
% export CLOUDCRAFT_TEST_SUBSCRIPTION={{ your-subscription-id }}
% export CLOUDCRAFT_TEST_DIRECTORY={{ your-directory-id }}
% export CLOUDCRAFT_TEST_APPLICATION={{ your-application-id }}
% export CLOUDCRAFT_TEST_SECRET={{ your-client-secret }}
% python3 dev_playgrounds/accounts_azure.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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cloudcraftco-1.1.0.tar.gz (13.6 kB view details)

Uploaded Source

Built Distribution

cloudcraftco-1.1.0-py3-none-any.whl (12.7 kB view details)

Uploaded Python 3

File details

Details for the file cloudcraftco-1.1.0.tar.gz.

File metadata

  • Download URL: cloudcraftco-1.1.0.tar.gz
  • Upload date:
  • Size: 13.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.1 Darwin/23.4.0

File hashes

Hashes for cloudcraftco-1.1.0.tar.gz
Algorithm Hash digest
SHA256 b6a556bc1ae7b53de9fa7457c145881dcb32704cfd8a0de983807af7912a8a26
MD5 f07c008c4499aaede10cf7b0c7d935a2
BLAKE2b-256 95505052a9f86fb39892294887a87c8778784a6a1991b0ffed479434d9d953c0

See more details on using hashes here.

File details

Details for the file cloudcraftco-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: cloudcraftco-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 12.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.1 Darwin/23.4.0

File hashes

Hashes for cloudcraftco-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a8d1f42b6e07952154d215da729719e9670d23470be5fb4aa274ec14394021b2
MD5 7ee5f3fbefc23f904da71f4abd318f1b
BLAKE2b-256 d5b03e363b77fee3ac4794b70f4ed43a7351464e6556e92c74fdc90ec2580d3d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page