Splitting Traffic With Weighted Routing

Domain expertise for splitting DNS responses across two or more endpoints in a defined ratio using weighted records: blue/green deployments, canary releases, A/B testing, and gradual cutover. Covers how weights are interpreted, how to take an endpoint out of rotation safely, health-aware routing for non-AWS targets, and the two distinct zero-weight behaviors.

Does not cover failover routing (a separate skill), latency or geolocation routing, or complex nested Traffic Flow policies.

Execute commands using the AWS MCP server when connected (sandboxed execution, audit logging, observability). Fall back to the AWS CLI otherwise.

Table of Contents

• Overview
• Workflow
• Weights are relative, not percentages
• Decision: zero-weight vs delete to stop traffic
• Health-aware routing for non-AWS endpoints
• Two zero-weight behaviors
• Troubleshooting
• Procedure
• Additional Resources

Workflow

To split traffic with weighted records, follow the procedure exactly. See the Procedure section below.

The procedure covers:

• Creating one weighted record per endpoint with the right relative weights
• Taking an endpoint out of rotation with a zero weight while keeping rollback
• Attaching health checks to non-alias weighted records
• Surfacing the console link to verify

Weights are relative, not percentages

Constraints:

• You MUST compute each record’s share as its weight divided by the sum of all weights for that name and type. Records weighted 1, 1, 2 send 25, 25, and 50 percent of queries, not 1, 1, and 2 percent. Do not let the customer read the weight as a percent value
• Each weight MUST be an integer from 0 to 255. To express a fine-grained split (for example 99.5/0.5), scale the ratio to fit within 0 to 255; a raw split wider than 255 to 1 cannot be expressed directly
• You MUST NOT create a non-weighted (simple) record with the same name and type as a weighted record. Route 53 forbids mixing the two for one name and type

Decision: zero-weight vs delete to stop traffic

Constraints:

• You SHOULD set an endpoint’s weight to zero to pull traffic while keeping rollback. Deleting the record also stops traffic but throws away instant rollback

Health-aware routing for non-AWS endpoints

Constraints:

• You MUST attach a health check explicitly to each non-alias weighted record (raw IPs, external hostnames). Evaluate Target Health works for alias records but not for non-alias targets, so without a health check an unhealthy non-AWS endpoint keeps receiving its share

Two zero-weight behaviors

A zero weight behaves in two completely different ways depending on whether all weights are zero and whether health checks are attached. Do not conflate them.

Constraints:

• You MUST warn the customer that setting every record in the group to weight 0 does NOT stop traffic. Route 53 treats all-zero as a safety net and routes to every record with equal probability. To actually take traffic off an endpoint, leave at least one other record with a nonzero weight, or delete the records. An operator zeroing every record to halt traffic during an incident will instead spread traffic evenly across all of them
• You SHOULD tell the customer that the health-based fallback is a separate mechanism: when nonzero records carry health checks, Route 53 serves only the healthy nonzero records, and falls back to zero-weighted records only if every nonzero record is unhealthy. This makes a zero-weight record a last-resort backup
• You MUST state the precondition for that fallback: it only triggers when the nonzero records have health checks attached. Without health checks, a record is always treated as eligible, so a zero-weight backup is never reached

Troubleshooting

Traffic split is not what was expected

Weights were read as percentages instead of relative shares. Recompute: each share is its weight divided by the sum of all weights.

Cannot roll back after stopping traffic

The record was deleted instead of zero-weighted. Use weight zero to pull traffic while keeping the record.

Dead non-AWS endpoint still gets traffic

No health check is attached to the non-alias record. Attach a health check to each non-alias weighted record.

Zeroing every record did not stop traffic

Expected. All-zero is a safety net: Route 53 routes to every record equally. Leave one record nonzero, or delete the records, to actually pull traffic.

Zero-weight backup never receives traffic when others fail

The nonzero records have no health checks, so Route 53 never sees them as unhealthy and never falls back. Attach health checks to the nonzero records.

Procedure

Overview

This procedure splits DNS responses across two or more endpoints in a defined ratio using weighted records. It creates one weighted record per endpoint, takes an endpoint out of rotation safely with a zero weight, attaches health checks to non-alias targets, and surfaces the console link to verify.

Parameters

• hosted_zone_id (required): The hosted zone ID.
• record_name (required): The shared record name (e.g., app.example.com).
• record_type (required): The shared record type (e.g., A).
• endpoints (required): A list of {set_identifier, target, weight} triples, one per endpoint. set_identifier is a label unique within the weighted group (for example the target value or a short name); Route 53 requires a distinct SetIdentifier per record in the group.
• health_checks (optional): Health check IDs for non-alias targets.

Constraints for parameter acquisition:

• You MUST ask for all required parameters upfront in a single prompt
• You MUST confirm the intended split ratio and translate it to relative weights with the customer

Steps

1. Verify dependencies

Constraints:

• You MUST confirm credentials with aws sts get-caller-identity
• You MUST REQUIRE provisioning credentials through ephemeral mechanisms (IAM roles via instance profiles, SSO/IAM Identity Center session credentials, or aws sts assume-role) rather than long-lived IAM user access keys.
• You MUST enable Route 53 query logging to an encrypted destination where applicable, ensure CloudTrail is enabled to audit changes, and set CloudWatch alarms on health-check status where health checks are involved.

2. Create one weighted record per endpoint

Constraints:

• You MUST create one record per endpoint with the same name and type, each with its own weight and a unique SetIdentifier:

  Copy

  aws route53 change-resource-record-sets --hosted-zone-id {hosted_zone_id} --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "{record_name}", "Type": "{record_type}",
        "SetIdentifier": "{set_identifier}", "Weight": {weight},
        "TTL": 60, "ResourceRecords": [{"Value": "{target}"}]
      }
    }]
  }'

• You MUST remind the customer that weights are relative shares, not percentages

3. Attach health checks to non-alias targets

Constraints:

• For non-alias targets (raw IPs, external hostnames), you MUST attach a HealthCheckId to each weighted record, or unhealthy endpoints keep receiving their share. Evaluate Target Health does not cover non-alias targets

4. Take an endpoint out of rotation (when needed)

Constraints:

• You SHOULD set an endpoint’s weight to zero to pull traffic while keeping the record for instant rollback, rather than deleting the record

5. Confirm and surface the console link

Constraints:

• You MUST verify the query distribution matches the intended ratio

• You MUST present the records view console link, filling {hostedZoneId}:

  Copy

  https://console.aws.amazon.com/route53/v2/hostedzones#ListRecordSets/{hostedZoneId}

Example

Example input

Example output

Troubleshooting

Traffic split is not what was expected

Weights read as percentages. Recompute: share = weight / sum of weights (Step 2).

Cannot roll back after stopping traffic

The record was deleted instead of zero-weighted. Use weight zero (Step 4).

Dead non-AWS endpoint still gets traffic

No health check on the non-alias record. Attach one to each (Step 3).

Security Considerations

• You SHOULD use least-privilege IAM credentials provisioned through ephemeral mechanisms (IAM roles, SSO/IAM Identity Center session credentials, or aws sts assume-role) rather than long-lived IAM user access keys, and prefer read-only credentials for inspection steps. Grant only the specific actions this procedure needs — route53:ChangeResourceRecordSets and route53:GetChange to create the weighted records and confirm propagation, plus route53:ListResourceRecordSets and route53:GetHostedZone for inspection — rather than route53:* or broader service:* wildcards.
• You MUST enable Route 53 query logging to an encrypted destination (KMS on CloudWatch Logs, SSE-S3/SSE-KMS on S3, or server-side encryption on a Data Firehose stream) to confirm the weighted distribution matches expectations, and ensure CloudTrail is enabled to audit record changes. This matters most for canary and blue/green cutovers, where an unexpected split can cause an outage.
• You SHOULD set CloudWatch alarms on the health-check status metrics of any health checks attached to the weighted records with an SNS notification, so an unhealthy endpoint still receiving its share is detected.
• You MUST enable KMS server-side encryption on the SNS topic used for health-check alarm notifications, because notification content can reveal endpoint and infrastructure topology.
• You MUST confirm the SNS topic’s subscription list is limited to authorized personnel.

Additional Resources

• Weighted routing (Route 53 Developer Guide) (opens in a new tab)
• Weighted routing rule (Route 53 console help panel) (opens in a new tab)