AWS Perspective Implementation Guide AWS Perspective Implementation Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon. AWS Perspective Implementation Guide

Table of Contents

Welcome ...... 1 Cost ...... 3 Architecture overview ...... 4 Solution components ...... 6 Authentication mechanism ...... 6 Web UI and storage management ...... 6 Data component ...... 7 Image deployment component ...... 8 Discovery component ...... 8 Cost component ...... 9 Supported resources ...... 10 AWS Perspective architecture diagram management ...... 10 Security ...... 11 Resource access ...... 11 IAM roles ...... 11 Amazon Cognito ...... 11 Network access ...... 11 Amazon Virtual Private Cloud (Amazon VPC) ...... 11 Amazon CloudFront ...... 12 Application conﬁguration ...... 12 Amazon API Gateway ...... 12 AWS AppSync ...... 12 AWS Lambda ...... 12 Amazon OpenSearch Service (OpenSearch Service) ...... 12 Design considerations ...... 13 Create dedicated deployment account ...... 13 AWS CloudFormation template ...... 14 Automated deployment ...... 15 Prerequisites ...... 15 Gather deployment parameter details ...... 15 Deployment overview ...... 16 Step 1. Launch the stack ...... 17 Step 2. Post-deployment conﬁguration tasks ...... 19 Turn on Advanced security in Amazon Cognito ...... 19 Create Amazon Cognito users ...... 19 Log in to AWS Perspective ...... 20 Step 3. Import a Region ...... 21 AWS CloudFormation StackSets ...... 21 AWS CloudFormation ...... 22 Deploy the stack to provision the Global resources ...... 24 Deploy the stack to provision the Regional resources ...... 24 Use CloudFormation StackSets to provision Global resources across accounts ...... 25 Use CloudFormation StackSets to provision Regional resources ...... 26 Verify the Region was imported correctly ...... 27 Step 4. Set up the cost feature ...... 27 Create the AWS Cost and Usage Report in the AWS Perspective deployment account ...... 28 Create the AWS Cost and Usage Report in an external account ...... 28 Set up replication ...... 29 Step 5. Edit S3 bucket lifecycle policies ...... 30 Web UI features and common tasks ...... 31 Side navigation pane ...... 31 AWS Perspective architecture diagrams ...... 32 Build an AWS Perspective architecture diagram ...... 32 Costs & Usage ...... 36

iii AWS Perspective Implementation Guide

View costs by resource ...... 36 View costs by service ...... 37 View costs by ARN ...... 37 Generate a Cost Report ...... 38 Export AWS Perspective architecture diagrams ...... 38 Export an AWS Perspective architecture diagram as CSV ...... 38 Export an AWS Perspective architecture diagram as PNG ...... 38 Export an AWS Perspective architecture diagram as JSON ...... 39 Export an AWS Perspective architecture diagram to draw.io ...... 39 Saving, downloading, and ﬁltering ...... 39 Save an AWS Perspective architecture diagram ...... 39 Download an AWS Perspective architecture diagram ...... 39 Filtering in AWS Perspective ...... 39 Additional resources ...... 42 Update the stack ...... 43 Using the AWS Management Console ...... 43 Using AWS Command Line Interface ...... 44 Resources removed with stack update ...... 45 Locating deployment resources ...... 47 Supported resources ...... 48 Supported deployment Regions ...... 50 IAM roles ...... 11 Using StackSets in an AWS Organization ...... 53 Debugging the discovery component ...... 54 S3 replication role actions ...... 55 S3 bucket policy ...... 56 Discovery process is slow ...... 57 Uninstall the solution ...... 58 Using the AWS Management Console ...... 58 Using AWS Command Line Interface ...... 58 Collection of operational metrics ...... 59 Source code ...... 60 Contributors ...... 61 Revisions ...... 62 Notices ...... 63

iv AWS Perspective Implementation Guide

Deploy a visualization tool that automatically generates architecture diagrams of AWS Cloud workloads

Publication date: September 2020 (last update (p. 62): August 2021)

Monitoring your Amazon Web Services (AWS) Cloud workloads is key to maintaining operational health and eﬃciency. However, keeping track of the AWS resources and the relationships between them can be a challenge. AWS Perspective is a visualization tool that automatically generates architecture diagrams of AWS Cloud workloads. 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). When making changes to a resource, AWS Perspective saves you time by providing a link to the resource in the AWS Management Console.

Figure 1: Sample architecture diagram generated by AWS Perspective

1 AWS Perspective Implementation Guide

Figure 2: Sample grouped architecture diagram generated by AWS Perspective

This implementation guide describes architectural considerations and conﬁguration steps for deploying AWS Perspective in the AWS Cloud. It includes links to an AWS CloudFormation template that launches and conﬁgures the AWS services required to deploy this solution using AWS best practices for security and availability.

The guide is intended for end users who have practical experience with the AWS Cloud.

2 AWS Perspective Implementation Guide

Cost

You are responsible for the cost of the AWS services provisioned while running this solution. As of July 2021, the estimated cost of running AWS Perspective in US East (N. Virginia) is approximately $0.58/hr or $425.19/mth. The following table lists the primary AWS services and the costs are incurred. These services are billed on a monthly basis.

AWS service Instance type Hourly cost Monthly cost

Amazon Neptune db.r5.large $0.348 $254.04

Amazon OpenSearch m6g.large.elasticsearch$0.128 $93.44 Service

Amazon VPC (NAT N/A $0.090 $65.7 Gateway)

AWS Conﬁg N/A $0.003 per Resource $0.003 per Resource

Amazon ECS (AWS N/A $0.02 $12.01 Fargate Task)

Total: $0.586* $425.19*

*Your final cost depends on the number of resources AWS Config detects. $0.003 per resource item recorded will be incurred in addition to the amount provided in the table. Important This pricing estimate is based on the Amazon Neptune read-replica option being turned off (the CreateNeptuneReplica parameter is set to No) with the instance type set to db.r5.large. The cost for Amazon Neptune varies, depending on the instance type you select.

We recommend creating a budget through AWS Cost Explorer to help manage costs. Prices are subject to change. For full details, refer to the pricing webpage for each AWS service you will be using in this solution.

3 AWS Perspective Implementation Guide

Architecture overview

Deploying this solution with the default parameters builds the following environment in the AWS Cloud.

Figure 3: AWS Perspective architecture on AWS

The AWS CloudFormation template deploys AWS Perspective to your account. The following overview describes the six components and their associated AWS services deployed with the solution. For additional details about each component, refer to the Solution components (p. 6) section.

1. AWS Lambda@Edge functions provide security for each request to the Amazon CloudFront distribution. 2. An Amazon Simple Storage Service (Amazon S3) bucket hosts the web user interface (web UI), which is distributed via Amazon CloudFront. Amazon Cognito authenticates user access to the web UI. 3. AWS Amplify and an Amazon S3 bucket are deployed for the storage management component to store user preferences and saved architecture diagrams. 4. Amazon API Gateway endpoints allow the web UI component to request resource relationship data from the data component. AWS AppSync endpoints allow the web UI component to request resource relationship data, import new AWS Regions, and update preferences. 5. API Gateway and AWS AppSync use JSON Web Tokens (JWTs) provisioned by Amazon Cognito to authenticate each request. 6. The Settings AWS Lambda function persists imported Regions and other conﬁgurations to Amazon DynamoDB. 7. The data component uses the Gremlin Lambda function to query and return data from an Amazon Neptune database. 8. The data component uses the Search Lambda function to query and persist resource data into an Amazon OpenSearch Service (OpenSearch Service) domain. 9. The Cost Lambda function uses Amazon Athena to query AWS Cost and Usage Reports (AWS CUR) to provide estimated cost data to the web UI.

4 AWS Perspective Implementation Guide

10.Amazon Athena runs queries on AWS CUR. 11.AWS CUR delivers the reports to the CostAndUsageReportBucket Amazon S3 bucket. 12.The Cost Lambda function stores the Amazon Athena results in the AthenaResultsBucket Amazon S3 bucket. 13.AWS CodePipeline and AWS CodeBuild build the discovery component container image in the image deployment component. 14.Amazon Elastic Container Registry (Amazon ECR) contains a Docker image provided by the image deployment component. 15.Amazon Elastic Container Service (Amazon ECS) manages the AWS Fargate task and provides the configuration required to run the task. AWS Fargate runs a container task every 15 minutes to refresh inventory and resource data. 16.AWS Config and AWS SDK calls help the discovery component maintain an inventory of resource data from imported Regions, then store its results in the data component. 17.The AWS Fargate task persists the results of the AWS Config and AWS SDK calls into an Amazon Neptune database and an Amazon OpenSearch Service domain via API calls to the ServiceGremlinAPI API Gateway resource. The API is invoked by the Search Lambda function.

5 AWS Perspective Implementation Guide Authentication mechanism

Solution components

Authentication mechanism

AWS Perspective uses an Amazon Cognito User Pool for both the web user interface (UI) and Amazon API Gateway authentication. Once authenticated, Amazon Cognito provides a JSON Web Token (JWT) to the web UI that will be provided with all subsequent API requests. If a valid JWT is not provided, the API request will fail and return a HTTP 403 Forbidden response.

Web UI and storage management

The web UI was developed using React and provides a front-end console to allow users to interact with AWS Perspective.

Lambda@Edge appends secure headers to every HTTP request to the web UI. This provides an additional layer of security, protecting against attacks such as Cross-site scripting (XSS).

Figure 4: AWS Perspective web UI and storage management components

The web UI resources are hosted in the WebUIBucket Amazon Simple Storage Service (Amazon S3) bucket and distributed by Amazon CloudFront. AWS Amplify provides an abstraction layer to simplify the integrations to API Gateway, AWS AppSync, and Amazon S3. Amazon Cognito authenticates users

6 AWS Perspective Implementation Guide Data component

at the login stage. On successful login, a JSON Web Token (JWT) is provided in the authentication response from Amazon Cognito. The JWT must be sent with all subsequent API requests. If the JWT is not provided, then the API request will fail and return a HTTP 403 Forbidden response.

AWS AppSync is used to facilitate interaction with various conﬁgurations available to AWS Perspective, including managing imported Regions. AWS AppSync integrates with Amazon DynamoDB for create, read, update, and delete (CRUD) operations, but utilizes the Settings AWS Lambda function to handle more complex requests, such as importing a new Region, which require an API call to AWS Conﬁg to authorize the new Region.

AWS AppSync endpoints are also used to allow the web UI to retrieve resource relationship data from the data component using an Amazon Resource Name (ARN) and querying estimated resource cost data from AWS CURs in the cost component.

Amazon API Gateway builds the PerspectiveWebRestAPI endpoint and provides access to the relationship data that AWS Perspective collects. This API endpoint is called when you build out your architecture diagram.

Refer to Web UI features and common tasks (p. 31) for an overview of UI features and common tasks.

Data component

Figure 5: AWS Perspective data component

7 AWS Perspective Implementation Guide Image deployment component

The web UI sends requests to the PerspectiveWebRestAPI and AWSPerspectiveAppSyncAPI API Gateway endpoints serving requests to the Gremlin AWS Lambda functions. The Lambda functions process the requests and query Amazon Neptune to retrieve data about the provided resources. AWS AppSync supports requests for resource data using an ID or Amazon Resource Name (ARN) and retrieves the estimated cost data from the AWS CURs.

The discovery component (p. 1) sends requests to the PerspectiveWebRestAPI API Gateway endpoint when it requires the latest data about the resources already discovered. This is to ensure that the discovery component aligns with the current state of the Neptune relationship graph.

The ServerGremlinAPI API Gateway endpoint receives requests from the AWS Fargate task in the discovery component and is authenticated using an Identity and Access Management (IAM) role that provides access to the Amazon OpenSearch Service (OpenSearch Service) cluster. The API Gateway endpoint is backed by the Search Lambda function that processes incoming requests and communicates with the OpenSearch Service cluster. The OpenSearch Service cluster provides an index of the relationship data discovered by AWS Perspective.

Image deployment component

Figure 6: AWS Perspective image deployment component

The image deployment component builds the container image that is used by the discovery component. The code is hosted in the DiscoveryBucket Amazon S3 bucket and downloaded at deployment time by AWS CodePipeline. CodePipeline initiates an AWS CodeBuild job that builds the container image and uploads it to Amazon Elastic Container Registry (Amazon ECR).

Discovery component

The discovery component is the main data-gathering element of the AWS Perspective architecture. It is responsible for querying AWS Conﬁg and making describe (p. 42) API calls to maintain the inventory of resources and their relationships between one another.

8 AWS Perspective Implementation Guide Cost component

Figure 7: AWS Perspective discovery component

This solution conﬁgures Amazon ECS to run an AWS Fargate task using the container image downloaded from Amazon ECR. The AWS Fargate task is scheduled to run at 15-minute intervals. The resource relationship data that is collected is inserted into an Amazon Neptune graph database and OpenSearch Service.

The discovery component workﬂow consists of three steps:

1. Amazon ECS invokes an AWS Fargate task at 15 minutes intervals. 2. The Fargate task gathers resource data from AWS Conﬁg and AWS API describe calls. 3. The Fargate task runs HTTP POST requests to the ServerGremlinAPI API Gateway endpoint to aggregate resource relationship data and persist it into Amazon Neptune and OpenSearch Service.

Cost component

Figure 8: AWS Perspective cost component

You can create an AWS CUR in AWS Billing and Cost Management and Cost Management. This publishes a Parquet formatted ﬁle to the CostAndUsageReportBucket S3 bucket. The web UI makes requests to the AWS AppSync endpoint that invokes the Cost Lambda function. The function sends predeﬁned queries to Amazon Athena that return estimated cost information from AWS CURs.

Due to the size of the AWS CURs, the responses from Amazon Athena can be very large. The solution stores the results in the AthenaResultsBucket Amazon S3 bucket and paginates the results back to the web UI. The lifecycle policy conﬁgured on this bucket removes items that are more than seven days old.

9 AWS Perspective Implementation Guide Supported resources

Supported resources

For a list of AWS resource types that Perspective can discover within your accounts and Regions, refer to Supported resources (p. 10).

AWS Perspective architecture diagram management

AWS Perspective architecture diagrams can be saved using the web UI where create, read, update, and delete (CRUD) operations can be performed. The AWS Amplify storage API allows Perspective to store architecture diagrams in an Amazon S3 bucket. There are two levels of permissions available:

• All users - Allows AWS Perspective architecture diagrams to be visible to AWS Perspective users in your deployment. Users can download and edit these diagrams. • You - Allows AWS Perspective architecture diagrams to be visible only to the creator. Other users will not view them.

10 AWS Perspective Implementation Guide Resource access

Security

When you build systems on AWS infrastructure, security responsibilities are shared between you and AWS. This shared model reduces your operational burden because AWS operates, manages, and controls the components including the host operating system, the virtualization layer, and the physical security of the facilities in which the services operate. For more information about AWS security, visit the AWS Security Center.

AWS Perspective has been architected and conﬁgured to be secure. These include the following best practices for AWS Perspective and its component parts:

• Access is conﬁgured to grant least privilege and scoped down to only required resources where possible. • Data at rest and transit is encrypted using keys stored in AWS Key Management Service (AWS KMS)—a dedicated key management store. • When credentials are used, they are short-lived and implement a strong password policy. • Logging, tracing, and versioning is turned on where applicable. • Automatic patching (minor-version) and snapshot creation is turned on where applicable. • Network access is private by default with Amazon Virtual Private Cloud (Amazon VPC) endpoints being turned on where available.

Resource access IAM roles

AWS Identity and Access Management (IAM) roles allow customers to assign granular access policies and permissions to services and users on the AWS Cloud. Multiple roles are required to run AWS Perspective and discover resources in AWS accounts. Refer to IAM roles (p. 1) for details. Amazon Cognito

Amazon Cognito is used to authenticate access with short-lived strong credentials granting access to components needed by AWS Perspective.

Network access Amazon Virtual Private Cloud (Amazon VPC)

AWS Perspective is deployed within an Amazon VPC and conﬁgured according to best practices to deliver security and high availability. For additional details, refer to Security best practices for your VPC. VPC endpoints allow non-internet transit between services and are conﬁgured where available.

Security groups are used to control and isolate network traﬃc between the components needed to run AWS Perspective.

We recommend that you review the security groups and further restrict access as needed once the deployment is up and running.

11 AWS Perspective Implementation Guide Amazon CloudFront

Amazon CloudFront

This solution deploys a web console hosted in an Amazon Simple Storage Service (Amazon S3) bucket which is distributed by Amazon CloudFront. The contents of this Amazon S3 bucket are accessible only via CloudFront. This is activated using the Origin Access Identity feature. For more information, refer to Restricting Access to Amazon S3 Content by Using an Origin Access Identity in the Amazon CloudFront Developer Guide.

Additional Security mitigations are activated with Lambda@Edge appending HTTP security headers to each origin request. For additional details, refer to Adding HTTP Security Headers Using Lambda@Edge and Amazon CloudFront. This solution uses the default CloudFront certificate which supports TLS v1.0 only. To use TLS v1.1 or TLS v1.2, you must use a custom SSL certificate instead of the default CloudFront certificate. For more information, refer to How do I configure my CloudFront distribution to use an SSL/TLS certificate.

Application conﬁguration Amazon API Gateway

AWS Perspective APIs have basic request validation activated with deeper input validation implemented within integrations, including AWS Lambda. Furthermore, authentication and authorization are implemented using IAM and Cognito, which use the JSON Web Token (JWT) provided by Cognito when a user authenticates successfully in the web UI. AWS AppSync

AWS Perspective GraphQL APIs have request validation provided by AWS AppSync as per the GraphQL speciﬁcation. Furthermore, authentication and authorization are implemented using IAM and Cognito, which use the JSON Web Token (JWT) provided by Cognito when a user authenticates successfully in the web UI. AWS Lambda

By default, the Lambda functions are conﬁgured with the most recent stable version of the language runtime. No sensitive data or secrets are logged. Service interactions are carried out with the least required privilege. Roles that deﬁne these privileges are not shared between functions. Furthermore, sensitive environment variables are stored as secure parameters in a dedicated vault. Amazon OpenSearch Service (OpenSearch Service)

OpenSearch Service domains are conﬁgured with an access policy that restricts access in order to stop any unsigned requests made to the OpenSearch Service cluster This is restricted to a single Lambda function.

The OpenSearch Service cluster is built with node-to-node encryption activated to add an extra layer of data protection on top of the existing OpenSearch Service security features.

12 AWS Perspective Implementation Guide Create dedicated deployment account

Design considerations

Create dedicated deployment account

We recommend that you deploy AWS Perspective into a dedicated AWS account created speciﬁcally for this solution. This approach means AWS Perspective is isolated from your existing workloads and provides a single location for conﬁguring the solution, such as adding users and importing new Regions. It is also easier to track the costs incurred while running the solution.

Once AWS Perspective is deployed, you can then import Regions from any accounts you already have provisioned.

13 AWS Perspective Implementation Guide

AWS CloudFormation template

This solution uses AWS CloudFormation to automate the deployment of AWS Perspective in the AWS Cloud. It includes the following CloudFormation template, which you can download before deployment:

aws-perspective.template: Use this template to launch the solution and all associated components. The default configuration deploys Amazon CloudFront, Amazon Simple Storage Service (Amazon S3), AWS Lambda, Amazon Cognito, Amazon Athena, AWS Amplify, Amazon API Gateway, AWS AppSync, Amazon Neptune, Amazon OpenSearch Service (OpenSearch Service), Amazon Elastic Container Service (Amazon ECS), AWS Fargate, AWS Config, Amazon Elastic Container Registry (Amazon ECR), Amazon DynamoDB, AWS CodePipeline, and AWS CodeBuild. Note You can customize the template to meet your specific needs; however, any changes you make could affect the upgrade (p. 58) process.

14 AWS Perspective Implementation Guide Prerequisites

Automated deployment Note If you have previously deployed AWS Perspective and would like to upgrade to the latest version, refer to Update the stack (p. 43).

Before you launch the solution, review the architecture, conﬁguration, network security, and other considerations discussed in this guide. Follow the step-by-step instructions in this section to conﬁgure and deploy the solution into your account.

Time to deploy: Approximately 30 minutes Prerequisites Gather deployment parameter details

Before deploying AWS Perspective, review your conﬁguration details for the Amazon OpenSearch Service (OpenSearch Service) service-linked role and AWS Conﬁg. Verify whether you have an AWSServiceRoleForAmazonElasticsearchService role

The deployment creates an OpenSearch Service cluster inside an Amazon Virtual Private Cloud (Amazon VPC). The template uses a service-linked role to create the OpenSearch Service cluster; however, if you already have the role created in your account, use the existing role.

To check if you already have this role:

1. Sign in to the Identity and Access Management (IAM) console for the account you plan to deploy this solution to. 2. In the Search box below the menu, search for AWSServiceRoleForAmazonElasticsearchService.

If your search returns a role, select No for the CreateElasticsearchServiceRole parameter when you launch the stack. Verify AWS Conﬁg is set up

AWS Perspective uses AWS Config to gather the majority of resource configurations. When deploying the solution or importing a new Region, you must confirm whether AWS Config is already set up and working as expected. The AlreadyHaveConfigSetup CloudFormation parameter informs AWS Perspective of whether to set up AWS Config.

The following snippet is taken from the AWS CLI Command Reference. Run the command in the Region you intend to deploy AWS Perspective or import into AWS Perspective.

aws configservice get-status

Output:

Configuration Recorders:

name: default

15 AWS Perspective Implementation Guide Deployment overview

recorder: ON last status: SUCCESS

Delivery Channels:

name: default last stream delivery status: SUCCESS last history delivery status: SUCCESS last snapshot delivery status: SUCCESS

If you receive a response similar to the output above, then there is a Conﬁguration Recorder and Delivery Channel running in that Region. Select Yes for the AlreadyHaveConﬁgSetup CloudFormation parameter.

If you are configuring AWS CloudFormation StackSets, then you must include this Region in the batch of Regions that already have AWS Config configured. Verify your AWS Config details in your account

The deployment will attempt to set up AWS Config. If you already use AWS Config in the account you plan to deploy to, or make discoverable by AWS Perspective, select the relevant parameters when you deploy this solution. Furthermore, for successful deployment, ensure that you have not restricted the resources that AWS Config scans.

To check your current AWS Conﬁg conﬁguration:

1. Sign in to the AWS Conﬁg console. 2. Choose Settings and ensure the Record all resources supported in this Region and Include global resources boxes are checked.

Verify whether you have an APIGatewayCloudWatchLogsRole role

The CreateAPIGatewayCloudWatchLogsRole CloudFormation template parameter allows you to control whether AWS Perspective creates the necessary role to let APIGateway log to CloudWatch. This process includes overwriting any existing role that you might have already created.

To check if a value is set, use:

aws apigateway get-account

For additional details, refer to the get-account command in the AWS CLI Command Reference. If you already have the role set up, then select No. The role created by AWS Perspective will be retained upon deletion of the solution’s stack to prevent the interruption of logging for other API Gateways in a Region.

Deployment overview

Use the following steps to deploy this solution on AWS. For detailed instructions, follow the links for each step.

Step 1. Launch the stack (p. 17)

• Launch the AWS CloudFormation template into your AWS account. • Review the other template parameters and enter or adjust the default values as needed.

16 AWS Perspective Implementation Guide Step 1. Launch the stack

Step 2. Post-Deployment tasks (p. 19)

• Turn on Advanced security in Amazon Cognito (Optional) • Create Amazon Cognito users • Log in

Step 3. Import a Region (p. 21)

• Deploy the stack to provision the Global resources • Deploy the stack to provision the Regional resources • Use CloudFormation StackSets to provision Global resources across accounts • Use CloudFormation StackSets to provision Regional resources • Verify the Region was imported correctly

Step 4. Set up the cost feature (p. 27)

Step 5. Edit S3 bucket lifecycle policies (p. 30)

Step 1. Launch the stack

This automated AWS CloudFormation template deploys AWS Perspective in the AWS Cloud. You must gather deployment parameter details before launching the stack. For details, refer to Prerequisites (p. 15). Note You are responsible for the cost of the AWS services used while running this solution. For more details, visit to the Cost (p. 3) section in this guide, and refer to the pricing webpage for each AWS service used in this solution.

1. Sign in to the AWS Management Console and select the button to launch the aws- perspective.template AWS CloudFormation template.

Alternatively, you can download the template as a starting point for your own implementation. 2. The template launches in the US East (N. Virginia) Region by default. To launch the solution in a diﬀerent AWS Region, use the Region selector in the console navigation bar. Note This solution uses services that are not available in all AWS Regions. Refer to Supported deployment Regions (p. 50) for a list of supported AWS Regions. 3. On the Create stack page, verify that the correct template URL is in the Amazon S3 URL text box and choose Next. 4. On the Specify stack details page, assign a name to your solution stack. For information about naming character limitations, refer to IAM and STS Quotas in the AWS Identity and Access Management User Guide. 5. Under Parameters, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.

17 AWS Perspective Implementation Guide Step 1. Launch the stack

Parameter Default Description

Stack name aws-perspective A name to indicate the solution you are deploying.

AdminUserEmailAddress An email address to create the ﬁrst user. The temporary credentials will be sent to this email address.

AlreadyHaveConfigSetup No Confirmation of whether or not you already have AWS Config set up in the deployment account. For details, refer to Prerequisites (p. 15).

CreateElasticsearchServiceRole Yes Conﬁrmation of whether or not you already have a service- linked role for OpenSearch Service. For details, refer to Prerequisites (p. 15).

CreateNeptuneReplica No Choose whether to create a read replica for Neptune in a separate Availability Zone. Choosing Yes improves resilience; however, increases the cost of this solution.

NeptuneInstanceClass db.r5.large The instance type used to host the Amazon Neptune database. What you select here aﬀects the cost of running this solution.

ElasticsearchInstanceType m6g.large.elasticsearch The instance type used for your Elasticsearch data nodes. Your selection aﬀects the cost of running the solution.

CreateAPIGatewayCloudWatchLoYesgsRole If set to Yes, the solution creates a role and overwrites the existing APIGatewayCloudWatchLogsLogsRole property. Set to No if you already have an existing role set. For details, refer to Prerequisites (p. 15).

AthenaWorkgroup primary The Workgroup that will be used to issue the Athena query when the Cost feature is enabled.

OptOutOfSendingAnonymousUsaNogeMetrics Choose whether to opt out of sending basic usage metrics to AWS.

18 AWS Perspective Implementation Guide Step 2. Post-deployment conﬁguration tasks

6. Choose Next. 7. On the Conﬁgure stack options page, choose Next. 8. On the Review page, review and conﬁrm the settings. Check the boxes acknowledging that the template creates AWS Identity and Access Management (IAM) resources and require certain capabilities. 9. Choose Create stack to deploy the stack.

You can view the status of the stack in the AWS CloudFormation Console in the Status column. You should receive a CREATE_COMPLETE status in approximately 30 minutes.

Note If deleted, this stack removes all resources. If the stack is updated, it retains the Amazon Cognito user pool to ensure conﬁgured users are not lost.

Step 2. Post-deployment conﬁguration tasks

After AWS Perspective has been successfully deployed, review the following post-deployment conﬁguration tasks. Turn on Advanced security in Amazon Cognito

To turn on the Advanced security features for Amazon Cognito, follow the instructions on Adding Advanced Security to a User Pool in the Amazon Cognito Developer Guide. Note There is an additional cost for activating Advanced security in Amazon Cognito. Create Amazon Cognito users

AWS Perspective uses Amazon Cognito to manage all users and authentication. It creates a user for you during deployment and sends an email at the address provided with temporary credentials. To create additional users:

1. Sign in to the AWS Cognito console. 2. Choose Manage User Pools. 3. Choose perspective..userpool. 4. In the navigation pane, under General Settings, choose Users and groups. 5. On the Users tab, choose Create user. 6. On the Create user box, enter values for all required ﬁelds.

Form Field Required? Description

Username Yes The username that you will use to log in to AWS Perspective.

Send an invitation Yes (email only) When selected, sends a notiﬁcation as a reminder of the temporary password. Select Email only. If you select SMS (default) an error message will

19 AWS Perspective Implementation Guide Log in to AWS Perspective

Form Field Required? Description be displayed, but the user will still be created.

Temporary Password Yes Enter a temporary password. The user will be forced to change this when they log in to AWS Perspective for the ﬁrst time.

Phone Number No Enter a phone number in international format, for example, +44. Ensure Mark phone number as veriﬁed? box is selected.

Email Yes Enter a valid email address. Ensure Mark email as veriﬁed? box is selected.

7. Choose Create user.

Repeat this process to create as many users as you need. Note Every user will have the same level of access to resources discovered. We recommend provisioning a separate deployment of AWS Perspective for accounts that contain sensitive workloads or data. This allows you to restrict access to only the users that need it. Log in to AWS Perspective

After AWS Perspective is successfully deployed, determine the URL for the Amazon CloudFront distribution that serves the solution’s web UI.

1. Sign in to the AWS CloudFormation console. 2. Choose View nested to display the nested stacks that make up the AWS Perspective deployment. Depending on your preferences, nested stacks might already be displayed. 3. Select the main stack, which will be of the following format: aws-perspective--. 4. Select the Outputs tab and choose the URL in the Value column. 5. On the Sign in to AWS Perspective screen, enter the username and password that you received via email. Then take the following actions: a. Follow the prompts to change your password. b. Use the verification code sent to your email to complete account recovery. 6. When the AWS Perspective web UI loads, you will be prompted to import your first Region. We recommend that you first import the Region that AWS Perspective is deployed in because it contains resources that will help you explore the solution. For details, refer to Step 3. Import a Region (p. 21). Note When importing the Region that AWS Perspective is deployed in, you do not need to deploy the CloudFormation templates described in the Import a Region section. 7. When the import has succeeded, explore your resources. Refer to Web UI features and common tasks (p. 31) for details about getting started.

20 AWS Perspective Implementation Guide Step 3. Import a Region

Step 3. Import a Region

AWS Perspective requires certain infrastructure to be deployed in the Region you would like to import. This infrastructure consists of Global and Regional resources:

Global - Resources that are deployed once in an account and reused for each Region imported.

• An IAM Role (ZoomDiscoveryRole)

Regional - Resources that are deployed in each Region imported.

• An AWS Config Delivery Channel • An Amazon S3 Bucket for AWS Config • An IAM Role (ConfigRole)

There are two options to deploy this infrastructure:

• AWS CloudFormation StackSets (Recommended) • AWS CloudFormation

AWS CloudFormation StackSets

These steps guide you through importing a Region and deploying the AWS CloudFormation templates using CloudFormation StackSets.

1. Sign in to AWS Perspective. Refer to Log in (p. 20) for the URL. 2. Under Settings in the side navigation panel, select Accounts & Regions. 3. Select the AWS CloudFormation StackSets tab. 4. Follow the steps in the wizard.

Provide Regions

Provide the Regions to import using the form:

1. Account ID: Enter a 12-digit account ID or select an existing account ID. 2. Account name: Enter an account name or use a pre-populated value when selecting an existing account ID. 3. Regions: Select the Regions to import. 4. Select Add to populate the Regions in the Regions table below. 5. Review the Regions table, then select Next.

Alternatively, provide a Comma Separated Value (CSV) that contains the Regions to be imported.

"accountId","accountName","region" 123456789012,"test-account-1",eu-west-2 123456789013,"test-account-2",eu-west-1 123456789013,"test-account-2",eu-west-2 123456789014,"test-account-3",eu-west-3

1. Select Upload a CSV.

21 AWS Perspective Implementation Guide AWS CloudFormation

2. Locate and open your CSV ﬁle. 3. Review the Regions table, then select Next.

Download AWS CloudFormation templates

After providing the Regions, download the AWS CloudFormation templates required to deploy the Global and Regional infrastructure that allows AWS Perspective to discover resources in the provided Regions.

Global template

Download this template when the Region being imported is from an account that does not already have the Global resources provisioned.

If you are importing a Region from an account that does not already have a Region imported into AWS Perspective, then you must deploy both the global-resources.template and the regional- resources.template.

Regional template

Download this template when the Region being imported belongs to an account that already contains the Global resources. If you are importing a Region from an account that already has a Region imported into AWS Perspective, then only deploy the regional-resources.template.

In AWS Perspective, download the templates, and then select Next. Conﬁgure AWS CloudFormation StackSets

Conﬁgure AWS CloudFormation StackSets to deploy the templates across the necessary accounts and Regions.

1. Review the items in the Regions table. 2. Select Deploy for each Region to conﬁgure CloudFormation StackSets using the downloaded templates. 3. Select Next.

Review and Import

Review the Regions to be imported. Select Previous to go back to a previous step in the wizard to make any necessary changes.

Verify the Regions are correct, then select Import. AWS CloudFormation

These steps will guide you through importing a Region and deploying the AWS CloudFormation templates.

1. Sign in to AWS Perspective. Refer to Log in (p. 20) for the URL. 2. Select Accounts & Regions under Settings in the side navigation panel. 3. Select the AWS CloudFormation tab. 4. Follow the steps in the wizard.

22 AWS Perspective Implementation Guide AWS CloudFormation

Provide Regions

Provide the Regions to import using the form:

Alternatively, provide a Comma Separated Value (CSV) ﬁle that contains the Regions to be imported.

"accountId","accountName","region" 123456789012,"test-account-1",eu-west-2 123456789013,"test-account-2",eu-west-1 123456789013,"test-account-2",eu-west-2 123456789014,"test-account-3",eu-west-3

1. Select Upload a CSV. 2. Locate and open your CSV ﬁle. 3. Review the Regions table, then select Next.

Download AWS CloudFormation templates

Download the AWS CloudFormation templates required to deploy the Global and Regional infrastructure that allows AWS Perspective to discover resources in the provided Regions.

Global template

Download this template when the Region being imported is from an account that does not already have the Global resources provisioned. Refer to Determine the CloudFormation template required (p. 54) for help understanding which templates to use.

Regional template

Download this template when the Region being imported belongs to an account that has the Global resources provisioned. Refer to Determine the CloudFormation template required (p. 54) for help understanding which templates to use.

Download the templates, and then select Next. Deploy AWS CloudFormation templates

Review the Regions to be imported and deploy the AWS CloudFormation templates in the necessary Regions.

1. Review the items in the Regions table. 2. Select Deploy for each Region and deploy the downloaded templates. 3. When the CloudFormation templates have been deployed for each Region, choose Next.

Review and Import

Review the Regions to be imported. If changes are required, choose Previous to go back a step in the wizard and make the necessary changes.

23 AWS Perspective Implementation Guide Deploy the stack to provision the Global resources

Verify the Regions are correct, then select Import. Deploy the stack to provision the Global resources

Global resources must be deployed once per account. Do not deploy this template when importing a Region from an account that contains a Region that is already imported into AWS Perspective. If the Region has already been imported, skip to Deploy the stack to provision the Regional resources (p. 24).

1. Sign in to the AWS CloudFormation console. 2. Choose Create stack, and then select With new resources (standard). 3. On the Create stack page, in the Specify template section, select Upload a template file. 4. Choose Choose file and select the global-resource.template file that you downloaded, and choose Next. 5. On the Specify stack details page, assign a name to your solution stack. For information about naming character limitations, refer to IAM and STS Quotas in the AWS Identity and Access Management User Guide. 6. Under Parameters, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.

Field Name Default Description

Stack name aws-perspective The name of this AWS CloudFormation stack.

AccountId AWS Perspective deployment The account ID of the original account ID AWS Perspective deployment account. Must be left as default.

7. Choose Next. 8. Check the box acknowledging that AWS CloudFormation might create IAM resources with custom names. 9. Choose Create stack.

The new Regions will be scanned during the next discovery process, which runs at 15-minute intervals, for example: 15:00, 15:15, 15:30, 15:45.

Go to the Perspective UI to ﬁnd the estimated time until the next discovery in the side navigation panel.

If the expected resources do not appear in the UI, refer to Verify the Regions have been imported correctly (p. 27). Deploy the stack to provision the Regional resources

1. Sign in to the AWS CloudFormation console. 2. Choose Create stack, and then select With new resources (standard). 3. On the Create stack page, in the Specify template section, select Upload a template file. 4. Choose Choose file and select the regional-resources.template file that you downloaded earlier, and choose Next. 5. On the Specify stack details page, assign a name to your solution stack. For information about naming character limitations, refer to IAM and STS Quotas in the AWS Identity and Access Management User Guide.

24 AWS Perspective Implementation Guide Use CloudFormation StackSets to provision Global resources across accounts

6. Under Parameters, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.

Field Name Default Description

Stack name aws-perspective The name of this AWS CloudFormation stack.

AccountId Perspective deployment The account Id of the original account ID AWS Perspective deployment account. Must be left as default.

AggregationRegion Perspective deployment Region The Region that AWS Perspective was originally deployed into. Must be left as default.

AlreadyHaveConfigSetup No Confirmation of whether the Region already has AWS Config installed. Set to Yes if AWS Config is already installed in this Region.

7. Choose Next. 8. Check the box acknowledging that AWS CloudFormation might create IAM resources with custom names. 9. Choose Create stack.

The new Regions will be scanned during the next discovery process, which runs at 15-minute intervals, for example, 15:00, 15:15, 15:30, 15:45.

Go to the Perspective UI to ﬁnd the estimated time until the next discovery in the side navigation panel.

If the expected resources do not appear in the UI, refer to Verify the Regions have been imported correctly (p. 27). Use CloudFormation StackSets to provision Global resources across accounts Important First, complete the Prerequites for stack set operations to activate StackSets in your target accounts.

1. In the administrator account, sign in to the AWS CloudFormation console. 2. From the left navigation panel, select StackSets. 3. Choose Create StackSet. 4. On the Choose a template page, under Specify template, select Upload a template ﬁle, choose the global-resources.template ﬁle that you downloaded earlier, and choose Next. 5. On the Specify StackSet details page, assign a name to your StackSet. For information about naming character limitations, refer to IAM and STS Quotas in the AWS Identity and Access Management User Guide. 6. Under Parameters, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.

25 AWS Perspective Implementation Guide Use CloudFormation StackSets to provision Regional resources

Field Name Default Description

AccountId The AWS Perspective The account ID of the original deployment account ID AWS Perspective deployment account. Must be left as default.

7. Choose Next. 8. If using StackSets in an AWS Organization: Choose either Service managed permissions or Self service permissions. For details, refer to Using StackSets in an AWS Organization (p. 53).

If not using AWS Organizations:

Enter the IAM run role name used when following the StackSets prerequisite steps. For details, refer to Grant self-managed permissions. 9. Choose Next. 10.Under Add stacks to StackSet, in the Account numbers box, enter the account IDs for deploying the AWS Perspective account role. 11.Under Specify regions, select a Region to install the stack. 12.Under Deployment options, select Parallel, and then choose Next. 13.Check the box acknowledging that AWS CloudFormation might create IAM resources with custom names. Choose Submit.

Use CloudFormation StackSets to provision Regional resources Important First, complete the Prerequites for stack set operations to activate StackSets in your target accounts. If you have some Regions with AWS Conﬁg installed and some without, you must perform two StackSet operations, one for the Regions with AWS Conﬁg installed and one for those without.

1. In the administrator account, sign in to the AWS CloudFormation console. 2. From the left navigation panel, select StackSets. 3. Choose Create StackSet. 4. On the Choose a template page, under Specify template, select Upload a template ﬁle, choose the regional-resources.template ﬁle that you downloaded earlier, and choose Next. 5. On the Specify StackSet details page, assign a name to your StackSet. For information about naming character limitations, refer to IAM and STS Quotas in the AWS Identity and Access Management User Guide. 6. Under Parameters, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.

Field Name Default Description

AccountId The AWS Perspective The account ID of the original deployment account ID AWS Perspective deployment account. Must be left as default.

AggregationRegion The AWS Perspective The Region that AWS deployment Region Perspective was originally

26 AWS Perspective Implementation Guide Verify the Region was imported correctly

Field Name Default Description deployed into. Must be left as default.

AlreadyHaveConfigSetup No Confirmation of whether the Region already has AWS Config installed. Set to Yes if AWS Config is already installed in this Region.

If not using AWS Organizations:

Enter the IAM run role name used when following the StackSets prerequisite steps. For details, refer to Grant self-managed permissions. 9. Choose Next. 10.Under Add stacks to StackSet, in the Account numbers box, enter the account IDs to deploy the AWS Perspective account role to. 11.Under Specify regions, select a Region to install the stack. This installs the stack in these Regions in all the accounts entered in step 6. 12.Under Deployment options, select Parallel, and then choose Next. 13.Check the box acknowledging that AWS CloudFormation might create IAM resources with custom names. Choose Submit.

Verify the Region was imported correctly

1. Sign in to AWS Perspective (or refresh the page if it’s already loaded). Refer to Log in (p. 1) for the URL. 2. From the left navigation panel, under Settings, select Imported Regions.

The Region, account name, and account ID appear in the table. The Last Scanned column shows when AWS Perspective last discovered resources in that Region. Note If the Last Scanned column stays blank for more than 30 mins, refer to Debugging the discovery component (p. 53).

Step 4. Set up the cost feature

The cost feature requires manual set up of Cost and Usage Reports (CURs).

1. Set up a scheduled Cost and Usage Report. 2. Set up S3 replication (when CURs are outside the AWS Perspective deployment account) 3. Deploy AWS CloudFormation to set up Amazon Athena.

27 AWS Perspective Implementation Guide Create the AWS Cost and Usage Report in the AWS Perspective deployment account Create the AWS Cost and Usage Report in the AWS Perspective deployment account

1. Sign in to the Billing console of the account from which you would like to gather cost data. 2. Under the Cost Management category on the left pane, select Cost & Usage Reports. 3. Choose Create Report. 4. Use aws-perspective-cost-and-usage- as the Report name. Note You must follow this naming convention because a small amount of infrastructure will be deployed to facilitate the querying of the CURs. 5. Check the Include resource IDs box. Note You must select the Include resource IDs box to view cost data. This ID is needed to match with the resources discovered by AWS Perspective. 6. Choose Next. 7. On the Delivery options page, choose Configure. 8. Select the aws-perspective-v-costandusagereportbucket- S3 bucket to store the CUR. Choose Next. 9. Review the policy, check the confirmation box, and choose Save. 10.Set the Report prefix path to aws-perspective. 11.Select Daily for the time granularity. 12.Under Enable report data integration for, select Amazon Athena. 13.Choose Next. 14.Choose Review and Complete.

To verify that the report is correctly set up, check the S3 bucket for the test ﬁle. Note It can take up to 24 hours for the reports to be uploaded to your bucket. Create the AWS Cost and Usage Report in an external account

28 AWS Perspective Implementation Guide Set up replication

7. On the Delivery options page, choose Configure. 8. Create a new Amazon S3 bucket to store the CURs. 9. Review the policy, check the confirmation box, and choose Save. 10.Set the Report prefix path to aws-perspective. 11.Select Daily for the time granularity. 12.Under Enable report data integration for, select Amazon Athena. 13.Choose Next. 14.Choose Review and Complete.

To verify that the report is correctly set up, check the S3 bucket for the test ﬁle. Note It can take up to 24 hours for the reports to be uploaded to your bucket.

Next, set up replication to the AWS Perspective deployment account. Set up replication

Set up replication into the S3 bucket created during deployment. The S3 bucket follows the following format: aws-perspective-v-costandusagereportbucket-. This allows AWS Perspective to query it via Amazon Athena.

1. Sign in to the Amazon S3 console of the AWS account you have created a CUR that needs to be replicate. 2. Select the S3 bucket created when configuring your AWS Cost and Usage Report. (Step 7 of Create and schedule the AWS Cost and Usage Report (p. 1).) 3. Select the Management tab. 4. Under Replication rules, choose Create replication rule. 5. Under Replication rule configuration, in the Replication rule name box, enter a descriptive rule ID. 6. Under Source bucket, select This rule applies to all objects in the bucket to configure the rule scope. 7. Under Destination, configure the following: a. Select Specify a bucket in another account. b. Enter the account ID. c. Enter a prefix of aws-perspective/aws-perspective-cost-and-usage-

Provide the account ID for the location of the source S3 bucket. d. Enter a value for the Bucket name that was created during deployment of AWS Perspective. You can find this by following the instructions in Locating deployment resources (p. 47), using the logical ID CostAndUsageReportBucket and the stack name you specified when first deploying AWS Perspective. e. Select the checkbox for Change object ownership to destination bucket owner. 8. Under IAM role, choose Create new role. Note A replication role might already exist. You can select it and ensure it has the required S3 replication role actions (p. 55). 9. Log in to the AWS Management Console where AWS Perspective is installed, navigate to the S3 service page and select the CostAndUsageReportBucket S3 bucket. For details, refer to Locating deployment resources (p. 47). 10.Select the Management tab. 11.Under Replication rules, from the Actions drop-down menu, select Receive replicated objects.

29 AWS Perspective Implementation Guide Step 5. Edit S3 bucket lifecycle policies

12.Under Source bucket account settings:

a. Enter the Source bucket account ID. b. Choose Generate policies. c. Under Policies, select view bucket policy. d. Select Include permission to change object ownership to destination bucket owner. e. Choose Copy and paste the S3 bucket policy into the policy for the S3 bucket in the account you are replicating to (the AWS Perspective Cost S3 bucket). This gives it access to copy objects to it. Refer to Cost Bucket replication policy (p. 56) for an example S3 Bucket Policy.

Note When replicating CURs from multiple AWS accounts. You need to ensure the bucket policy on the destination bucket (within the Perspective account) has the ARN of each IAM Role you are using from each account. Refer to Cost Bucket replication policy (p. 56) for more details.

When the reports are in the AWS Perspective account cost data appears on the bounding boxes and individual resources.

Figure 9: Example of a bounding box with cost data

Step 5. Edit S3 bucket lifecycle policies

During deployment we conﬁgure lifecycle policies on two buckets:

• PerspectiveCostBucket • AccessLogsBucket

Important These lifecycle policies will delete data from these buckets after 90 days. You can edit the lifecycle to ﬁt any internal policies you have.

For additional information about how to navigate the web UI, refer to Web UI features and common tasks (p. 31).

30 AWS Perspective Implementation Guide Side navigation pane

Web UI features and common tasks

The AWS Perspective solution deploys an AWS Amplify web UI to build architecture diagrams of your services and resources. This section provides details about the features of the web UI and how to navigate it.

Side navigation pane

If the left pane is not visible, choose the menu icon to expand the list of options. The side navigation pane provides the following functionalities.

Option Sub options Description

Resources All Select resources to visualize. Resources are grouped by service. Select to visualize individual resources.

Types Select resources to visualize. Resources are grouped by type. Select to visualize all resources of a particular type, for example, all Lambda functions.

Costs & Usage Query Build a query to run against Cost & Usage Reports (CURs). Requires extra setup (p. 27).

Generate cost report Produces a cost report detailing the incurred costs of the resources in your architecture diagram.

Architecture Diagrams Manage Save, load, and delete architecture diagrams.

Actions Export Export the architecture diagram in a variety of formats including CSV, JSON, PNG, and Draw.io.

Clear Map This will remove all resources from the current architecture diagram.

Preferences Filters Filters that can be applied to the data. These are persisted to S3 to allow them to be saved across sessions.

Settings Imported Regions Manage the Regions that AWS Perspective can discover resources in.

31 AWS Perspective Implementation Guide AWS Perspective architecture diagrams

Option Sub options Description

Cost Settings Activate/deactivate the Cost processing feature. It also contains links for help setting up the feature.

Get in touch Feature Request Provide details of a new feature they would like to view in AWS Perspective.

Raise an issue Log an issue that they have encountered on our GitHub repository page.

AWS Perspective architecture diagrams

Architecture diagrams generated by AWS Perspective appear in the main body of the web UI. Each architecture diagram displays the selected resources and the relationships between those resources. Resource relationships are presented as edges between resources in the architecture diagram.

AWS Perspective architecture diagrams are interactive, you can drag resources to another position and zoom in or out to produce the architecture diagram to suit your needs. Build an AWS Perspective architecture diagram Note Before you start this exercise, ensure you have imported the AWS Perspective deployment Region as suggested in step 6 of the Log in (p. 20) procedure.

The following steps walk you through building an architecture diagram.

1. Under the Resources category on the left pane, select All.

If the left pane is not visible, choose the menu icon to expand the list. 2. Choose Lambda to expand the list of resources directly related to Lambda.

In the AWS Perspective account, there are both environment variables and functions. 3. Choose Function to expand the list of Lambda functions. 4. Choose aws-perspective---GremlinFunction. AWS Perspective then builds the architecture diagram.

32 AWS Perspective Implementation Guide Build an AWS Perspective architecture diagram

Figure 10: AWS Perspective architecture diagram for the GremlinFunction Lambda function

The GremlinFunction Lambda function appears at the center of the AWS Perspective architecture diagram, with a line to each related resource. The architecture diagram groups the resources by account, Region, Availability Zone, VPC, subnet, and type.

You can explore the workload by right-clicking on the resources and selecting Expand. This gathers the related resources for each resource selected.

To learn more about a resource, right-click and select Show resource details to view the conﬁguration information about the selected resource. Context menu

Use the context menu to explore AWS Perspective architecture diagrams. Select a resource in the architecture diagram.

Option Sub options Description

Focus Redraw the visualization to show this resource and its immediate dependencies, removing everything else.

Expand Selected resources View additional resource dependencies and redraw the architecture diagram to include the resource dependencies of the selected resource(s).

This resource

Remove Remove this resource from the current visualization.

Show resource details Opens a dialog box containing the conﬁguration details for the selected resource.

33 AWS Perspective Implementation Guide Build an AWS Perspective architecture diagram

After choosing a resource grouping (for example, a group of tags), the following options become available.

Option Sub options Description

Collapse All Collapse the group of resources down to one icon.

Remove All Remove all the resources in the group.

Diagram Clear Remove the architecture diagram and leave a blank canvas.

Fit Reset the viewport on the canvas to bring the contents to the center.

The following table shows the options available after choosing an empty section of the canvas.

Option Sub-options Description

Diagram Clear Remove the architecture diagram and leave a blank canvas.

Fit Reset the viewport on the canvas to bring the contents to the center.

Costs & usage Cost report Produces a report detailing the costs of the resources in the architecture diagram.

Resources Group resources Provides a layout with resources grouped by type.

Edges Show or hide the edges in the architecture diagram.

Resource Details dialog box

The Resource details dialog box is accessed from the context menu and provides the following:

• High level information about the selected resource. • A link to access the resource within the AWS Management Console, when possible. • The data object that we have stored for that resource as JSON.

The structure and content of the resource details dialog depends on the type of resource being viewed.

To view a JSON formatted document holding the data about a resource, expand Raw data.

34 AWS Perspective Implementation Guide Build an AWS Perspective architecture diagram

Figure 11: Resource details box

Note: You can also view a high-level overview of a resource without selecting it. When you hover over a resource, a small detail box appears towards the side of the screen containing some key details about the resource. Visualize AWS resources by resource type

1. Under the Resources category on the left pane, select Types. 2. Choose Lambda to expand the list of resources directly related to Lambda.

In the AWS Perspective Region, there are both Environment variables and Functions. 3. Choose Function to build an architecture diagram of all Lambda functions discovered across your imported Regions. The architecture diagram will be grouped by accounts and Regions. Figure 12 is an example architecture diagram.

35 AWS Perspective Implementation Guide Costs & Usage

Figure 12: AWS Perspective architecture diagram of Lambda functions Note If resources are not appearing, verify if you have any ﬁlters (p. 1) applied. Search for resources

The Search bar is useful for quickly finding AWS resources. Imagine that a CloudWatch log file contains the name of an EC2 instance that has terminated and you want to view potentially affected resources. Simply search for the instance ID.

1. Enter your search term into the search bar at the top of the screen. The autocomplete dropdown helps you narrow down the possible matches. 2. Select the resource to visualize from the autocomplete dropdown.

After a brief pause, an AWS Perspective architecture diagram builds showing the resource and its related resources.

Costs & Usage

The Costs & Usage feature lets you query for estimated costs associated to individual or grouped resources in an account. This feature returns unblended costs from the Cost and Usage Report. For details about how to set up the Cost and Usage Report with AWS Perspective, refer to Step 4. Set up the cost feature (p. 27). View costs by resource

A quick way to view the resources that have incurred the highest cost is to use the Query all Resources option. This will return a list of resources ordered by the estimated cost (highest ﬁrst)

1. Sign in to AWS Perspective (or refresh the page if it’s already loaded). Refer to Log in (p. 1) for the URL.

36 AWS Perspective Implementation Guide View costs by service

2. Under the Costs & Usage category on the left pane, select Query. 3. Under Query, select Query all Resources. 4. Select the Account IDs, Regions, and a To/From date range, and then choose Submit.

The Summary panel contains the following information: • Estimated AWS costs • Number of AWS resources • Date range

The Resources panel contains the following information: • Resource • Estimated cost • Account ID • Region 5. Select a single resource or multiple resources, and then choose Add to diagram to display them on a canvas.

View costs by service

The Query by Service option returns estimated costs broken down by service type. Select the service, for example AWS Lambda, and the estimated cost returns.

1. Under the Costs & Usage category on the left pane, select Query. 2. Under Query, select Query by Service. 3. Select the Account IDs, Regions, Service name, and a To/From date range, and then choose Submit.

The Summary panel contains the following information: • Estimated AWS costs • Number of AWS Resources • Date range

The Resources panel contains the following information: • Resource • Estimated cost • Account ID • Region

View costs by ARN

The Query by ARN option provides estimated cost information for particular Amazon Resource Names (ARNs).

1. Under the Costs & Usage category on the left pane, select Query. 2. Under Query, select Query by ARN. 3. Select the Account Ids, Regions, Add Resource ARN, and a To/From date range, and then choose Submit.

The Summary panel contains the following information: • Estimated AWS costs 37 AWS Perspective Implementation Guide Generate a Cost Report

• Number of AWS Resources • Date range

The Resources panel contains the following information: • Resource • Estimated cost • Account ID • Region

Generate a Cost Report

To view estimated cost information for your workloads, you can generate a high-level cost report.

1. Follow the steps to Build an AWS Perspective architecture diagram (p. 32). 2. Under the Costs & Usage category on the left pane, select Generate cost report. Alternatively, you can right-click on the canvas, select Costs & usage, and then choose Cost report.

A dialog opens containing an overview of the resources with their incurred a costs. It provides the following options: a. To rerun the query for a speciﬁc time period, under Time period, in the From/To box, change the date. b. To export the Resources table as a Comma Seperated Value (CSV) ﬁle, select Actions, and then choose Export CSV. c. To build a line chart, select resources from the Resources table, select Actions, and then choose Update graph.

Export AWS Perspective architecture diagrams Export an AWS Perspective architecture diagram as CSV

1. Sign in to AWS Perspective (or refresh the page if it’s already loaded). Refer to Log in (p. 1) for the URL. 2. Under the Actions category on the left pane, under Export, select CSV. The Export Graph dialog box loads a list of resources that are about to be exported. 3. Enter a ﬁle name and change the delimiter, if required. 4. Choose Export and the CSV ﬁle downloads to your computer.

Export an AWS Perspective architecture diagram as PNG

1. Under the Actions category on the left pane, under Export, select PNG. 2. Enter a ﬁle name. 3. Choose Download to save it to your computer.

38 AWS Perspective Implementation Guide Export an AWS Perspective architecture diagram as JSON

Export an AWS Perspective architecture diagram as JSON

1. Under the Actions category on the left pane, under Export, select JSON. 2. Enter a ﬁle name. 3. Choose Download to save it to your computer.

Export an AWS Perspective architecture diagram to draw.io

Under the Actions category on the left pane, under Export, select Drawio.

Draw.io opens in a new tab displaying your architecture diagram.

Saving, downloading, and ﬁltering Save an AWS Perspective architecture diagram

You can save architecture diagrams created in AWS Perspective to S3. Saving ﬁles allows you to continue editing them later.

1. Sign in to AWS Perspective (or refresh the page if it’s already loaded). Refer to Log in (p. 1) for the URL. 2. Under the Architecture diagrams category on the left pane, select Manage. 3. On the You tab, enter a ﬁle name and choose Save. Only you can view the saved architecture diagram.

If you would like other users in your deployment of AWS Perspective to have access to the architecture diagram, select the All users tab and save your ﬁle. Download an AWS Perspective architecture diagram

1. Under the Architecture diagrams category on the left pane, select Manage. 2. Choose the relevant tab, You or All users. A list of architecture diagrams available to you appears. 3. Choose a diagram and choose Preview to verify the diagram in the preview section. 4. When you are ready to load the diagram, choose Download. The diagram renders in the main canvas for you to start editing.

Filtering in AWS Perspective

There are two ways that you can ﬁlter the data in AWS Perspective: by account and Region, and by resource type. Accounts & Regions ﬁlter

These ﬁlters allow you to restrict the accounts and Regions you view data from.

39 AWS Perspective Implementation Guide Filtering in AWS Perspective

View all Regions in an account

1. Under the Preferences category on the left pane, select Filters. 2. Choose the Accounts & Regions tab. 3. Locate the account in the Accounts table. 4. Toggle the Show column.

Display or hide global resources

1. Under the Preferences category on the left pane, select Filters. 2. Choose the Accounts & Regions tab. 3. Locate the account to view global resources. 4. Toggle the Show global resources column.

Display or hide Regions

1. Under the Preferences category on the left pane, select Filters. 2. Choose the Accounts & Regions tab. 3. Locate the account that contains the Region to display or hide. 4. Select the account. 5. The Regions table updates to show discoverable Regions. 6. Locate the Region to update. 7. Toggle the Show column.

Resource Types ﬁlter

These ﬁlters allow you to show or hide particular resource types. Show or hide a resource type

1. Under the Preferences category on the left pane, select Filters. 2. Choose the Resource Types tab. 3. Search for the resource type you want to ﬁlter by. 4. Toggle the Show column.

Show all resources types

1. Under the Preferences category on the left pane, select Filters. 2. Choose the Resource Types tab. 3. Choose Include all.

Hide all resources types

This can be helpful to select a small subset of resource types to display.

1. Under the Preferences category on the left pane, select Filters.

40 AWS Perspective Implementation Guide Filtering in AWS Perspective

2. Choose the Resource Types tab. 3. Choose Exclude all.

Filter badge

A badge displayed under the Preferences category on the left pane, next to Filters shows the number of ﬁlters currently in action.

If there is no badge next to Filters then no ﬁlters have been applied and zero resources will appear. You must select the account and Regions you want to view resources from.

41 AWS Perspective Implementation Guide

Additional resources

AWS services

• Amazon API Gateway • Amazon Virtual Private Cloud • Amazon Athena • AWS AppSync • Amazon CloudFront • AWS CloudFormation • Amazon CloudWatch • AWS CodePipeline • Amazon Cognito • AWS CodeBuild • Amazon DynamoDB • AWS Conﬁg • Amazon Elastic Container Registry • AWS Fargate • Amazon Elastic Container Service • AWS Identity and Access Management (IAM) • Amazon OpenSearch Service • AWS Lambda • Amazon Neptune • AWS SDK for Java • Amazon Simple Notiﬁcation Service • AWS Systems Manager • Amazon Simple Storage Service

AWS APIs

• describeVpcEndpoints • describeTaskDeﬁnition • describeSpotFleetRequests • listTasks • describeSpotInstanceRequests • describeTasks • describeDBClusters • listServices • getAccountAuthorizationDetails • describeServices • describeInstances • listClusters • describeLoadBalancers • describeClusters • describeListeners • listContainerInstances • describeTargetGroups • describeContainerInstances • describeTargetHealth • getRestApis • getFunction • getResources • GetFunctionConﬁguration • getIntegration

42 AWS Perspective Implementation Guide Using the AWS Management Console

Update the stack

To upgrade to the lastest version of the AWS Perspective solution, use the AWS Management Console or the AWS Command Line Interface (AWS CLI).

Using the AWS Management Console

1. Download the template for AWS Perspective. 2. Before beginning the upgrade, you must deactivate the discovery process. Sign in to the Amazon Elastic Container Service console. 3. Select the cluster named aws-perspective--cluster. 4. Select Scheduled Tasks. 5. Select aws-perspective--rule. 6. Choose Edit. 7. Uncheck the Schedule rule enabled checkbox and choose Update. 8. Sign in to the AWS CloudFormation console. 9. Select the stack with the name provided during deployment and choose Update stack. 10.Select the Replace current template radio box, then select the Upload a template ﬁle radio box and upload the ﬁle downloaded in step 1. 11.Choose Next. 12.Under Parameters, the following new parameters have been added. Review the default parameters for this solution template and modify them as necessary.

Parameter Default Description

ElasticsearchInstanceType m6g.large.elasticsearch The instance type that will be used for your Elasticsearch data nodes. What you select here aﬀects the cost of running the solution. Note, the default value will upgrade the instance type of the cluster from the previous default of m4.large.elasticsearch. If you continue using the same instance type, you must enter the instance type that the deployed cluster is currently using.

CreateAPIGatewayCloudWatchLoYesgsRole If set to Yes, Perspective will create a role and overwrite the existing ApiGateway Account CloudWatchLogsRoleArn property. Set this to No if you already have an existing role set. Refer to the Prerequisites (p. 15).

43 AWS Perspective Implementation Guide Using AWS Command Line Interface

13.On the Conﬁgure stack options page, choose Next. 14.On the Review page, review and conﬁrm the settings. Check the boxes acknowledging that the template will create AWS Identity and Access Management (IAM) resources and require certain capabilities. 15.Choose Update stack to deploy the stack.

After the AWS Perspective stacks have updated, restart the discovery process:

1. Sign in to the Amazon Elastic Container Service console within the account and Region AWS Perspective is deployed. 2. From the left-hand menu, select Repositories, then select the aws-perspective---taskstack- stack. 3. Copy the image tag for the latest entry in the table, for example, aws-perspective-. 4. From the left-hand menu, select Task Definitions, then select the latest AWS Perspective task definition: aws-perspective--taskgroup. 5. Select the checkbox for the first entry in the table: aws-perspective-- taskgroup:, then choose Create new revision. 6. Scroll down to Container Definitions and select aws-perspective-. 7. Update the aws-perspective- image text after the final ':' with the image tag copied in step 3. 8. Choose Update, then scroll down and choose Create. 9. From the left-hand menu, select Clusters, then select the cluster named aws- perspective--cluster. 10.Select Scheduled Tasks, select aws-perspective--rule, then choose Edit. 11.Select the Schedule rule enabled checkbox and choose Update.

Using AWS Command Line Interface

Determine whether the AWS Command Line Interface (AWS CLI) is available in your environment. For installation instructions, refer to What Is the AWS Command Line Interface in the AWS CLI User Guide.

1. Download the AWS Perspective CloudFormation template. 2. Before beginning the upgrade, you must deactivate the discovery process by running the following command:

aws events disable-rule --name aws-perspective--rule

3. Run the following command in the directory the template was downloaded to:

$ aws cloudformation update-stack --stack-name --template-body file:// --parameters ParameterKey= AdminUserEmailAddress,UsePreviousValue=true ParameterKey= AdminUserEmailAddress,UsePreviousValue=true ParameterKey= AlreadyHaveConfigSetup,UsePreviousValue=true ParameterKey= CreateElasticsearchServiceRole,UsePreviousValue=true ParameterKey= CreateNeptuneReplica,UsePreviousValue=true ParameterKey= NeptuneInstanceClass,UsePreviousValue=true ParameterKey= ElasticsearchInstanceType,ParameterValue= ParameterKey= OptOutOfSendingAnonymousUsageMetrics,UsePreviousValue=true

4. After the AWS Perspective stacks have updated, update and restart the discovery Amazon ECS task. Run the following commands to create a new ECS task revision:

44 AWS Perspective Implementation Guide Resources removed with stack update

TASK_DEFINITION=aws-perspective--taskgroup RULE_NAME=aws-perspective--rule

NEW_TASK_DEFINTION=$(aws ecs describe-task-definition --task-definition ${TASK_DEFINITION} \ --query '{ containerDefinitions: taskDefinition.containerDefinitions, family: taskDefinition.family, taskRoleArn: taskDefinition.taskRoleArn, executionRoleArn: taskDefinition.executionRoleArn, networkMode: taskDefinition.networkMode, volumes: taskDefinition.volumes, placementConstraints: taskDefinition.placementConstraints, requiresCompatibilities: taskDefinition.requiresCompatibilities, cpu: taskDefinition.cpu, memory: taskDefinition.memory}')

aws ecs register-task-definition --cli-input-json "$NEW_TASK_DEFINTION"

5. Save the scheduled task rule description to a temporary ﬁle:

aws events list-targets-by-rule --rule ${RULE_NAME} --query 'Targets[0]' > params.json

6. Retrieve the scheduled task ARN and task role ARN by running the following command:

aws ecs describe-task-definition --task-definition ${TASK_DEFINITION} \ --query '{ RoleArn: taskDefinition.taskRoleArn, TaskDefinitionArn: taskDefinition.taskDefinitionArn}'

7. In a text editor, update the RoleArn and TaskDefinitionArn ﬁelds in params.json with the values returned in the previous step. 8. Update the scheduled task:

aws events put-targets --rule ${RULE_NAME} rule --targets file://params.json

9. Reactivate the scheduled task:

aws events enable-rule --name ${RULE_NAME}

Resources removed with stack update

When you update a previous installation of AWS Perspective, resources will be removed to reﬂect the changes in the architecture introduced by the new version.

The following table lists the resources removed as part of updating the stack:

Resource name Resource type

aws-perspective-- AWS::DynamoDB::Table PerspectiveCostDBTable-*

aws-perspective-- AWS::S3::Bucket PerspectiveCostBucket -*

aws-perspective-- AWS::S3::BucketPolicy PerspectiveCostBucketPolicy -*

45 AWS Perspective Implementation Guide Resources removed with stack update

Resource name Resource type aws-perspective-- AWS::IAM::Role PerspectiveCostRole -* aws-perspective-- AWS:ApiGateway::Account APIGatewayAccount -* aws-perspective-- AWS::ApiGateway::Account ServerAPIGatewayAccount -* aws-perspective-- Custom::Setup CleanupPerspectiveCostBucket -* aws-perspective-- AWS::IAM::Role APIGatewayCloudWatchLogsRole -* aws-perspective-- AWS::IAM::Role ServerAPIGatewayCloudWatchLogsRole -*

46 AWS Perspective Implementation Guide

Locating deployment resources

Follow these steps to locate resources that AWS Perspective deployed into your account.

1. Sign in to the AWS CloudFormation console. 2. Select the Region you deployed AWS Perspective in.

Depending on the usage of this account, it may contain multiple stacks for diﬀerent workloads. AWS Perspective will create a main stack called aws-perspective-- and multiple nested stacks beneath it, all preﬁxed with aws- perspective. 3. Select each stack to access the resources deployed using that template. 4. Select the Resources tab and choose the Physical ID link for the relevant resource to view the resource in its respective service console.

If you know the Logical ID of a resource, you can also use search.

47 AWS Perspective Implementation Guide

Supported resources

The following table contains the supported resources that AWS Perspective discovers. Details are provided in the corresponding AWS documentation listing. Select the link and search for the specific resource type. AWS Perspective might find resources supported by AWS Config, but does not list them due to transitive relationships between resources. The following list provides the resources that AWS Perspective finds.

Resource type Source Description

AWS::IAM::Policy AWS Conﬁg AWS Conﬁg docs

AWS::IAM::User AWS Conﬁg

AWS::IAM::Role AWS Conﬁg

AWS::IAM::Role_In_Line_Policy AWS Conﬁg

AWS::IAM::CustomerManagedPolicyStatement AWS Conﬁg

AWS::EC2::VPC AWS Conﬁg

AWS::EC2::Instance AWS Conﬁg

AWS::EC2::Volume AWS Conﬁg

AWS::RDS::DBInstance AWS Conﬁg

AWS::EC2::NetworkInterface AWS Conﬁg

AWS::Lambda::Function AWS Conﬁg

AWS::S3::Bucket AWS Conﬁg

AWS::DynamoDB::Table AWS Conﬁg

AWS::CloudFormation::Stack AWS Conﬁg

AWS::CloudWatch::Alarm AWS Conﬁg

AWS::EC2::SecurityGroup AWS Conﬁg

AWS::EC2::EIP AWS Conﬁg

AWS::ElasticLoadBalancing::LoadBalancer AWS Conﬁg

AWS::ElasticLoadBalancingV2::LoadBalancer AWS Conﬁg

AWS::AutoScaling::AutoScalingGroup AWS Conﬁg

AWS::EC2::NatGateway AWS Conﬁg

AWS::Elasticsearch::Domain AWS Conﬁg

AWS::KMS::Key AWS Conﬁg

AWS::CodeBuild::Project AWS Conﬁg

48 AWS Perspective Implementation Guide

Resource type Source Description

AWS::CodePipeline::Pipeline AWS Conﬁg

AWS::QLDB::Ledger AWS Conﬁg

AWS::Redshift::Cluster AWS Conﬁg

AWS::ApiGateway::RestApi SDK get-rest-apis

AWS::ApiGateway::Resource SDK

AWS::ApiGateway::Method SDK

AWS::ECS::Cluster SDK list-clusters

AWS::ECS::Service SDK describe-services

AWS::ECS::Task SDK describe-tasks

AWS::ECS::TaskDeﬁnition SDK describeTaskDeﬁnition

AWS::IAM::AWSManagedPolicy SDK getAccountAuthorizationDetails

AWS::RDS::DBCluster SDK describeDBClusters

AWS::EC2::Spot SDK describeSpotInstanceRequests

AWS::EC2::SpotFleet SDK describeSpotFleetRequests

AWS::ECS::EnvironmentVariable SDK describeTaskDeﬁnition

AWS::VPC::Endpoint SDK describeVpcEndpoints

49 AWS Perspective Implementation Guide

Supported deployment Regions

The following table lists the supported AWS Regions for AWS Perspective.

Region ID Region Name

us-east-1 US East (N. Virginia)

us-east-2 US East (Ohio)

us-west-2 US West (Oregon)

ap-south-1 Asia Paciﬁc (Mumbai)*

ap-northeast-2 Asia Paciﬁc (Seoul)

ap-southeast-1 Asia Paciﬁc (Singapore)

ap-southeast-2 Asia Paciﬁc (Sydney)

ap-northeast-1 Asia Paciﬁc (Tokyo)

ca-central-1 Canada (Central)

eu-west-2 Europe (London)

eu-central-1 Europe (Frankfurt)

eu-west-1 Europe (Ireland)

eu-west-3 Europe (Paris)**

eu-north-1 Europe (Stockholm)

sa-east-1 South America (São Paulo)

* During deployment, for the ElasticsearchInstanceType parameter, select c6g.large.elasticsearch.

** During deployment, for the ElasticsearchInstanceType parameter, select m5.large.elasticsearch.

50 AWS Perspective Implementation Guide

IAM roles

The following table lists all the Identity and Access Management (IAM) roles employed by AWS Perspective.

IAM role name

aws-perspective--APIGatewayCloudWatchLogs-*

aws-perspective--PerspectiveGremlinAppSyn-*

aws-perspective--AuthPerspectiveRole-*

aws-perspective--CleanupBucketFunctionRol-*

aws-perspective--CleanupRepositoryFunctio-*

aws-perspective--CodePipelineRole-*

aws-perspective--CodeBuildRole-*

aws-perspective--ConﬁgRole-*

aws-perspective--DrawIOExportFunctionRole-*

aws-perspective--EcsTaskExecutionRole-*

aws-perspective--FlowLogRole-*

aws-perspective--LambdaEdgeFunctionRole-*

aws-perspective--LambdaFunctionRole-*

aws-perspective--NeptuneRole-*

aws-perspective--PerspectiveCostLambdaApp-*

aws-perspective--PerspectiveCostLambdaRol-*

aws-perspective--PerspectiveDiscoveryTask-*

aws-perspective--PerspectiveGremlinAppSyn-*

aws-perspective--PerspectiveGremlinLambda-*

aws-perspective--PerspectiveSettingsDynam-*

aws-perspective--RegionalEdgeLambdaFuncti-*

aws-perspective--SearchLambdaRole-*

aws-perspective--ServerAPIGatewayCloudWat-*

aws-perspective--PerspectiveSettingsLambd-*

aws-perspective-ApiGatewayCloudWatchRole-*

aws-perspective-CleanupBucketFunctionRole-*

51 AWS Perspective Implementation Guide

IAM role name aws-perspective-LambdaExecutionRole-* aws-perspective-PerspectiveAppSyncLoggingRole- aws-perspective-PerspectiveDiscoveryRole-*

AWSServiceRoleForAmazonElasticsearchService

52 AWS Perspective Implementation Guide

Using StackSets in an AWS Organization

If you are using StackSets in an AWS Organization, choose either Service managed permissions or Self service permissions, depending on how your organization has chosen to manage IAM permissions for StackSets. For more information about deploying StackSets in an organization, refer to Use AWS CloudFormation StackSets for Multiple Accounts in an AWS Organization on the AWS blog.

53 AWS Perspective Implementation Guide

Debugging the discovery component

If you have imported an account and Region that does not show resources within the AWS Perspective UI, check the following items to ensure you have everything set up.

1. Check that you have deployed the CloudFormation template in the AWS Region of the account you are importing and that it created successfully. Ensure you have followed the steps for importing a Region (p. 21). 2. Double check the account ID that you have imported is correct. Follow the steps in verify the Region was imported correctly (p. 27) to verify the import details. 3. If resources are still not appearing, then there could be a problem with the discovery component. Check this by following these steps:

To retrieve the logs for the API that the discovery service uses: a. Sign in to the AWS Management Console in the account you deployed AWS Perspective in. b. Choose Services. c. From the collection of services, choose Lambda. d. Search for GremlinFunction and select it. e. Choose the Monitoring tab. f. Choose View logs in CloudWatch. g. In the Log streams section, select the latest log file link in the table (usually the top entry). This opens up the log file. h. Search for "400" or "500". This searches for HTTP 400 or 500 error codes in the log file. If it returns any entries, then it means that there is a problem in the discovery component.

To retrieve the logs for the discovery component: a. Sign in to the AWS Management Console in the account you deployed AWS Perspective in. b. Choose Services. c. From the collection of services, choose CloudWatch. d. Under the Log section, select Log Groups. e. Search for the log group /ecs/aws-perspective----task. f. Select the latest Log Stream tab. g. Scroll to the top of the page and choose Load More until the No older events at this moment message appears. h. Select Actions and then Download search results from the menu. i. Save the ﬁle locally.

To request assistance from AWS, raise an issue in our GitHub repository. Select create an issue and follow the prompts and include the logs from both the API and the discovery process.

54 AWS Perspective Implementation Guide

S3 replication role actions

The IAM role used to perform the replication needs to have the following actions:

s3:ReplicateObject

s3:ReplicateDelete

s3:ReplicateTags

s3:ObjectOwnerOverrideToBucketOwner

s3:ListBucket

s3:GetReplicationConﬁguration

s3:GetObjectVersionForReplication

s3:GetObjectVersionAcl

s3:GetObjectVersionTagging

s3:GetObjectRetention

s3:GetObjectLegalHold

To verify the role has the replication role actions:

1. Copy the name of the role name in the S3 Replication wizard. 2. Navigate to the IAM Console within the account you are setting up the replication in. 3. Paste the name of the role into the Search IAM box. 4. Select the top item from the list. This is the IAM role that will be used. 5. Under Permissions policies, expand the Managed policy. 6. Ensure it has the actions detailed in the table above.

55 AWS Perspective Implementation Guide

S3 bucket policy

Below is an example of an S3 bucket policy that will allow Cost and Usage Reports (CURs) to be uploaded to the bucket along with permissions to allow external accounts to replicate Objects into it. You will need to add the IAM Role from each external AWS account to this policy to grant permissions for the replication to take place.

{ "Version":"2012-10-17", "Id":"", "Statement":[ { "Sid":"Set permissions for objects", "Effect":"Allow", "Principal":{ "AWS":"arn-of-role-selected-in-replication-setup-in-source-account" }, "Action":["s3:ReplicateObject", "s3:ReplicateDelete"], "s3:ObjectOwnerOverrideToBucketOwner", "Resource":"arn:aws:s3:::destination-bucket-name/*" }, { "Sid":"Set permissions on bucket", "Effect":"Allow", "Principal":{ "AWS":"arn-of-role-selected-in-replication-setup-in-source-account" }, "Action":["s3:GetBucketVersioning", "s3:PutBucketVersioning"], "Resource":"arn:aws:s3:::destination-bucket-name " }, { "Sid": "Stmt1335892150622", "Effect": "Allow", "Principal": { "Service": "billingreports.amazonaws.com" }, "Action": [ "s3:GetBucketAcl", "s3:GetBucketPolicy" ], "Resource": "arn:aws:s3:::destination-bucket-name" }, { "Sid": "Stmt1335892526596", "Effect": "Allow", "Principal": { "Service": "billingreports.amazonaws.com" }, "Action": "s3:PutObject", "Resource": "arn:aws:s3:::destination-bucket-name/*" } ] }

56 AWS Perspective Implementation Guide

Discovery process is slow

If you are importing a large number of accounts at once, the discovery process might become slow. This often happens due to API rate limiting while it tries to discover resources. We recommend that if this occurs, that you add Regions in a gradual manner allowing the discovery process to run fully on those Regions, before attempting to add more.

The number of Regions that can be added at once will depend on how many resources they contain.

57 AWS Perspective Implementation Guide Using the AWS Management Console

Uninstall the solution

To uninstall the AWS Perspective solution, use the AWS Management Console or the AWS Command Line Interface (AWS CLI).

Using the AWS Management Console

1. Sign in to the AWS CloudFormation console. 2. Select the stack with the name provided during deployment. 3. Choose Delete stack. 4. Select this solution’s installation stack: aws-perspective--. 5. Choose Delete. 6. Choose Edit termination protection, select Disabled, and choose Save. 7. Select the aws-perspective stack and choose Delete.

Using AWS Command Line Interface

Determine whether the AWS Command Line Interface (AWS CLI) is available in your environment. For installation instructions, refer to What Is the AWS Command Line Interface in the AWS CLI User Guide.

After conﬁrming that the AWS CLI is available, run the following command:

$ aws cloudformation delete-stack --stack-name aws-perspective-- $ aws cloudformation delete-stack --stack-name

58 AWS Perspective Implementation Guide

Collection of operational metrics

This solution includes an option to send anonymous operational metrics to AWS. We use this data to better understand how customers use this solution and related services and products. When activated, the following information is collected and sent to AWS:

• Solution ID: SO0075 SO0075a SO0075b SO0075c • Unique ID (UUID): Randomly generated, unique identiﬁer for each AWS Perspective deployment • Timestamp: Data-collection timestamp • Login Attempts: Increments on each log in and is sent back anonymously • Instance Data: Count of the state and type of instances that are managed by the EC2 Scheduler in each AWS Region

Example data:

Running: {t2.micro: 2}, {m3.large:2} Stopped: {t2.large: 1}, {m3.xlarge:3}

AWS owns the data gathered though this survey. Data collection is subject to the AWS Privacy Policy. To opt out of this feature, ensure that you deploy the aws-perspective.template with the OptOutOfSendingAnonymousUsageMetrics set to Yes and complete the following task.

Modify the AWS CloudFormation template mapping section from:

“Send” : { “AnonymousUsage” : { “Data” : “Yes” } },

to:

“Send” : { “AnonymousUsage” : { “Data” : “No" } },

59 AWS Perspective Implementation Guide

Source code

Visit the AWS Pespective GitHub repository to download the templates and scripts for this solution, and to share your customizations with others.

60 AWS Perspective Implementation Guide

Contributors

The following individuals contributed to this document:

• Mohsan Jaﬀery • Matthew Ball • Stefano Vozza • Connor Kirkpatrick

61 AWS Perspective Implementation Guide

Revisions

Date Change

September 2020 Initial release

September 2020 Release v1.0.1: bug ﬁxes. For more information, refer to the CHANGELOG.md ﬁle in the GitHub repository.

August 2021 Release v1.1.0: new features and bug ﬁxes. For more information, refer to the CHANGELOG.md ﬁle in the GitHub repository.

62 AWS Perspective Implementation Guide

Notices

Customers are responsible for making their own independent assessment of the information in this document. This document: (a) is for informational purposes only, (b) represents current AWS product oﬀerings and practices, which are subject to change without notice, and (c) does not create any commitments or assurances from AWS and its aﬃliates, suppliers or licensors. AWS products or services are provided “as is” without warranties, representations, or conditions of any kind, whether express or implied. The responsibilities and liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

The AWS Perspective solution is licensed under the terms of the Apache License Version 2.0 available at The Apache Software Foundation.