arc-region-switch

Files (3)

• SKILL.md
• doc-links.md · references/
• positioning.md · references/

SKILL.md (first lines)

# ARC Region switch Expert

## Overview

Makes the agent an expert on **Amazon Application Recovery Controller (ARC) Region switch** — the feature for orchestrating cross-Region workload failover and switchover. Supports technical questions, customer positioning, and SA engagement preparation.

Region switch orchestrates recovery for applications already deployed multi-Region. It does not create multi-Region architecture or handle data replication — it orchestrates failover of existing replicas and resources.

## Guardrail — where this skill's own files live (MCP vs local install)

Before reading a reference file, determine how this skill was loaded:

- **Loaded via the AWS MCP `retrieve_skill` tool:** the skill's reference files are not on the local filesystem. Fetch each one through `retrieve_skill` with the `file` parameter (e.g. `file="references/positioning.md"` or `file="references/doc-links.md"`) — do NOT `file_read` these paths locally or search the filesystem for them.
- **Installed locally** (e.g. `.kiro/skills/arc-region-switch/` or `~/.claude/skills/arc-region-switch/`): read reference files from the local skill directory using the relative paths shown here.

This applies only to the skill's own reference files; always read and write user or session data in the working directory, never through `retrieve_skill`.

## When Not to Use

- **In-Region failover** — Region switch is for cross-Region recovery only. Use AZ-level mechanisms (ALB, Auto Scaling) for in-Region resilience.
- **Data replication design** — Region switch orchestrates failover of existing replicas; it does not set up or manage replication. Use Aurora Global Database, DynamoDB Global Tables, S3 Cross-Region Replication, etc.
- **AZ-level resiliency** — For Availability Zone failures within a single Region, use multi-AZ architecture patterns instead.

## Terminology Constraints

- ALWAYS use "Region switch" (lowercase 's') for the product name
- Use "Routing Controls" only when referring to the Routing Controls execution block or the legacy cluster-based approach — do not use it as a synonym for Region switch
- Do NOT conflate **triggers** (CloudWatch alarms that start execution) with **application health alarms** (measure actual recovery time)
- Region switch orchestrates failover — it does NOT replicate data

## Critical Warnings

- **Irreversible in-progress steps**: Plan executions can be paused or cancelled, but any step that is already started cannot be reversed without another plan execution.
- **Monitor during events**: Customers should still monitor their application health during an event, even if they configure plan triggers to automatically start a plan execution.
- **Regional endpoint matters**: When deactivating a Region, call `start-plan-execution` from the healthy Region, not the Region being deactivated. When activating a Region, call from the Region being activated. See [StartPlanExecution API](https://docs.aws.amazon.com/arc-region-switch/latest/api/API_StartPlanExecution.html).

## Workflow

1. Classify the question: technical architecture, customer positioning, how-to, troubleshooting, or comparison
2. Answer from embedded knowledge in this skill
3. If the knowledge base is insufficient, search official AWS documentation (`docs.aws.amazon.com`)
4. Format the response for the audience (engineer, SA, customer)

Always validate:

- Correct terminology (Region switch, not routing controls for plan-based features)
- Include doc links where helpful (see Documentation Links section)
- Use positioning language from the Positioning section

## Architecture

### Components

| Component | Description |
|-----------|-------------|
| **Plan** | Top-level resource scoped to a multi-Region application. Contains workflows. |
| **Child Plan** | A self-contained plan nested within a parent plan (one level deep). |
| **Workflow** | Ordered sequence of steps within a plan. Defines activation/deactivation logic. |
| **Step** | Container for one or more execution blocks, run in parallel or sequence. |
| **Execution Block** | Performs a specific recovery action (e.g., scale up, reroute traffic, failover DB). |
| **Trigger** | CloudWatch alarm-based automation that initiates plan execution. |
| **Application Health Alarms** | CloudWatch alarms indicating app health per Region; used to calculate actual recovery time. |
| **Post-recovery Workflow** | Optional workflow that runs after recovery to prepare for future events. |
| **Plan Evaluation** | Automated checks verifying plan execution readiness. Verifies IAM permissions, resource existence and configuration, capacity, etc. |
| **Automatic Execution Reports** | PDF reports delivered to S3 after each plan execution for compliance/audit. |

### Execution Modes

Recommend using graceful execution unless not possible (e.g., when an execution block has a dependency on the impaired Region — such as Aurora/DocumentDB/Neptune switchover requiring connectivity to the impaired Region, or a Custom Action Lambda deployed in the impaired Region).

- **Graceful**: Runs all steps in orderly sequence. Preferred for planned switchovers, DR tests, and any scenario where the source Region is still healthy.
- **Ungraceful**: Skips or modifies certain execution blocks — only critical steps run. Use only when the source Region is impaired and graceful execution is not possible.
- **Post-recovery**: Runs after successful recovery in the previously-impaired Region. Requires both Regions to be healthy. Supports a subset of execution blocks — see the [Add execution blocks](https://docs.aws.amazon.com/r53recovery/latest/dg/working-with-rs-execution-blocks.html) documentation for the current set.

### Active/Passive vs Active/Active

| Approach | Workflows Needed | Behavior |
|----------|-----------------|----------|
| **Active/Passive** | 1 activation workflow (either Region) OR 2 separate activation workflows (one per Region) | Failover from primary to standby; failback when primary recovers |
| **Active/Active** | 1 activation workflow + 1 deactivation workflow per Region | Shift-away from impaired Region + return when healthy |

### Supported Execution Blocks

Execution blocks are the individual step types a Region switch workflow is composed of — each performs one recovery action, spanning traffic/DNS rerouting, compute scaling, database failover, custom-action Lambdas, manual-approval gates, and nested child plans.

**Do not rely on a hardcoded list of block types** — ARC adds and changes execution blocks over time. Retrieve the current supported set at query time from the [Components & concepts](https://docs.aws.amazon.com/r53recovery/latest/dg/components-rs.html) and [Add execution blocks](https://docs.aws.amazon.com/r53recovery/latest/dg/working-with-rs-execution-blocks.html) documentation.

### Recovery Time Tracking

- **Recovery Time Objective (RTO)**: Set when creating a plan
- **Actual Recovery Time**: Plan execution time + time for application health alarms to return to green
- Visible on plan execution details page for comparison against RTO

### Plan Evaluation

- Validates: IAM permissions, resource configurations, running capacity
- Warnings surfaced in console, EventBridge, and API
- Passing evaluation alone is NOT sufficient — always test by executing plans

### Automatic Execution Reports

- PDF reports generated after each plan execution
- Delivered to customer-specified S3 bucket (within ~30 min)
- Customers must configure the S3 bucket and update permissions for the PlanExecutionRole to enable reporting
- Contents: executive summary, plan config, execution timeline, resource states, alarm history, child plan details, glossary
- Useful for regulatory compliance and DR audit evidence
- See Security Considerations for encryption and access control guidance

## Cross-Account Support

Plans can orchestrate resources across multiple AWS accounts via IAM roles with cross-account trust policies. This is a key enterprise differentiator — always mention it for large customers.

When configuring cross-account trust policies:

- Include condition keys (`aws:SourceArn`, `aws:SourceAccount`, `sts:ExternalId`) to prevent confused deputy attacks
- Scope IAM policies to least privilege — avoid `*` resource wildcards and `FullAccess` managed policies
- Scope permissions to only the specific resources (ASG ARNs, Aurora cluster ARNs, Route 53 health check ARNs, etc.) referenced in execution blocks

## Regional Availability

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws