legal_holds

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

Overview

Name	legal_holds
Type	Resource
Id	aws.backup.legal_holds

Fields

The following fields are returned by SELECT queries:

get_legal_hold

Name	Datatype	Description
cancel_description	string	The reason for removing the legal hold.
cancellation_date	string (date-time)	The time when the legal hold was cancelled.
creation_date	string (date-time)	The time when the legal hold was created.
description	string	The description of the legal hold.
legal_hold_arn	string	The framework ARN for the specified legal hold. The format of the ARN depends on the resource type.
legal_hold_id	string	The ID of the legal hold.
recovery_point_selection	object	This specifies criteria to assign a set of resources, such as resource types or backup vaults.
retain_record_until	string (date-time)	The date and time until which the legal hold record is retained.
status	string	The status of the legal hold. (CREATING, ACTIVE, CANCELING, CANCELED)
title	string	The title of the legal hold.

list_legal_holds

Name	Datatype	Description
cancellation_date	string (date-time)	The time when the legal hold was cancelled.
creation_date	string (date-time)	The time when the legal hold was created.
description	string	The description of a legal hold.
legal_hold_arn	string	The Amazon Resource Name (ARN) of the legal hold; for example, arn:aws:backup:us-east-1:123456789012:recovery-point:1EB3B5E7-9EB0-435A-A80B-108B488B0D45.
legal_hold_id	string	The ID of the legal hold.
status	string	The status of the legal hold. (CREATING, ACTIVE, CANCELING, CANCELED)
title	string	The title of a legal hold.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_legal_hold	select	legal_hold_id, region		This action returns details for a specified legal hold. The details are the body of a legal hold in JSON format, in addition to metadata.
list_legal_holds	select	region	nextToken, maxResults	This action returns metadata about active and previous legal holds.
create_legal_hold	insert	region		Creates a legal hold on a recovery point (backup). A legal hold is a restraint on altering or deleting a backup until an authorized user cancels the legal hold. Any actions to delete or disassociate a recovery point will fail with an error if one or more active legal holds are on the recovery point.
cancel_legal_hold	exec	legal_hold_id, cancelDescription, region	retainRecordInDays	Removes the specified legal hold on a recovery point. This action can only be performed by a user with sufficient permissions.

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
cancelDescription	string	A string the describes the reason for removing the legal hold.
legal_hold_id	string	The ID of the legal hold.
region	string	AWS region (default: us-east-1)
maxResults	integer	The maximum number of resource list items to be returned.
nextToken	string	The next item following a partial list of returned resources. For example, if a request is made to return MaxResults number of resources, NextToken allows you to return more items in your list starting at the location pointed to by the next token.
retainRecordInDays	integer (int64)	The integer amount, in days, after which to remove legal hold.

SELECT examples

get_legal_hold

This action returns details for a specified legal hold. The details are the body of a legal hold in JSON format, in addition to metadata.

SELECT
cancel_description,
cancellation_date,
creation_date,
description,
legal_hold_arn,
legal_hold_id,
recovery_point_selection,
retain_record_until,
status,
title
FROM aws.backup.legal_holds
WHERE legal_hold_id = '{{ legal_hold_id }}' -- required
AND region = '{{ region }}' -- required
;

list_legal_holds

This action returns metadata about active and previous legal holds.

SELECT
cancellation_date,
creation_date,
description,
legal_hold_arn,
legal_hold_id,
status,
title
FROM aws.backup.legal_holds
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;

INSERT examples

create_legal_hold

Creates a legal hold on a recovery point (backup). A legal hold is a restraint on altering or deleting a backup until an authorized user cancels the legal hold. Any actions to delete or disassociate a recovery point will fail with an error if one or more active legal holds are on the recovery point.

INSERT INTO aws.backup.legal_holds (
Title,
Description,
IdempotencyToken,
RecoveryPointSelection,
Tags,
region
)
SELECT 
'{{ Title }}',
'{{ Description }}',
'{{ IdempotencyToken }}',
'{{ RecoveryPointSelection }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
creation_date,
description,
legal_hold_arn,
legal_hold_id,
recovery_point_selection,
status,
title
;

Manifest

# Description fields are for documentation purposes
- name: legal_holds
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the legal_holds resource.
  - name: Title
    value: "{{ Title }}"
  - name: Description
    value: "{{ Description }}"
  - name: IdempotencyToken
    value: "{{ IdempotencyToken }}"
  - name: RecoveryPointSelection
    description: |
      This specifies criteria to assign a set of resources, such as resource types or backup vaults.
    value:
      VaultNames:
        - "{{ VaultNames }}"
      ResourceIdentifiers:
        - "{{ ResourceIdentifiers }}"
      DateRange:
        FromDate: "{{ FromDate }}"
        ToDate: "{{ ToDate }}"
  - name: Tags
    value: "{{ Tags }}"

Lifecycle Methods

cancel_legal_hold

Removes the specified legal hold on a recovery point. This action can only be performed by a user with sufficient permissions.

EXEC aws.backup.legal_holds.cancel_legal_hold 
@legal_hold_id='{{ legal_hold_id }}' --required, 
@cancelDescription='{{ cancelDescription }}' --required, 
@region='{{ region }}' --required, 
@retainRecordInDays='{{ retainRecordInDays }}'
;