Routing Control API Reference Guide Welcome API Version 2019-12-02

(1)

Routing Control API Reference Guide

Welcome

API Version 2019-12-02

(2)

Routing Control API Reference Guide: Welcome

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.

(3)

Welcome

Welcome to the Routing Control (Recovery Cluster) API Reference Guide for Amazon Route 53 Application Recovery Controller.

With Amazon Route 53 Application Recovery Controller, you can use routing control with extreme reliability to recover applications by rerouting traffic across Availability Zones or AWS Regions. Routing controls are simple on/off switches hosted on a highly available cluster in Application Recovery Controller. A cluster provides a set of five redundant Regional endpoints against which you can run API calls to get or update the state of routing controls. To implement failover, you set one routing control on and another one off, to reroute traffic from one Availability Zone or AWS Region to another.

Be aware that you must specify the Regional endpoints for a cluster when you work with API cluster operations to get or update routing control states in Application Recovery Controller. In addition, you must specify the US West (Oregon) Region for Application Recovery Controller API calls. For example, use the parameter region us-west-2 with AWS CLI commands. For more information, see Get and update routing control states using the API in the Amazon Route 53 Application Recovery Controller Developer Guide.

This API guide includes information about the API operations for how to get and update routing control states in Application Recovery Controller. You also must set up the structures to support routing controls:

clusters and control panels.

For more information about working with routing control in Application Recovery Controller, see the following:

• To create clusters, routing controls, and control panels by using the control plane API for routing control, see the Recovery Control Conﬁguration API Reference Guide for Amazon Route 53 Application Recovery Controller.

• Learn about the components in recovery control conﬁguration, including clusters, routing controls, and control panels. For more information, see Recovery control components in the Amazon Route 53 Application Recovery Controller Developer Guide.

• Application Recovery Controller also provides readiness checks that run continually to help make sure that your applications are scaled and ready to handle failover traﬃc. For more information about the related API actions, see the Recovery Readiness API Reference Guide for Amazon Route 53 Application Recovery Controller.

• For more information about creating resilient applications and preparing for recovery readiness with Application Recovery Controller, see the Amazon Route 53 Application Recovery Controller Developer Guide.

This document was last published on March 6, 2022.

(5)

Actions

The following actions are supported:

• GetRoutingControlState (p. 3)

• UpdateRoutingControlState (p. 6)

• UpdateRoutingControlStates (p. 9)

(6)

GetRoutingControlState

Get the state for a routing control. A routing control is a simple on/off switch that you can use to route traffic to cells. When the state is On, traffic flows to a cell. When it's Off, traffic does not flow.

Before you can create a routing control, you must ﬁrst create a cluster to host the control in a control panel. For more information, see Create routing control structures in the Amazon Route 53 Application Recovery Controller Developer Guide. Then you access one of the endpoints for the cluster to get or update the routing control state to redirect traﬃc.

You must specify Regional endpoints when you work with API cluster operations to get or update routing control states in Application Recovery Controller.

To see a code example for getting a routing control state, including accessing Regional cluster endpoints in sequence, see API examples in the Amazon Route 53 Application Recovery Controller Developer Guide.

Learn more about working with routing controls in the following topics in the Amazon Route 53 Application Recovery Controller Developer Guide:

• Viewing and updating routing control states

• Working with routing controls overall

Request Syntax

{

"RoutingControlArn": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 15).

The request accepts the following data in JSON format.

RoutingControlArn (p. 3)

The Amazon Resource Name (ARN) for the routing control that you want to get the state for.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: ^[A-Za-z0-9:.\/_-]*$

Required: Yes

Response Syntax

{

"RoutingControlArn": "string", "RoutingControlState": "string"

}

(7)

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

The Amazon Resource Name (ARN) of the response.

Type: String

Pattern: ^[A-Za-z0-9:.\/_-]*$

RoutingControlState (p. 3)

The state of the routing control.

Type: String

Valid Values: On | Off

Errors

For information about the errors that are common to all actions, see Common Errors (p. 17).

AccessDeniedException

You don't have suﬃcient permissions to query the routing control state.

HTTP Status Code: 400

EndpointTemporarilyUnavailableException

The cluster endpoint isn't available. Try another cluster endpoint.

HTTP Status Code: 400 InternalServerException

There was an unexpected error during processing of the request.

HTTP Status Code: 500 ResourceNotFoundException

The request references a routing control that was not found.

HTTP Status Code: 400 ThrottlingException

The request was denied because of request throttling.

HTTP Status Code: 400 ValidationException

There was a validation error on the request.

(8)

UpdateRoutingControlState

Set the state of the routing control to reroute traffic. You can set the value to be On or Off. When the state is On, traffic flows to a cell. When it's Off, traffic does not flow.

With Application Recovery Controller, you can add safety rules for routing controls, which are safeguards for routing control state updates that help prevent unexpected outcomes, like fail open traﬃc routing.

However, there are scenarios when you might want to bypass the routing control safeguards that are enforced with safety rules that you've conﬁgured. For example, you might want to fail over quickly for disaster recovery, and one or more safety rules might be unexpectedly preventing you from updating a routing control state to reroute traﬃc. In a "break glass" scenario like this, you can override one or more safety rules to change a routing control state and fail over your application.

The SafetyRulesToOverride property enables you override one or more safety rules and update routing control states. For more information, see Override safety rules to reroute traﬃc in the Amazon Route 53 Application Recovery Controller Developer Guide.

Request Syntax

{ "RoutingControlArn": "string", "RoutingControlState": "string", "SafetyRulesToOverride": [ "string" ] }

Request Parameters

The Amazon Resource Name (ARN) for the routing control that you want to update the state for.

Type: String

Pattern: ^[A-Za-z0-9:.\/_-]*$

Required: Yes

RoutingControlState (p. 6)

The state of the routing control. You can set the value to be On or Oﬀ.

(10)

Response Elements

Type: String

Valid Values: On | Off Required: Yes

SafetyRulesToOverride (p. 6)

The Amazon Resource Names (ARNs) for the safety rules that you want to override when you're updating the state of a routing control. You can override one safety rule or multiple safety rules by including one or more ARNs, separated by commas.

For more information, see Override safety rules to reroute traﬃc in the Amazon Route 53 Application Recovery Controller Developer Guide.

Type: Array of strings

Pattern: ^[A-Za-z0-9:.\/_-]*$

Required: No

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

HTTP Status Code: 400 ConﬂictException

There was a conﬂict with this request. Try again.

(11)

UpdateRoutingControlStates

Set multiple routing control states. You can set the value for each state to be On or Off. When the state is On, traffic flows to a cell. When it's Off, traffic does not flow.

With Application Recovery Controller, you can add safety rules for routing controls, which are safeguards for routing control state updates that help prevent unexpected outcomes, like fail open traﬃc routing.

However, there are scenarios when you might want to bypass the routing control safeguards that are enforced with safety rules that you've conﬁgured. For example, you might want to fail over quickly for disaster recovery, and one or more safety rules might be unexpectedly preventing you from updating a routing control state to reroute traﬃc. In a "break glass" scenario like this, you can override one or more safety rules to change a routing control state and fail over your application.

The SafetyRulesToOverride property enables you override one or more safety rules and update routing control states. For more information, see Override safety rules to reroute traﬃc in the Amazon Route 53 Application Recovery Controller Developer Guide.

Request Syntax

{ "SafetyRulesToOverride": [ "string" ], "UpdateRoutingControlStateEntries": [ {

"RoutingControlArn": "string", "RoutingControlState": "string"

} ]}

Request Parameters

SafetyRulesToOverride (p. 9)

The Amazon Resource Names (ARNs) for the safety rules that you want to override when you're updating routing control states. You can override one safety rule or multiple safety rules by including one or more ARNs, separated by commas.

For more information, see Override safety rules to reroute traﬃc in the Amazon Route 53 Application Recovery Controller Developer Guide.

Type: Array of strings

(13)

Response Elements

Pattern: ^[A-Za-z0-9:.\/_-]*$

Required: No

UpdateRoutingControlStateEntries (p. 9)

A set of routing control entries that you want to update.

Type: Array of UpdateRoutingControlStateEntry (p. 13) objects Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

HTTP Status Code: 400 ConﬂictException

There was a conﬂict with this request. Try again.

(14)

Data Types

The Route53 Recovery Cluster API contains several data types that various actions use. This section describes each data type in detail.

Note

The order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.

The following data types are supported:

• UpdateRoutingControlStateEntry (p. 13)

• ValidationExceptionField (p. 14)

(16)

UpdateRoutingControlStateEntry

A routing control state entry.

ValidationExceptionField

Common Parameters

The following list contains the parameters that all actions use for signing Signature Version 4 requests with a query string. Any action-speciﬁc parameters are listed in the topic for that action. For more information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web Services General Reference.

Action

The action to be performed.

Type: string Required: Yes Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string Required: Yes X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256 Required: Conditional

X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:

20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing requests. If the Date header is speciﬁed in the ISO 8601 basic format, X-Amz-Date is

(19)

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS STS). For a list of services that support temporary security credentials from AWS Security Token Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you must include the security token.

Type: string

Required: Conditional X-Amz-Signature

Speciﬁes the hex-encoded signature that was calculated from the string to sign and the derived signing key.

Type: string

Required: Conditional X-Amz-SignedHeaders

Speciﬁes all the HTTP headers that were included as part of the canonical request. For more information about specifying signed headers, see Task 1: Create a Canonical Request For Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional

(20)

Common Errors

This section lists the errors common to the API actions of all AWS services. For errors speciﬁc to an API action for this service, see the topic for that API action.

You do not have suﬃcient access to perform this action.

HTTP Status Code: 400 IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400 InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500 InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400 InvalidClientTokenId

The X.509 certiﬁcate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403 InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400 InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400 InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400 MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404 MissingAction

The request is missing an action or a required parameter.

(21)

MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certiﬁcate.

HTTP Status Code: 403 MissingParameter

A required parameter for the speciﬁed action is not supplied.

HTTP Status Code: 400 NotAuthorized

You do not have permission to perform this action.

HTTP Status Code: 400 OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403 RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on the request is more than 15 minutes in the future.

HTTP Status Code: 400 ServiceUnavailable

The request has failed due to a temporary failure of the server.

The request was denied due to request throttling.

HTTP Status Code: 400 ValidationError

The input fails to satisfy the constraints speciﬁed by an AWS service.

Routing Control API Reference Guide Welcome API Version 2019-12-02

Routing Control API Reference Guide

Welcome

API Version 2019-12-02

Routing Control API Reference Guide: Welcome

Table of Contents

Welcome

Actions

GetRoutingControlState

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

UpdateRoutingControlState

Request Syntax

Request Parameters

Response Elements

Errors

See Also

UpdateRoutingControlStates

Request Syntax

Request Parameters

Response Elements

Errors

See Also

Data Types

UpdateRoutingControlStateEntry

Contents

See Also

ValidationExceptionField

Contents

See Also

Common Parameters

Common Errors