AWS Perspective

AWS Perspective is a tool that quickly visualizes AWS Cloud workloads as architecture diagrams. You can use the solution to build, customize, and share detailed workload visualizations based on live data from AWS. This solution works by maintaining an inventory of the AWS resources across your accounts and Regions, mapping relationships between them, and displaying them in a web user interface (web UI).

To find out more about AWS Perspective visit the AWS Perspective Solution Page.

Features

Build architecture diagrams

AWS Perspective lets you build, customize, and share detailed architecture diagrams. Perspective maintains an inventory of the AWS resources across your accounts and Regions, mapping relationships between them and displaying them in a web user interface (UI).

Search across Accounts and Regions

The search feature lets you use basic information e.g. resource name, Tag name, or IP address to locate the resources you are interested in.

Explore your AWS Resources

Explore resources provisioned across your accounts and Regions using the resource directory. It contains all the resources Perspective has discovered. You can start building your architecture diagrams with a single click of a resource.

Save & export architecture diagrams

You can save your architecture diagram to revisit later or share it with other Perspective users. If you need to use the diagrams outside of Perspective you can export to PNG, JSON, CSV, or DrawIO.

To find out more about AWS Perspective visit our AWS Solutions page.

Launch AWS Perspective

Installation

AWS Perspective is deployed to your account using an AWS CloudFormation template and should take approximately 30 minutes to deploy. See the deployment guide for instructions, and the cost overview to learn about costs.

Usage

A web interface is included with AWS Perspective. To login to the interface, follow the Post-deployment configuration steps of the installation guide.

Refer to the implementation guide to learn how to use AWS Perspective.

Feature requests

To submit an idea for a feature you would like to see implemented, please create an issue and use the 'enhancement' label. Your issue will be available on the project board for others to vote on.

Architecture

AWS Perspective is deployed to your account using an AWS CloudFormation template consisting of six components. Following is a high level overview of the components. For additional details about each component, refer to the Solution components guide.

The web user interface (UI) interacts with the data component via Amazon API Gateway and AWS AppSync endpoints. The web UI requests resource relationship data from the data component. The data component queries and returns data from an Amazon Neptune database.

The storage management component stores user preferences and saved architecture diagrams. This is implemented using AWS Amplify and an Amazon Simple Storage Service (Amazon S3) bucket.

The discovery component uses AWS Config and AWS API calls to maintain an inventory of resource data from imported accounts and Regions, then stores its findings in the data componenet. This runs every 15 minutes as a container task on AWS Fargate. The discovery component container image is built in the image deployment component using AWS CodePipeline and AWS CodeBuild.

The cost component processes AWS Cost and Usage Reports (AWS CUR) to make cost data available in AWS Perspective. To use this feature, you must create a report in AWS CUR to deliver the reports to the PerspectiveCostBucket Amazon S3 bucket. When an AWS CUR is delivered, it triggers an AWS Lambda function to process the cost data and store it in an Amazon DynamoDB table. The data component queries this DynamoDB table to provide the costs associated with the individual resources for display in the web UI. If you do not create an AWS CUR, cost data will not be included in AWS Perspective architecture diagrams.

Development

Directory structure

|-deployment/
  |-build-s3-dist.sh             [ shell script for packaging distribution assets ]
  |-run-unit-tests.sh            [ shell script for executing unit tests ]
  |-perspective-setup.yaml       [ the main CloudFormation deployment template ]
|-source/
  |-frontend/                    [ the frontend ui code ]
  |-backend/                     [ the backend code ]
    |-discovery/                 [ the code for the discovery process ]
    |-functions/                 [ the code for the Lambda functions ]
  |-cfn/                         [ the CloudFormation templates that deploy aws-perspective ]

Running the Perspective Web Application locally

For development and debugging, it's possible to run the Perspective UI locally. The Perspective solution must already be deployed to an account.

The Perspective solution generates a settings.js file used by the web browser for configuration. To develop locally, this settings.js file must be present.

• Copy the settings.js file from the S3 Bucket containing the Perspective UI. This has the logical name WebUIBucket in the CloudFormation stack.
• Place the settings.js file in source/frontend/public.
• From the source/frontend directory, run npm install
• Run npm run start to run the local development server.

Running unit tests

cd ./deployment
./run-unit-tests.sh

Running a local build

cd ./deployment
./build-s3-dist.sh

Deployment

When you have made changes to the code, you can build it locally and upload the deployment artefacts to Amazon S3 by running the following bash script.

Prerequistes

1. AWS CLI installed.
2. The CLI configured with credentials/profile that will allow:
   • S3 Bucket creation
   • S3 Object creation

Create deployment script

1. Create a shell script in the root project directory. touch local-deploy-script.sh
2. Copy the contents below and paste in local-deploy-script.sh. Substitute the value placeholders (marked with angle brackets) with your own values, then save the script.

#!/usr/bin/env bash

set -e

# The Region you wish to deploy to.
AWS_REGION=<aws-region>
# The S3 Bucket name to be created to store your deployment artefacts
DIST_OUTPUT_BUCKET=<s3-bucket>
# A name for your test solution
SOLUTION_NAME=<solution-name>
# A version number for this test release e.g vX.Y.Z
VERSION=<version>
# Tag that will be given to Docker image.
IMAGE_TAG=<tag>

if aws s3api head-bucket --bucket "${DIST_OUTPUT_BUCKET}" 2>/dev/null;
then
    echo "${DIST_OUTPUT_BUCKET} bucket exists and you own it, so not creating it"
else
    echo "creating bucket in region ${AWS_REGION} with name ${DIST_OUTPUT_BUCKET}"
    aws s3 mb s3://${DIST_OUTPUT_BUCKET} --region ${AWS_REGION}
fi

if aws s3api head-bucket --bucket "${DIST_OUTPUT_BUCKET}-${AWS_REGION}" 2>/dev/null;
then
    echo "${DIST_OUTPUT_BUCKET}-${AWS_REGION} bucket exists and you own it, so not creating it"
else
    echo "creating bucket in region ${AWS_REGION} with name ${DIST_OUTPUT_BUCKET}-${AWS_REGION}"
    aws s3 mb s3://${DIST_OUTPUT_BUCKET}-${AWS_REGION} --region ${AWS_REGION}
fi

cd deployment
./build-s3-dist.sh $DIST_OUTPUT_BUCKET $SOLUTION_NAME $VERSION $IMAGE_TAG
aws cloudformation package --template-file "global-s3-assets/perspective-setup.template" --s3-bucket "$DIST_OUTPUT_BUCKET" --s3-prefix "${SOLUTION_NAME}/${VERSION}" --output-template-file packaged.template
aws s3 cp packaged.template "s3://${DIST_OUTPUT_BUCKET}/${SOLUTION_NAME}/${VERSION}/aws-perspective.template"
aws s3 cp global-s3-assets  s3://${DIST_OUTPUT_BUCKET}-${AWS_REGION}/${SOLUTION_NAME}/${VERSION}/ --recursive --acl bucket-owner-full-control
aws s3 cp regional-s3-assets  s3://${DIST_OUTPUT_BUCKET}-${AWS_REGION}/${SOLUTION_NAME}/${VERSION}/ --recursive --acl bucket-owner-full-control

echo "You can now deploy using this template URL https://${DIST_OUTPUT_BUCKET}.s3.${AWS_REGION}.amazonaws.com/${SOLUTION_NAME}/${VERSION}/aws-perspective.template"

3. Make the script executable chmod +x ./local-deploy-script.sh
4. Run the script ./local-deploy-script.sh

This will:

• Create S3 buckets to store the deployment artefacts.
• Run the build
• Deploy artefacts to your chosen S3 Bucket.

Deploying the CloudFormation template

Once you have the deployment artefacts in S3, you can deploy the aws-perspective.template in the CloudFormation console. Just pass the link to the template in S3 to CloudFormation and it will do the rest.

Parameters required by the template:

• Stack Name - The name given to the deployment stack e.g. aws-perspective
• AdminUserEmailAddress - The email address to receive login credentials at.
• AlreadyHaveConfigSetup - Yes/No depending on whether AWS Config has is configured in the deployment Region.
• CreateElasticsearchServiceRole - Yes/No depending on whether you already have this service-role created. You can check in the IAM console to see if it is provisioned.
• OptOutOfSendingAnonymousUsageMetrics - Yes/No depending on whether you are happy to send anonymous usage metrics back to AWS.
• CreateNeptuneReplica - Yes/No depending on whether you want a read-replica created for Amazon Neptune. Note, that this will increase the cost of running the solution.
• NeptuneInstanceClass - Select from a range of instance types that will be provisioned for the Amazon Neptune database. Note, the selection could increase the cost associated with running the solution.

Note - You will need to deploy in the same account and region as the S3 bucket.

Web API Examples

Getting a Bearer Token

Via Browser

The Web API requires a JWT present in the request Authorization Header. You can find your Bearer Token by:

1. Logging into AWS Perspective UI in Google Chrome
2. Right-click anywhere on the screen.
3. Click Inspect
4. Click Network
5. Find the resources request.
6. Select it and go to Headers
7. Locate the Authorization Header
8. Copy the contents.

Commands

getAllResources

Request

curl --location --request POST 'https://<your-api-gateway-id>.execute-api.<deployment-region>.amazonaws.com/Prod/resources' \
--header 'Authorization: Bearer <your-token>' \
--header 'Content-Type: application/json' \
--data-raw '{"command":"getAllResources","data":{}}'

Response

You will receive all the resources that have been discovered with just a subset of data about each one. You will also receive a metadata object that breaks down the resource types discovered and the resource counts for each. This is done for each account and region that is discoverable to AWS Perspective.

linkedNodesHierarchy

Request

curl --location --request GET 'https://<your-api-gateway-id>.execute-api.<deployment-region>.amazonaws.com/Prod/resources?command=linkedNodesHierarchy&id=<node-id>' \
--header 'Authorization: Bearer <your-token>'

Response

You will receive an array of nodes that have a relationship with the node id used in the request.

DrawIO Export

This takes a JSON representation of the architecture diagram and converts it to mxGraph and opens in a DrawIO tab.

Request

curl --location --request POST 'https://<your-api-gateway-id>.execute-api.<deployment-region>.amazonaws.com/Prod/resources' \
--header 'Authorization: Bearer <your-token> \
--header 'Content-Type: text/plain' \
--data-raw '{"elements":{"nodes":[], "edges": []'}}

Response

You will receive a URL that when clicked will open up DrawIO in the browser and show your graph.

Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://www.apache.org/licenses/ or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions and limitations under the License.