Get started with routing control by using the Amazon 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 Amazon Web Services 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 Amazon Web Services 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 Amazon Web Services Region and the endpoint URL) in your CLI command.
For more information about using the Amazon CLI, see the Amazon CLI Command Reference. For more information about recovery control configuration API actions in Route 53 ARC, see Recovery control configuration actions or the Recovery Control Configuration API Reference Guide 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 resource, 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, you must at least 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 routing control 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 an 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, you can do the following, for example:
Use the Route 53 ARC CLI to create a routing control for each cell.
Use the Route 53 CLI to create a Route 53 ARC health check in Route 53 for each routing control.
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 Amazon 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.