Get started with routing control by using the AWS CLI - Amazon Route 53 Application Recovery Controller

Get started with routing control by using the AWS CLI

With routing control in Amazon Route 53 Application Recovery Controller, you can trigger traffic failovers between redundant application copies, or replicas, that are running in separate AWS Regions or Availability Zones.

You can organize routing controls into groups called control panels that are provisioned on a cluster. A Route 53 ARC cluster is a Regional set of endpoints that is globally deployed. Cluster endpoints provide a highly available API that you can use to set and retrieve routing control states. For more information about the components of the routing control feature, see Routing control components .

Our first step is to create a cluster. A Route 53 ARC cluster is a set of five Regional endpoints that are deployed in a global distribution. The infrastructure in Route 53 ARC supports these endpoints to work in coordination to provide a guarantee of high availability and sequential consistency of failover operations.

Note

Route 53 ARC is a global service that supports endpoints in multiple AWS Regions but you must specify the US West (Oregon) Region (that is, specify the parameter --region us-west-2) in most Route 53 ARC CLI commands. For example, to create resources such as recovery groups, readiness checks, or clusters.

When you create a cluster, Route 53 ARC provides you with a set of Regional endpoints. To get or update routing control states, you must specify the Regional endpoint (the AWS Region and the endpoint URL) in your CLI command.

For more information about using the AWS CLI, see the AWS CLI Command Reference. For more information about Route 53 ARC API actions, see the Recovery Control Configuration API Reference for Amazon Route 53 Application Recovery Controller.

1. Create a cluster

1a. Create a cluster.

aws route53-recovery-control-config --region us-west-2 create-cluster --cluster-name NewCluster
{ "Cluster": { "ClusterArn": "arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh", "Name": "NewCluster", "Status": "PENDING" } }

When you first create a Route 53 ARC object, it has a status of PENDING while the cluster is created. You can check in on its progress by calling describe-cluster.

1b. Describe a cluster.

aws route53-recovery-control-config --region us-west-2 \ describe-cluster --cluster-arn arn:aws:route53-recovery-control:: 111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh
{ "Cluster":{ "ClusterArn": "arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh", "ClusterEndpoints":[ {"Endpoint": "https://host-aaaaaa.us-east-1.example.com", "Region":"us-east-1"}, {"Endpoint": "https://host-bbbbbb.ap-southeast-2.example.com", "Region":"ap-southeast-2"}, {"Endpoint": "https://host-cccccc.eu-west-1.example.com", "Region":"eu-west-1"}, {"Endpoint": "https://host-dddddd.us-west-2.example.com", "Region":"us-west-2"}, {"Endpoint": "https://host-eeeeee.ap-northeast-1.example.com", "Region":"ap-northeast-1"} ] "Name": "NewCluster", "Status": "DEPLOYED" } }

When the status is DEPLOYED, Route 53 ARC has successfully created the cluster with the set of endpoints for you to interact with. You can list all of your clusters by calling list-clusters.

1c. List your clusters.

aws route53-recovery-control-config --region us-west-2 list-clusters
{ "Clusters": [ { "ClusterArn": "arn:aws:route53-recovery-control::111122223333:cluster/1234abcd-abcd-1234-abcd-1234abcdefgh", "ClusterEndpoints":[ {"Endpoint": "https://host-aaaaaa.us-east-1.example.com", "Region":"us-east-1"}, {"Endpoint": "https://host-bbbbbb.ap-southeast-2.example.com", "Region":"ap-southeast-2"}, {"Endpoint": "https://host-cccccc.eu-west-1.example.com", "Region":"eu-west-1"}, {"Endpoint": "https://host-dddddd.us-west-2.example.com", "Region":"us-west-2"}, {"Endpoint": "https://host-eeeeee.ap-northeast-1.example.com", "Region":"ap-northeast-1"} ], "Name": "AnotherCluster", "Status": "DEPLOYED" }, { "ClusterArn": "arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh", "ClusterEndpoints": [ {"Endpoint": "https://host-ffffff.us-east-1.example.com", "Region":"us-east-1"}, {"Endpoint": "https://host-gggggg.ap-southeast-2.example.com", "Region":"ap-southeast-2"}, {"Endpoint": "https://host-hhhhhh.eu-west-1.example.com", "Region":"eu-west-1"}, {"Endpoint": "https://host-iiiiii.us-west-2.example.com", "Region":"us-west-2"}, {"Endpoint": "https://host-jjjjjj.ap-northeast-1.example.com", "Region":"ap-northeast-1"} ], "Name": "NewCluster", "Status": "DEPLOYED" } ] }

2. Create a control panel

A control panel is a logical grouping for organizing your Route 53 ARC routing controls. When you create a cluster, Route 53 ARC automatically provides a control panel for you called DefaultControlPanel. You can use this control panel right away.

A control panel can only exist in one cluster. If you want to move a control panel to another cluster, you must delete it and then create it in the second cluster. You can see all of the control panels in your account by calling list-control-panels. To see just the control panels in a specific cluster, add the --cluster-arn field.

2a. List control panels.

aws route53-recovery-control-config --region us-west-2 \ list-control-panels --cluster-arn arn:aws:route53-recovery-control::111122223333:cluster/eba23304-1a51-4674-ae32-b4cf06070bdd
{ "ControlPanels": [ { "ControlPanelArn": "arn:aws:route53-recovery-control::111122223333:controlpanel/1234567dddddd1234567dddddd1234567", "ClusterArn": "arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh", "DefaultControlPanel": true, "Name": "DefaultControlPanel", "RoutingControlCount": 0, "Status": "DEPLOYED" } ] }

Optionally, create your own control panel by calling create-control-panel.

2b. Create a control panel.

aws route53-recovery-control-config --region us-west-2 --control-panel-name NewControlPanel2 \ --cluster-arn arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh
{ "ControlPanel": { "ControlPanelArn": "arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456", "ClusterArn": "arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh", "DefaultControlPanel": false, "Name": "NewControlPanel2", "RoutingControlCount": 0, "Status": "PENDING" } }

When you first create a Route 53 ARC resource, it has a status of PENDING while it's being created. You can check on progress by calling describe-control-panel.

2c. Describe a control panel.

aws route53-recovery-control-config --region us-west-2 describe-control-panel \ --control-panel-arn arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456
{ "ControlPanel": { "ControlPanelArn": "arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456", "ClusterArn": "arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh", "DefaultControlPanel": true, "Name": "DefaultControlPanel", "RoutingControlCount": 0, "Status": "DEPLOYED" } }

3. Create a routing control

Now that you've set up the cluster and looked at control panels, you can begin creating routing controls. When you create a routing control, at a minimum you must specify the Amazon Resource Name (ARN) of the cluster that you want the routing control to be in. You can also specify the ARN of a control panel for the routing control. You'll also need to specify the cluster where the control panel is located.

If you don't specify a control panel, your routing control is added to the automatically created control panel, DefaultControlPanel.

Create a control panel by calling create-routing-control.

3a. Create a routing control.

aws route53-recovery-control-config --region us-west-2 create-routing-control \ --routing-control-name NewRc1 \ --cluster-arn arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh
{ "RoutingControl": { "ControlPanelArn": " arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456", "Name": "NewRc1", "RoutingControlArn": "arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/abcdefg1234567", "Status": "PENDING" } }

Routing controls follow the same creation pattern as other Route 53 ARC resources, so you can track their progress by calling a describe operation.

3b. Describe routing control.

aws route53-recovery-control-config --region us-west-2 describe-routing-control \ --routing-control-arn arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/abcdefg1234567
{ "RoutingControl": { "ControlPanelArn": "arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456", "Name": "NewRc1", "RoutingControlArn": "arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/ abcdefg1234567", "Status": "DEPLOYED" } }

You can list the routing controls in a control panel by calling list-routing-controls. The control panel ARN is required.

3c. List routing controls.

aws route53-recovery-control-config --region us-west-2 list-routing-controls \ --control-panel-arn arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456
{ "RoutingControls": [ { "ControlPanelArn": "arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456", "Name": "Rc1", "RoutingControlArn": "arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/ abcdefg1234567", "Status": "DEPLOYED" }, { "ControlPanelArn": "arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456", "Name": "Rc2", "RoutingControlArn": "arn:aws:route53-recovery-control:: 111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/hijklmnop987654321", "Status": "DEPLOYED" } ] }

In the following example, where we work with routing control states, we assume that you have the two routing controls listed in this section (Rc1 and Rc2). In this example, each routing control represents an Availability Zone that your application is deployed in.

4. Create safety rules

When you work with several routing controls at the same time, you might decide that you want some safeguards in place when you enable and disable them, to avoid unintentional consequences, like turning both routing controls off and stopping all traffic flow. To create these safeguards, you create Route 53 ARC safety rules.

There are two types of safety rules: assertion rules and gating rules. To learn more about safety rules, see Creating safety rules in Route 53 ARC .

The following call provides an example of creating an assertion rule that makes sure that at least one of two routing controls is set to On at any given time. To create the rule, you run create-safety-rule with the assertion-rule parameter.

For detailed information about the assertion rule API operation, see AssertionRule in the Routing Control API Reference Guide for Amazon Route 53 Application Recovery Controller.

4a. Create an assertion rule.

aws route53-recovery-control-config --region us-west-2 create-safety-rule \ --assertion-rule '{"Name": "TestAssertionRule", "ControlPanelArn": "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx", "WaitPeriodMs": 5000, "AssertedControls": ["arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/def123def123def", "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/ghi456ghi456ghi"], "RuleConfig": {"Threshold": 1, "Type": "ATLEAST", "Inverted": false}}'
{ "Rule": { "ASSERTION": { "Arn": "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/safetyrule/333333444444", "AssertedControls": [ "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/def123def123def", "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/ghi456ghi456ghi"], "ControlPanelArn": "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx", "Name": "TestAssertionRule", "RuleConfig": { "Inverted": false, "Threshold": 1, "Type": "ATLEAST" }, "Status": "PENDING", "WaitPeriodMs": 5000 } } }

The following call provides an example of creating a gating rule that provides a overall "on/off" or "gating" switch for a set of target routing controls in a control panel. This lets you disallow updating the target routing controls so that, for example, automation can't make unauthorized updates. In this example, the gating switch is a routing control specified by the GatingControls parameter and the two routing controls that are controlled or "gated" are specified by the TargetControls parameter.

Note

Before you create the gating rule, you must create the gating routing control, which does not include DNS failover records, and the target routing controls, which you do configure with DNS failover records.

To create the rule, you run create-safety-rule with the gating-rule parameter.

For detailed information about the assertion rule API operation, see GatingRule in the Routing Control API Reference Guide for Amazon Route 53 Application Recovery Controller.

4b. Create a gating rule.

aws route53-recovery-control-config --region us-west-2 create-safety-rule \ --gating-rule '{"Name": "TestGatingRule", "ControlPanelArn": "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx", "WaitPeriodMs": 5000, "GatingControls": ["arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/def123def123def"], "TargetControls": ["arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/ghi456ghi456ghi", "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/lmn789lmn789lmn"], "RuleConfig": {"Threshold": 0, "Type": "OR", "Inverted": false}}'
{ "Rule": { "GATING": { "Arn": "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/safetyrule/444444444444", "GatingControls": [ "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/def123def123def" ], "TargetControls": [ "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/ghi456ghi456ghi", "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx/routingcontrol/lmn789lmn789lmn" ], "ControlPanelArn": "arn:aws:route53-recovery-control::888888888888:controlpanel/zzz123yyy456xxx789zzz123yyy456xxx", "Name": "TestGatingRule", "RuleConfig": { "Inverted": false, "Threshold": 0, "Type": "OR" }, "Status": "PENDING", "WaitPeriodMs": 5000 } } }

As with other Route 53 ARC resources, you can describe, list, or delete safety rules after they propagate to the data plane.

After you set up one or more safety rules, you can continue to interact with the cluster, to set or retrieve state for routing controls. If a set-routing-control-state operation breaks a rule that you created, you’ll receive an exception similar to the following:

Cannot modify control state for [0123456bbbbbbb0123456bbbbbb01234560123 abcdefg1234567] due to failed rule evaluation 0123456bbbbbbb0123456bbbbbb0123456333333444444

The first identifier is the control panel ARN concatenated with the routing control ARN. The second identifier is the control panel ARN concatenated with the safety rule ARN.

5. Create health checks

To use routing controls to fail over traffic, you create health checks in Amazon Route 53, and associate the health checks with your DNS records. As an example, let's say you have two cells, one that you've configured as the primary cell for your application, and the other that you've configured as the secondary, to fail over to.

To set up health checks for failover, do the following:

  1. Use the Route 53 ARC CLI to create a routing control for each cell.

  2. Use the Route 53 CLI to create a Route 53 ARC health check in Route 53 for each routing control.

  3. Use the Route 53 CLI to create two failover DNS records in Route 53, and associate a health check with each one.

5a. Create a routing control for each cell.

aws route53-recovery-control-config --region us-west-2 create-routing-control \ --routing-control-name RoutingControlCell1 \ --cluster-arn arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh
aws route53-recovery-control-config --region us-west-2 create-routing-control \ --routing-control-name RoutingControlCell2 \ --cluster-arn arn:aws:route53-recovery-control::111122223333:cluster/5678abcd-abcd-5678-abcd-5678abcdefgh

5b. Create a health check for each routing control.

Note

You create Route 53 ARC health checks by using the Amazon Route 53 CLI.

aws route53 create-health-check --caller-reference RoutingControlCell1 \ --health-check-config \ Type=RECOVERY_CONTROL,RoutingControlArn=arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/abcdefg1234567
{ "Location": "https://route53.amazonaws.com/2015-01-01/healthcheck/11111aaaa-bbbb-cccc-dddd-ffffff22222", "HealthCheck": { "Id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "CallerReference": "RoutingControlCell1", "HealthCheckConfig": { "Type": "RECOVERY_CONTROL", "Inverted": false, "Disabled": false, "RoutingControlArn": "arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/abcdefg1234567" }, "HealthCheckVersion": 1 } }
aws route53 create-health-check --caller-reference RoutingControlCell2 \ --health-check-config \ Type=RECOVERY_CONTROL,RoutingControlArn=arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/abcdefg1234567
{ "Location": "https://route53.amazonaws.com/2015-01-01/healthcheck/11111aaaa-bbbb-cccc-dddd-ffffff22222", "HealthCheck": { "Id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "CallerReference": "RoutingControlCell2", "HealthCheckConfig": { "Type": "RECOVERY_CONTROL", "Inverted": false, "Disabled": false, "RoutingControlArn": "arn:aws:route53-recovery-control::111122223333:controlpanel/0123456bbbbbbb0123456bbbbbb0123456/routingcontrol/abcdefg1234567" }, "HealthCheckVersion": 1 } }

5c. Create two failover DNS records, and associate a health check with each one.

You create failover DNS records in Route 53 using the Route 53 CLI. To create the records, follow the directions in the Amazon Route 53 AWS CLI Command Reference for the change-resource-record-sets command. In the records, specify the DNS value for each cell together with the corresponding HealthCheckID value that Route 53 created for the health check (see 6b).

For the primary cell:

{ "Name": "myapp.yourdomain.com", "Type": "CNAME", "SetIdentifier": "primary", "Failover": "PRIMARY", "TTL": 0, "ResourceRecords": [ { "Value": "cell1.yourdomain.com" } ], "HealthCheckId": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

For the secondary cell:

{ "Name": "myapp.yourdomain.com", "Type": "CNAME", "SetIdentifier": "secondary", "Failover": "SECONDARY", "TTL": 0, "ResourceRecords": [ { "Value": "cell2.yourdomain.com" } ], "HealthCheckId": "yyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" }

Now, to fail over from your primary cell to your secondary cell, you can follow the CLI example in Step 4b to update the state of RoutingControlCell1 to OFF and RoutingControlCell2 to ON.