groups

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

Overview

Name	groups
Type	Resource
Id	aws.synthetics.groups

Fields

The following fields are returned by SELECT queries:

get_group

Name	Datatype	Description
arn	string	The ARN of the group. (pattern: <code>arn:(aws[a-zA-Z-]*)?:synthetics:[a-z]{2,4}(-[a-z]{2,4})?-[a-z]+-\d{1}:\d{12}:group:[0-9a-z]+</code>)
created_time	string (date-time)	The date and time that the group was created.
id	string	The unique ID of the group.
last_modified_time	string (date-time)	The date and time that the group was most recently updated.
name	string	The name of the group.
tags	object	The list of key-value pairs that are associated with the canary.

list_groups

Name	Datatype	Description
groups	array	An array of structures that each contain information about one group.
next_token	string	A token that indicates that there is more data available. You can use this token in a subsequent ListGroups operation to retrieve the next set of results.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_group	select	group_identifier, region		Returns information about one group. Groups are a global resource, so you can use this operation from any Region.
list_groups	select	region		Returns a list of all groups in the account, displaying their names, unique IDs, and ARNs. The groups from all Regions are returned.
create_group	insert	region, Name		Creates a group which you can use to associate canaries with each other, including cross-Region canaries. Using groups can help you with managing and automating your canaries, and you can also view aggregated run results and statistics for all canaries in a group. Groups are global resources. When you create a group, it is replicated across Amazon Web Services Regions, and you can view it and add canaries to it from any Region. Although the group ARN format reflects the Region name where it was created, a group is not constrained to any Region. This means that you can put canaries from multiple Regions into the same group, and then use that group to view and manage all of those canaries in a single view. Groups are supported in all Regions except the Regions that are disabled by default. For more information about these Regions, see Enabling a Region. Each group can contain as many as 10 canaries. You can have as many as 20 groups in your account. Any single canary can be a member of up to 10 groups.
associate_resource	update	group_identifier, region, ResourceArn		Associates a canary with a group. Using groups can help you with managing and automating your canaries, and you can also view aggregated run results and statistics for all canaries in a group. You must run this operation in the Region where the canary exists.
delete_group	delete	group_identifier, region		Deletes a group. The group doesn't need to be empty to be deleted. If there are canaries in the group, they are not deleted when you delete the group. Groups are a global resource that appear in all Regions, but the request to delete a group must be made from its home Region. You can find the home Region of a group within its ARN.
disassociate_resource	exec	group_identifier, region, ResourceArn		Removes a canary from a group. You must run this operation in the Region where the canary exists.

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
group_identifier	string	Specifies the group. You can specify the group name, the ARN, or the group ID as the GroupIdentifier.
region	string	AWS region (default: us-east-1)

SELECT examples

get_group

Returns information about one group. Groups are a global resource, so you can use this operation from any Region.

SELECT
arn,
created_time,
id,
last_modified_time,
name,
tags
FROM aws.synthetics.groups
WHERE group_identifier = '{{ group_identifier }}' -- required
AND region = '{{ region }}' -- required
;

list_groups

Returns a list of all groups in the account, displaying their names, unique IDs, and ARNs. The groups from all Regions are returned.

SELECT
groups,
next_token
FROM aws.synthetics.groups
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_group

Creates a group which you can use to associate canaries with each other, including cross-Region canaries. Using groups can help you with managing and automating your canaries, and you can also view aggregated run results and statistics for all canaries in a group. Groups are global resources. When you create a group, it is replicated across Amazon Web Services Regions, and you can view it and add canaries to it from any Region. Although the group ARN format reflects the Region name where it was created, a group is not constrained to any Region. This means that you can put canaries from multiple Regions into the same group, and then use that group to view and manage all of those canaries in a single view. Groups are supported in all Regions except the Regions that are disabled by default. For more information about these Regions, see Enabling a Region. Each group can contain as many as 10 canaries. You can have as many as 20 groups in your account. Any single canary can be a member of up to 10 groups.

INSERT INTO aws.synthetics.groups (
Name,
Tags,
region
)
SELECT 
'{{ Name }}' /* required */,
'{{ Tags }}',
'{{ region }}'
RETURNING
group
;

Manifest

# Description fields are for documentation purposes
- name: groups
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the groups resource.
  - name: Name
    value: "{{ Name }}"
  - name: Tags
    value: "{{ Tags }}"

UPDATE examples

associate_resource

Associates a canary with a group. Using groups can help you with managing and automating your canaries, and you can also view aggregated run results and statistics for all canaries in a group. You must run this operation in the Region where the canary exists.

UPDATE aws.synthetics.groups
SET 
ResourceArn = '{{ ResourceArn }}'
WHERE 
group_identifier = '{{ group_identifier }}' --required
AND region = '{{ region }}' --required
AND ResourceArn = '{{ ResourceArn }}' --required;

DELETE examples

delete_group

Deletes a group. The group doesn't need to be empty to be deleted. If there are canaries in the group, they are not deleted when you delete the group. Groups are a global resource that appear in all Regions, but the request to delete a group must be made from its home Region. You can find the home Region of a group within its ARN.

DELETE FROM aws.synthetics.groups
WHERE group_identifier = '{{ group_identifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

disassociate_resource

Removes a canary from a group. You must run this operation in the Region where the canary exists.

EXEC aws.synthetics.groups.disassociate_resource 
@group_identifier='{{ group_identifier }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"ResourceArn": "{{ ResourceArn }}"
}'
;