Analysis: AWS Analyze

Analysis: AWS Analyze

#340460

Description

The /analysis/cloud/aws/analyze resource is used to collect AWS CloudWatch data and initiate optimization analysis with the cloud infrastructure collected. Below are the series of processes that occur when the initial /analysis/cloud/aws/analyze request is triggered:

  • set up and initiate data collection of the AWS account and schedule it to run automatically on a nightly basis;
    • the first data collection will collect up to 60 days of data, if available;
    • subsequent data collection will collect the last day's data, if available;
  • initiate analysis on the data collected using the default policy;
    • subsequent analysis is scheduled to run on a nightly basis after data collection;
    • you have the option to override the default policy used during an analysis (see GET /analysis/cloud/aws/policy for a list of available AWS policies);
    • you have the option to configure a webhook URI, where the results will be sent upon analysis completion (see Add webhook to an analysis for details).

While data collection or analysis is in progress, you can check for status (using /analysis/cloud/aws/<analysisId>/status resource) or wait for the results to be published to an optional webhook URI.

The reporting database update is typically scheduled to run automatically on a nightly basis after data collection and analysis. This scheduled job produces reports for each instance recommendation, which is useful for network analysts or application owners. These application owner reports are created on a nightly basis after the scheduled analysis, therefore, they are only available on the following day for a new analysis.

You can make an ad-hoc /analysis/cloud/aws/analyze request for an existing analysis, outside of the scheduled nightly runs. This manual ad-hoc analysis request does not perform data collection or reporting database updates. It simply runs the analysis on the existing data collected with the following behavior:

  • If a new policy is provided, the analysis will use the updated policy. If no policy is provided, the analysis will use the existing policy already configured for the analysis.
  • If a new webhook is provided, the analysis will send results to the new webhook URI. If no webhook is provided, the analysis will send results to the existing webhook configured.
  • If the same analysis is already running, the request does not proceed and an appropriate message is returned.
  • If the same analysis has data collection scheduled within 30 minutes, the request does not proceed and an appropriate message is returned. For example, if data collection is scheduled to run at 12:05 AM, and you initiate a manual ad-hoc analyze request at 11:45 PM, then the analysis will not proceed and an error message is returned.

Before you can collect AWS CloudWatch data, you need to create an IAM role for Densify to have a trust relationship with your AWS account that contains data. See AWS Data Collection Prerequisites for an IAM Role for details on how to set up the IAM role for data collection.

Resource

/analysis/cloud/aws/analyze

Supported Operations

Table: AWS Analyze Supported Operations

Operation

HTTP Method

Input

Output

Description

Run AWS data collection and analysis

POST /analysis/cloud/aws/analyze

Request Body Parameter:

This resource operation is used to:

  1. Collect AWS cloud data connected via IAM role access.
  2. Run analysis on AWS cloud data collected.
  3. (Optional) Send results to webhook receiving application.
  4. Schedule data collection and analysis processes each night subsequent to the initial request.

Example: Running AWS Data Collection and Analysis

RE-run AWS data analysis

POST /analysis/cloud/aws/analyze

Request Body Parameter:

This resource operation is used to re-run an analysis that already exists.

You can specify an updated policy and/or webhook to use for the analysis ad-hoc re-run. Keep in mind that data collection only occurs during the first /analyze request, and is subsequently scheduled to run nightly.

The updated policy or webhook is saved and will be used in future scheduled analyses.

If you initiate an analysis re-run request when data collection and analysis is already running or within 30 minutes from running, then the request will fail and an appropriate error message is returned.

Update AWS credentials

PUT /analysis/cloud/aws/ <analysisId>

Path Parameter:

Request Body Parameter:

This resource operation is used to update AWS account's IAM role ARN and External ID for the next scheduled analysis.

Specify the updated roleArnName and roleExternalId in the request body.

Example: Updating AWS Credentials

Update AWS policy

PUT /analysis/cloud/aws/ <analysisId>

Path Parameter:

Request Body Parameter:

This resource operation, with a policyInstanceId in the request body, is used to update the policy used in the next scheduled AWS Analysis.

Example: Updating AWS Policy

Note : The current policy used in an analysis is exposed in the output of the analysis recommendation results.

Update AWS credentials and policy

PUT /analysis/cloud/aws/ <analysisId>

Path Parameter:

Request Body Parameter:

This resource operation is used to update AWS account's IAM role ARN, External ID, and the policy used in the next scheduled Analysis.

Example: Updating AWS Credentials and Policy

Parameters

Path Parameters

Table: AWS Analysis Path Parameters

Parameter Name

Type

Description

analysisId

string

The unique referenced ID of the AWS analysis.

Request Body Parameters

Table: AWS Analysis Request Body Parameters

Parameter Name

Type

Description

accountId

string

The AWS account ID with the CloudWatch data to collect.

See AWS Data Collection Prerequisites for an IAM Role for details on setting up the IAM role for your AWS account.

roleArnName

string

The Amazon Resource Name (ARN) for the IAM role that you created in AWS to collect data.

See AWS Data Collection Prerequisites for an IAM Role for details on setting up the ARN.

To update the ARN, refer to Update AWS credentials.

roleExternalId

string

The external ID specified for Densify when the IAM role was created.

See AWS Data Collection Prerequisites for an IAM Role for details on setting up the external ID for the IAM role.

To update the external ID, refer to Update AWS credentials.

policyInstanceId

(optional)

string

The cloud policy used for optimization analysis.

This parameter is optional and used to override the default policy for AWS cloud analysis. See GET /analysis/cloud/aws/policy.

webHook

(optional)

  • uri
  • authType
  • authValue

The webhook definition to an external application.

Optimization results are sent to the webhook-defined application when analysis is complete. See Parameters for details of each parameter in the webhook definition.

Response

Table: AWS Analysis Response Schema

Element

Type

Filter/Sort

Description

href

string

 

The referenced resource to the analysis entity.

See Analysis: Entity for details of the analysis entity resource.

When a new analysis is requested from the /analyze resource, the entity ID will not be available until after data collection completes and the analysis entity is created.

message

string

 

The message for the status response is returned.

status

number

 

The HTTP response code of the request. Possible status values include:

  • 200—success with request;
  • 400—invalid parameters;
  • 401—authentication failed;
  • 404—resource not found;
  • 500—internal server error.

Examples

Example: Running AWS Data Collection and Analysis

The following example shows you how to initiate AWS data collection and analysis, and send the results to a WebHook.

Example: Updating AWS Credentials

The following example shows you how to update your AWS account's IAM role ARN and External ID.

Example: Updating AWS Policy

The following example shows you how to update the policy used in your AWS analysis. The new policy will be used in the next scheduled analysis. To obtain the policy instance ID (i.e. policyInstanceId), refer to the Analysis: Policy resource.

Example: Updating AWS Credentials and Policy

The following example shows you how to update both the AWS credentials and policy in your analysis, at the same time. The new credentials and policy will be used in the next scheduled analysis.