by 
This is part one of a three part series that will demonstrate how the Cloudcraft API can be used to programmatically snapshot your AWS applications and workloads. These Image or JSON snapshots may be embedded in your Confluence page, Wiki, or HTML page ensuring readers of your documentation always have an up-to-date solution architecture diagram.
In this tutorial series, we will use Cloudcraft’s API and the Postman client.
The ability to programmatically create snapshots of your AWS environment can be helpful for:
- Building a documentation process into your CI/CD pipeline
- Onboarding new team members with accurate documentation
- Managing changes in your AWS environment(s)
- Eliminating time consuming manual documentation tasks
- Fulfilling governance and compliance requirements
In the first part of this series, we will provide instructions for setting up Cloudcraft Pro and configuring your Postman environment.
The series consists of:
Part 1: Setting up Cloudcraft and Configuring your Postman Environment
Part 2: Making requests to Cloudcraft API endpoints; Tips for creating filtered Snapshots using tags and embedding your diagram in Confluence
Part 3: Using AWS Lambda to take Snapshots and automatically updating your Cloudcraft Blueprint; always have an up-to-date AWS diagram
Requirements
- An active Cloudcraft Pro account to generate a Cloudcraft API key
- Postman client
- Confluence login
- An AWS account with services deployed
- Ability to create an IAM Role in your AWS account
Part 1: Getting Started
Setting up Cloudcraft and Configuring Your Postman Environment
1. Open Cloudcraft. For optimal performance, Cloudcraft recommends using Chromium based browsers, like Google Chrome.
2. You will need a Cloudcraft Pro license. If you don’t have Cloudcraft Pro yet, check Subscription Settings in the menu or sign up for a 14 day trial of Cloudcraft Pro here.
3. To use the Live scan feature, you will need to add your AWS account to Cloudcraft. Select AWS accounts in the menu.
Note: You will need AdministratorAccess or sufficient privileges to create new IAM roles and attach IAM policies. If you do not have access, a team member will be able to follow steps 4 to 10 and send you the Role ARN.
4. A pop-up will appear outlining 5 steps. Click step 1 “Open the AWS IAM Console to the Create Role page.”
5. Cloudcraft creates URLs which will take you directly to the AWS console with all the required information automatically filled out. You don’t need to add any additional information. Click Next: Permissions
6. Cloudcraft uses the AWS-managed ReadOnlyAccess policy. This policy will be automatically selected and attached to the role. If you would like, you can create a custom IAM policy – click here. Click Next:Tags.
7. You can include your IAM tags, which are key-value pairs added to the role. You can read more about best practice tagging conventions for IAM Users and Roles here – AWS Docs. For my tag I used Key=Cloudcraft and Value=LiveScan. Click Next:Review.
8. Now you can change the role name or keep the default “cloudcraft.” I kept the default. Click Create role.
9. Search for the role you just created by typing in the role name. If you kept the default, search for “cloudcraft.”
10. Copy the Role ARN and navigate back to Cloudcraft in your browser.
11. Paste the Role ARN and give the AWS account a name. I named mine WordPress Environment. Click Save AWS account.
Now you have connected your AWS account and can perform Live scans in Cloudcraft! The next section will walk through configuring Postman.
12. In Cloudcraft, click “API Keys” in the top right menu to generate an API Key.
Tip – Be sure to copy the API key as it only appears once.
13. Open https://developers.cloudcraft.co and click Run in Postman.
To use the Postman client on your system you will need to create a Postman account. The local install of the Postman client will walk you through this process, or you can login to an account if you’ve previously created one. Download the latest version of Postman for your operating system: https://www.postman.com/downloads/
Extract the archive, or follow the installation instructions. You may need to allow Postman to run in your systems security settings, or ask your System Administrator to allow you to access the application on your workstation.
14. Once you’ve downloaded Postman, navigate to the eye-view to create an Environment. Learn more about Postman environments here.
15. From your clipboard, paste the API key that was generate by Cloudcraft. After naming your environment, click “Update.”
Congratulations! You have configured both your Cloudcraft and Postman environments. We are ready to start using the provided API endpoints.
Now, let’s use Postman to get an image of the AWS environment.
16. First, we will need to do a GET to list your AWS account(s). Select the “List my AWS accounts” endpoint (https://api.cloudcraft.co/aws/account) and click send.
The output is an array of AWS accounts that have been added in Cloudcraft. Each entry provides the account ID and name given to it in Cloudcraft, access control and user information. The account IDs are what we need for the next steps. Copy the account ID to your clipboard.
Note – If you would like to add additional AWS accounts to Cloudcraft, you can repeat steps 3 to 11.
17. The next endpoint we will use is a GET to take a “snapshot AWS account” (https://api.cloudcraft.co/aws/account/ACCOUNT_ID/REGION/FORMAT). This endpoint allows us to scan a particular region in an AWS account in JSON, SVG, PNG, PDF or MxGraph.
You will need to fill out the following Path Parameters:
Account ID = Paste the ID you copied from from the List my AWS account endpoint
Region = Select the AWS region you want to a snapshot of (i.e. us-west-2)
Format = json. Make sure that the ‘json’ format is in lowercase
You can also add an optional extension to your endpoint in the format of key=value. Some of these extension include:
- filter: String. Render a subset of the AWS account. If you want your snapshot using a specific AWS tag, you an apply an extension to the endpoint.
For example, “application=webserver” - exclude: List of Strings. Exclude one or multiple AWS services by name.
For example, “exclude=ec2,sg” will exclude both EC2s and Security Groups. - autoconnect: Bool. Automatically connect all components. Defaults to true.
There are also some additional query parameters you can use, however, these are for SVG, PNG and/or PDF specifically:
- scale: Float. Scale relative to original size (1.0).
For example “scale=0.5” (for half) or “scale=2.0” (for double size) - width: Number. Image width in pixels.
For example, “width=1280” - height: Number. Image height in pixels
For example, “height=720” - projection: String. The visual topography of the diagram.
For example, “projection=isometric” or “projection=2d” - grid: Boolean. Enable or disable grid rendering. Defaults is to disable grid.
- transparent: Boolean. Enable or disable transparent background rendering.
- landscape: Boolean. Enable or disable landscape paper format. For PDF format only.
- paperSize: String. For PDF format only.
For example, One of “Letter”, “Legal”, “Tabloid”, “Ledger”, “A0”, “A1”, “A2”, “A3”, “A4”, “A5”.
For my endpoint, I added a filter and scale parameter:
https://api.cloudcraft.co/account/xxxx/us-west-2/json?filter=environment=projectA&scale=0.5
Now you have used the Snapshot AWS account endpoint! Part 2 of the series will explain how to make request to the Snapshot API endpoint in JSON and how to embed your diagram into Confluence.
Stay tuned for Part 2!
Leave a Reply