Assessments - Amazon Managed Streaming for Apache Kafka
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Assessments

Assessments scan a cluster for readiness before you change it. An assessment of type UPDATE_BROKER_TYPE reports every condition that would block or complicate an in-place upgrade from Standard brokers to Express brokers, so that you can resolve the conditions before you call UpdateBrokerType.

URI

/v1/clusters/clusterArn/assessments

HTTP methods

GET

Operation ID: ListAssessments

Returns the assessments for a cluster, newest first. Filter by assessmentType to narrow the list.

Path parameters
NameTypeRequiredDescription
clusterArnStringTrue

The Amazon Resource Name (ARN) that uniquely identifies the cluster.

Query parameters
NameTypeRequiredDescription
assessmentTypeStringFalse

Optional filter. The type of assessment to filter by.

maxResultsStringFalse

The maximum number of assessments to return in the response. The default is 25 and the maximum is 100. If there are more results, the response includes a NextToken parameter.

nextTokenStringFalse

The paginated results marker. When the result of the operation is truncated, the call returns NextToken in the response. To get the next batch, provide this token in your next request.

Responses
Status codeResponse modelDescription
200ListAssessmentsResponse

Successful response.

400Error

The request isn't valid because the input is incorrect. Correct your input and then submit it again.

401Error

The request is not authorized. The provided credentials couldn't be validated.

403Error

Access forbidden. Check your credentials and then retry your request.

404Error

The resource could not be found due to incorrect input. Correct the input, then retry the request.

429Error

429 response

500Error

There was an unexpected internal server error. Retrying your request might resolve the issue.

503Error

503 response

POST

Operation ID: CreateAssessment

Creates an assessment for a cluster and starts an asynchronous, read-only scan. The operation returns as soon as the scan starts; poll DescribeAssessment for the result and call ListAssessmentFindings once the status is COMPLETE.

A cluster can have only one assessment of a given type in progress at a time. If one is already in progress, this operation returns that assessment rather than creating another. When the cluster has reached its assessment quota, the operation fails; delete a completed or failed assessment to free a slot.

The scan does not lock the cluster and does not change it.

Path parameters
NameTypeRequiredDescription
clusterArnStringTrue

The Amazon Resource Name (ARN) that uniquely identifies the cluster.

Responses
Status codeResponse modelDescription
200CreateAssessmentResponse

Successful response.

400Error

The request isn't valid because the input is incorrect. Correct your input and then submit it again.

401Error

The request is not authorized. The provided credentials couldn't be validated.

403Error

Access forbidden. Check your credentials and then retry your request.

404Error

The resource could not be found due to incorrect input. Correct the input, then retry the request.

409Error

An assessment of the same type is already in progress for this cluster. Wait for it to complete, or read it with DescribeAssessment.

429Error

The cluster has reached its assessment quota. Delete a completed or failed assessment for this cluster, then retry your request.

500Error

There was an unexpected internal server error. Retrying your request might resolve the issue.

503Error

503 response

OPTIONS

Enable CORS by returning correct headers

Path parameters
NameTypeRequiredDescription
clusterArnStringTrue

The Amazon Resource Name (ARN) that uniquely identifies the cluster.

Responses
Status codeResponse modelDescription
200None

Default response for CORS method

Schemas

Request bodies

{ "assessmentType": enum, "assessmentParameters": { "targetBrokerType": "string", "targetInstanceType": "string" }, "tags": { } }

Response bodies

{ "assessments": [ { "assessmentArn": "string", "clusterArn": "string", "assessmentType": enum, "status": enum, "creationTime": "string", "tags": { } } ], "nextToken": "string" }
{ "assessmentArn": "string", "clusterArn": "string", "assessmentType": enum, "status": enum, "creationTime": "string" }
{ "message": "string", "invalidParameter": "string" }

Properties

AssessmentInfo

Summary information about an assessment, returned by ListAssessments.

PropertyTypeRequiredDescription
assessmentArn

string

MaxLength: 2048

False

The Amazon Resource Name (ARN) of the assessment.

assessmentType

AssessmentType

False

The type of assessment.

clusterArn

string

MaxLength: 2048

False

The Amazon Resource Name (ARN) of the cluster that was assessed.

creationTime

string

False

The time when the assessment was created.

status

AssessmentStatus

False

The current status of the assessment.

tags

object

False

The tags attached to the assessment.

AssessmentParameters

Type-specific parameters for the assessment. The required fields depend on the assessmentType.

PropertyTypeRequiredDescription
targetBrokerType

string

MaxLength: 64

False

The broker type to assess readiness for. Specify EXPRESS to assess an upgrade from Standard brokers to Express brokers. This parameter is required when assessmentType is UPDATE_BROKER_TYPE.

targetInstanceType

string

MaxLength: 256

False

The specific instance type to assess readiness for, for example express.m7g.large. Omit it to have the assessment recommend an instance type instead, which it reports as a CAPACITY finding.

AssessmentStatus

The lifecycle status of the assessment. While the status is IN_PROGRESS the scan is running and no findings are available. When it reaches COMPLETE, read summary here and the individual findings through ListAssessmentFindings. FAILED means that the scan did not finish, and statusMessage explains why. DELETING means that the assessment is being deleted and its findings are being removed.

  • IN_PROGRESS

  • COMPLETE

  • FAILED

  • DELETING

AssessmentType

The type of assessment to perform.

  • UPDATE_BROKER_TYPE

CreateAssessmentRequest

Creates a new assessment for a cluster. Kicks off an asynchronous scan and returns immediately with an assessment ARN and status.

PropertyTypeRequiredDescription
assessmentParameters

AssessmentParameters

False

Type-specific parameters for the assessment. Required parameters depend on the assessmentType.

assessmentType

AssessmentType

True

The type of assessment to perform.

tags

object

False

The tags to attach to the assessment.

CreateAssessmentResponse

Returns information about the created assessment.

PropertyTypeRequiredDescription
assessmentArn

string

MaxLength: 2048

False

The Amazon Resource Name (ARN) of the assessment.

assessmentType

AssessmentType

False

The type of assessment.

clusterArn

string

MaxLength: 2048

False

The Amazon Resource Name (ARN) of the cluster being assessed.

creationTime

string

False

The time when the assessment was created.

status

AssessmentStatus

False

The current status of the assessment.

Error

Returns information about an error.

PropertyTypeRequiredDescription
invalidParameter

string

False

The parameter that caused the error.

message

string

False

The description of the error.

ListAssessmentsResponse

Returns a list of assessments.

PropertyTypeRequiredDescription
assessments

Array of type AssessmentInfo

False

A list of assessment summaries.

nextToken

string

False

If the response is truncated, it returns a nextToken. Send this in the subsequent request to get the remaining results.

See also

For more information about using this API in one of the language-specific AWS SDKs and references, see the following:

ListAssessments

CreateAssessment