plans

Creates, updates, deletes, gets or lists a plans resource.

Overview

Name	plans
Type	Resource
Id	aws.arc_region_switch.plans

Fields

The following fields are returned by SELECT queries:

get_plan

Name	Datatype	Description
name	string	The name for a plan. (pattern: <code>[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,30}[a-zA-Z0-9])?</code>)
arn	string	The Amazon Resource Name (ARN) of the plan. (pattern: <code>arn:aws[a-zA-Z-]*:arc-region-switch::[0-9]{12}:plan/([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,30}[a-zA-Z0-9])?):([a-z0-9]{6})</code>)
associated_alarms	object	The associated application health alarms for a plan.
description	string	The description for a plan.
execution_role	string	The execution role for a plan. (pattern: <code>arn:aws[a-zA-Z0-9-]*:iam::[0-9]{12}:role/.+</code>)
owner	string	The owner of a plan. (pattern: <code>\d{12}</code>)
primary_region	string	The primary Region for a plan. (pattern: <code>[a-z]{2}-[a-z-]+-\d+</code>)
recovery_approach	string	The recovery approach for a Region switch plan, which can be active/active (activeActive) or active/passive (activePassive). (activeActive, activePassive)
recovery_time_objective_minutes	integer	The recovery time objective for a plan.
regions	array	The Amazon Web Services Regions for a plan.
report_configuration	object	Configuration for automatic report generation for plan executions. When configured, Region switch automatically generates a report after each plan execution that includes execution events, plan configuration, and CloudWatch alarm states.
triggers	array	The triggers for a plan.
updated_at	string (date-time)	The timestamp when the plan was last updated.
version	string	The version for the plan.
workflows	array	The workflows for a plan.

list_plans

Name	Datatype	Description
name	string	The name of a Region switch plan. (pattern: <code>[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,30}[a-zA-Z0-9])?</code>)
active_plan_execution	string	Specifies if this is the active plan execution at this time.
arn	string	The Amazon Resource Name (ARN) of the Region switch plan. (pattern: <code>arn:aws[a-zA-Z-]*:arc-region-switch::[0-9]{12}:plan/([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,30}[a-zA-Z0-9])?):([a-z0-9]{6})</code>)
description	string	The description of a Region switch plan.
execution_role	string	The execution role is a way to categorize a Region switch plan.
owner	string	The owner of a Region switch plan. (pattern: <code>\d{12}</code>)
primary_region	string	The primary Region for a plan. (pattern: <code>[a-z]{2}-[a-z-]+-\d+</code>)
recovery_approach	string	The recovery approach for a Region switch plan, which can be active/active (activeActive) or active/passive (activePassive). (activeActive, activePassive)
recovery_time_objective_minutes	integer	The recovery time objective that you've specified.
regions	array	The Amazon Web Services Region specified for a Region switch plan.
updated_at	string (date-time)	The timestamp when the plan execution was last updated.
version	string	The version for the plan.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_plan	select	region		Retrieves detailed information about a Region switch plan. You must specify the ARN of the plan.
list_plans	select	region		Lists all Region switch plans in your Amazon Web Services account.
create_plan	insert	region, workflows, executionRole, name, regions, recoveryApproach		Creates a new Region switch plan. A plan defines the steps required to shift traffic from one Amazon Web Services Region to another. You must specify a name for the plan, the primary Region, and at least one additional Region. You can also provide a description, execution role, recovery time objective, associated alarms, triggers, and workflows that define the steps to execute during a Region switch.
update_plan	update	region, arn, workflows, executionRole		Updates an existing Region switch plan. You can modify the plan's description, workflows, execution role, recovery time objective, associated alarms, and triggers.
delete_plan	delete	region		Deletes a Region switch plan. You must specify the ARN of the plan to delete. You cannot delete a plan that has an active execution in progress.
cancel_plan_execution	exec	region, planArn, executionId		Cancels an in-progress plan execution. This operation stops the execution of the plan and prevents any further steps from being processed. You must specify the plan ARN and execution ID. You can also provide an optional comment explaining why the execution was canceled.
start_plan_execution	exec	region, planArn, targetRegion, action		Starts the execution of a Region switch plan. You can execute a plan in either graceful or ungraceful mode. Specifing ungraceful mode either changes the behavior of the execution blocks in a workflow or skips specific execution blocks.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

get_plan

Retrieves detailed information about a Region switch plan. You must specify the ARN of the plan.

SELECT
name,
arn,
associated_alarms,
description,
execution_role,
owner,
primary_region,
recovery_approach,
recovery_time_objective_minutes,
regions,
report_configuration,
triggers,
updated_at,
version,
workflows
FROM aws.arc_region_switch.plans
WHERE region = '{{ region }}' -- required
;

list_plans

Lists all Region switch plans in your Amazon Web Services account.

SELECT
name,
active_plan_execution,
arn,
description,
execution_role,
owner,
primary_region,
recovery_approach,
recovery_time_objective_minutes,
regions,
updated_at,
version
FROM aws.arc_region_switch.plans
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_plan

Creates a new Region switch plan. A plan defines the steps required to shift traffic from one Amazon Web Services Region to another. You must specify a name for the plan, the primary Region, and at least one additional Region. You can also provide a description, execution role, recovery time objective, associated alarms, triggers, and workflows that define the steps to execute during a Region switch.

INSERT INTO aws.arc_region_switch.plans (
description,
workflows,
executionRole,
recoveryTimeObjectiveMinutes,
associatedAlarms,
triggers,
reportConfiguration,
name,
regions,
recoveryApproach,
primaryRegion,
tags,
region
)
SELECT 
'{{ description }}',
'{{ workflows }}' /* required */,
'{{ executionRole }}' /* required */,
{{ recoveryTimeObjectiveMinutes }},
'{{ associatedAlarms }}',
'{{ triggers }}',
'{{ reportConfiguration }}',
'{{ name }}' /* required */,
'{{ regions }}' /* required */,
'{{ recoveryApproach }}' /* required */,
'{{ primaryRegion }}',
'{{ tags }}',
'{{ region }}'
RETURNING
plan
;

Manifest

# Description fields are for documentation purposes
- name: plans
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the plans resource.
  - name: description
    value: "{{ description }}"
    description: |
      The description of a Region switch plan.
  - name: workflows
    description: |
      An array of workflows included in a Region switch plan.
    value:
      - steps: "{{ steps }}"
        workflowTargetAction: "{{ workflowTargetAction }}"
        workflowTargetRegion: "{{ workflowTargetRegion }}"
        workflowDescription: "{{ workflowDescription }}"
  - name: executionRole
    value: "{{ executionRole }}"
    description: |
      An execution role is a way to categorize a Region switch plan.
  - name: recoveryTimeObjectiveMinutes
    value: {{ recoveryTimeObjectiveMinutes }}
    description: |
      Optionally, you can specify an recovery time objective for a Region switch plan, in minutes.
  - name: associatedAlarms
    value: "{{ associatedAlarms }}"
    description: |
      The alarms associated with a Region switch plan.
  - name: triggers
    description: |
      The triggers associated with a Region switch plan.
    value:
      - description: "{{ description }}"
        targetRegion: "{{ targetRegion }}"
        action: "{{ action }}"
        conditions: "{{ conditions }}"
        minDelayMinutesBetweenExecutions: {{ minDelayMinutesBetweenExecutions }}
  - name: reportConfiguration
    description: |
      Configuration for automatic report generation for plan executions. When configured, Region switch automatically generates a report after each plan execution that includes execution events, plan configuration, and CloudWatch alarm states.
    value:
      reportOutput:
        - s3Configuration:
            bucketPath: "{{ bucketPath }}"
            bucketOwner: "{{ bucketOwner }}"
  - name: name
    value: "{{ name }}"
    description: |
      The name of a Region switch plan.
  - name: regions
    value:
      - "{{ regions }}"
    description: |
      An array that specifies the Amazon Web Services Regions for a Region switch plan. Specify two Regions.
  - name: recoveryApproach
    value: "{{ recoveryApproach }}"
    description: |
      The recovery approach for a Region switch plan, which can be active/active (activeActive) or active/passive (activePassive).
    valid_values: ['activeActive', 'activePassive']
  - name: primaryRegion
    value: "{{ primaryRegion }}"
    description: |
      The primary Amazon Web Services Region for the application. This is the Region where the application normally runs before any Region switch occurs.
  - name: tags
    value: "{{ tags }}"
    description: |
      The tags to apply to the Region switch plan.

UPDATE examples

update_plan

Updates an existing Region switch plan. You can modify the plan's description, workflows, execution role, recovery time objective, associated alarms, and triggers.

UPDATE aws.arc_region_switch.plans
SET 
arn = '{{ arn }}',
description = '{{ description }}',
workflows = '{{ workflows }}',
executionRole = '{{ executionRole }}',
recoveryTimeObjectiveMinutes = {{ recoveryTimeObjectiveMinutes }},
associatedAlarms = '{{ associatedAlarms }}',
triggers = '{{ triggers }}',
reportConfiguration = '{{ reportConfiguration }}'
WHERE 
region = '{{ region }}' --required
AND arn = '{{ arn }}' --required
AND workflows = '{{ workflows }}' --required
AND executionRole = '{{ executionRole }}' --required
RETURNING
plan;

DELETE examples

delete_plan

Deletes a Region switch plan. You must specify the ARN of the plan to delete. You cannot delete a plan that has an active execution in progress.

DELETE FROM aws.arc_region_switch.plans
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

cancel_plan_execution

Cancels an in-progress plan execution. This operation stops the execution of the plan and prevents any further steps from being processed. You must specify the plan ARN and execution ID. You can also provide an optional comment explaining why the execution was canceled.

EXEC aws.arc_region_switch.plans.cancel_plan_execution 
@region='{{ region }}' --required 
@@json=
'{
"planArn": "{{ planArn }}", 
"executionId": "{{ executionId }}", 
"comment": "{{ comment }}"
}'
;

start_plan_execution

Starts the execution of a Region switch plan. You can execute a plan in either graceful or ungraceful mode. Specifing ungraceful mode either changes the behavior of the execution blocks in a workflow or skips specific execution blocks.

EXEC aws.arc_region_switch.plans.start_plan_execution 
@region='{{ region }}' --required 
@@json=
'{
"planArn": "{{ planArn }}", 
"targetRegion": "{{ targetRegion }}", 
"action": "{{ action }}", 
"mode": "{{ mode }}", 
"comment": "{{ comment }}", 
"latestVersion": "{{ latestVersion }}", 
"recoveryExecutionId": "{{ recoveryExecutionId }}", 
"clientToken": "{{ clientToken }}"
}'
;