AWS.ResourceGroups reference

CancelTagSyncTask

Source: src/AWS/ResourceGroups/CancelTagSyncTask.ts

Runtime binding for resource-groups:CancelTagSyncTask.

Cancels a running tag-sync task. Group membership stops being synced to the tag, but resources already grouped keep their membership. The task ARN is chosen per request, so the grant is on *. Provide the implementation with Effect.provide(AWS.ResourceGroups.CancelTagSyncTaskHttp).

CancelTagSyncTask: Tag-Sync Tasks

// init
const cancelTagSyncTask = yield* AWS.ResourceGroups.CancelTagSyncTask();

// runtime
yield* cancelTagSyncTask({ TaskArn: taskArn });

GetAccountSettings

Source: src/AWS/ResourceGroups/GetAccountSettings.ts

Runtime binding for resource-groups:GetAccountSettings.

Reads the account’s Resource Groups settings — most importantly whether group lifecycle events (the EventBridge feed consumed by consumeGroupEvents) are ACTIVE, INACTIVE, or stuck in ERROR. Provide the implementation with Effect.provide(AWS.ResourceGroups.GetAccountSettingsHttp).

GetAccountSettings: Account Settings

// init
const getAccountSettings = yield* AWS.ResourceGroups.GetAccountSettings();

// runtime
const { AccountSettings } = yield* getAccountSettings();
const status = AccountSettings?.GroupLifecycleEventsStatus;

GetTagSyncTask

Source: src/AWS/ResourceGroups/GetTagSyncTask.ts

Runtime binding for resource-groups:GetTagSyncTask.

Reads one tag-sync task’s detail — the synced tag key/value, the role it runs as, and its ACTIVE/ERROR status with the error message. The task ARN is chosen per request (typically the TaskArn returned by StartTagSyncTask or found via ListTagSyncTasks), so the grant is on *. Provide the implementation with Effect.provide(AWS.ResourceGroups.GetTagSyncTaskHttp).

GetTagSyncTask: Tag-Sync Tasks

// init
const getTagSyncTask = yield* AWS.ResourceGroups.GetTagSyncTask();

// runtime
const task = yield* getTagSyncTask({ TaskArn: taskArn });
if (task.Status === "ERROR") {
  yield* Effect.logError(`tag sync failed: ${task.ErrorMessage}`);
}

Group

Source: src/AWS/ResourceGroups/Group.ts

An AWS Resource Groups group — a collection of AWS resources defined by a tag-based query, a CloudFormation stack query, or an attached service configuration.

Deleting a group never deletes its member resources; it only deletes the group structure.

Group: Creating Groups

Tag-based Group

import * as ResourceGroups from "alchemy/AWS/ResourceGroups";

const group = yield* ResourceGroups.Group("EnvGroup", {
  description: "All resources tagged env=prod",
  resourceQuery: {
    type: "TAG_FILTERS_1_0",
    query: JSON.stringify({
      ResourceTypeFilters: ["AWS::AllSupported"],
      TagFilters: [{ Key: "env", Values: ["prod"] }],
    }),
  },
});

CloudFormation Stack Group

const group = yield* ResourceGroups.Group("StackGroup", {
  resourceQuery: {
    type: "CLOUDFORMATION_STACK_1_0",
    query: JSON.stringify({
      ResourceTypeFilters: ["AWS::AllSupported"],
      StackIdentifier: stackArn,
    }),
  },
});

Group: Service Configurations

const pool = yield* ResourceGroups.Group("ReservationPool", {
  configuration: [
    {
      type: "AWS::ResourceGroups::Generic",
      parameters: [
        {
          name: "allowed-resource-types",
          values: ["AWS::EC2::CapacityReservation"],
        },
      ],
    },
    { type: "AWS::EC2::CapacityReservationPool" },
  ],
});

Group: Tagging

const group = yield* ResourceGroups.Group("TaggedGroup", {
  resourceQuery: {
    type: "TAG_FILTERS_1_0",
    query: JSON.stringify({
      ResourceTypeFilters: ["AWS::AllSupported"],
      TagFilters: [{ Key: "team", Values: ["platform"] }],
    }),
  },
  tags: { team: "platform" },
});

GroupResources

Source: src/AWS/ResourceGroups/GroupResources.ts

Runtime binding for resource-groups:GroupResources.

Adds the specified resources to the bound Group. Supported only for groups configured with AWS::ResourceGroups::ApplicationGroup, AWS::EC2::HostManagement, or AWS::EC2::CapacityReservationPool — query-based groups derive membership from their query instead. Grouping is asynchronous (application-group members are tagged with awsApplication): the response reports Pending ARNs which ListGroupingStatuses tracks to SUCCESS/FAILED. The group name is injected from the binding; the grant includes the Tagging API permissions the membership tagging fans out to (member services may additionally require their own TagResource permission on the caller). Provide the implementation with Effect.provide(AWS.ResourceGroups.GroupResourcesHttp).

GroupResources: Managing Group Membership

// init — bind the operation to the group
const groupResources = yield* AWS.ResourceGroups.GroupResources(group);

// runtime
const { Succeeded, Pending, Failed } = yield* groupResources({
  ResourceArns: [resourceArn],
});

ListGroupingStatuses

Source: src/AWS/ResourceGroups/ListGroupingStatuses.ts

Runtime binding for resource-groups:ListGroupingStatuses.

Returns the status of the last grouping or ungrouping action for each resource in the bound application Group — grouping members is asynchronous, so this is how a function tracks a GroupResources / UngroupResources request to SUCCESS or reads the failure reason. The group name is injected from the binding. Provide the implementation with Effect.provide(AWS.ResourceGroups.ListGroupingStatusesHttp).

ListGroupingStatuses: Enumerating Group Members

// init — bind the operation to the group
const listGroupingStatuses = yield* AWS.ResourceGroups.ListGroupingStatuses(group);

// runtime
const { GroupingStatuses } = yield* listGroupingStatuses();
const failed = (GroupingStatuses ?? []).filter((s) => s.Status === "FAILED");

ListGroupResources

Source: src/AWS/ResourceGroups/ListGroupResources.ts

Runtime binding for resource-groups:ListGroupResources.

Enumerates the member resources of the bound Group — for a tag-based group the resources currently matching the query, for an application or configuration group the explicitly grouped members. The group name is injected from the binding; the grant also includes the tag:GetResources / CloudFormation read-through permissions the enumeration fans out to. Provide the implementation with Effect.provide(AWS.ResourceGroups.ListGroupResourcesHttp).

ListGroupResources: Enumerating Group Members

// init — bind the operation to the group
const listGroupResources = yield* AWS.ResourceGroups.ListGroupResources(group);

// runtime
const { Resources } = yield* listGroupResources();
const arns = (Resources ?? []).map((r) => r.Identifier?.ResourceArn);

ListTagSyncTasks

Source: src/AWS/ResourceGroups/ListTagSyncTasks.ts

Runtime binding for resource-groups:ListTagSyncTasks.

Enumerates the account’s tag-sync tasks (optionally filtered to a specific group) with each task’s status — how an ops function audits which groups are kept in sync with a tag and alerts on tasks in ERROR. Account-level: tasks span groups, so the grant is on *. Provide the implementation with Effect.provide(AWS.ResourceGroups.ListTagSyncTasksHttp).

ListTagSyncTasks: Tag-Sync Tasks

// init
const listTagSyncTasks = yield* AWS.ResourceGroups.ListTagSyncTasks();

// runtime
const { TagSyncTasks } = yield* listTagSyncTasks({
  Filters: [{ GroupName: "my-application" }],
});

SearchResources

Source: src/AWS/ResourceGroups/SearchResources.ts

Runtime binding for resource-groups:SearchResources.

Runs an ad-hoc resource query (the same TAG_FILTERS_1_0 / CLOUDFORMATION_STACK_1_0 syntax a query-based group is defined with) and returns the matching resource ARNs — a group-less preview of what a query would capture. Account-level: the query is chosen per request, so the grant is on * (including the Tagging API / CloudFormation read-through permissions the search fans out to). Provide the implementation with Effect.provide(AWS.ResourceGroups.SearchResourcesHttp).

SearchResources: Searching Resources

// init
const searchResources = yield* AWS.ResourceGroups.SearchResources();

// runtime
const { ResourceIdentifiers } = yield* searchResources({
  ResourceQuery: {
    Type: "TAG_FILTERS_1_0",
    Query: JSON.stringify({
      ResourceTypeFilters: ["AWS::AllSupported"],
      TagFilters: [{ Key: "env", Values: ["prod"] }],
    }),
  },
});

StartTagSyncTask

Source: src/AWS/ResourceGroups/StartTagSyncTask.ts

Runtime binding for resource-groups:StartTagSyncTask.

Starts a tag-sync task on the bound application Group: Resource Groups continuously adds resources carrying the tag (or matching the resource query) to the group and removes ones that stop matching, acting as the bound IAM role. The binding grants the action on the group plus iam:PassRole on the role (condition-scoped to resource-groups.amazonaws.com); the role itself needs the tagging permissions tag-sync uses and a trust policy for resource-groups.amazonaws.com. Provide the implementation with Effect.provide(AWS.ResourceGroups.StartTagSyncTaskHttp).

StartTagSyncTask: Tag-Sync Tasks

// init — bind the operation to the group and the sync role
const startTagSyncTask = yield* AWS.ResourceGroups.StartTagSyncTask(group, syncRole);

// runtime
const { TaskArn } = yield* startTagSyncTask({
  TagKey: "team",
  TagValue: "platform",
});

UngroupResources

Source: src/AWS/ResourceGroups/UngroupResources.ts

Runtime binding for resource-groups:UngroupResources.

Removes the specified resources from the bound Group (the inverse of GroupResources — supported for the same application / host-management / capacity-reservation-pool group types). Ungrouping is asynchronous; track the reported Pending ARNs with ListGroupingStatuses. The group name is injected from the binding. Provide the implementation with Effect.provide(AWS.ResourceGroups.UngroupResourcesHttp).

UngroupResources: Managing Group Membership

// init — bind the operation to the group
const ungroupResources = yield* AWS.ResourceGroups.UngroupResources(group);

// runtime
const { Succeeded, Pending } = yield* ungroupResources({
  ResourceArns: [resourceArn],
});