AWS Resource Groups Tagging API ExecModule

Overview

The AWS Resource Groups Tagging API ExecModule makes resource metadata usable in governed ValkyrAI workflows. Cloud-platform, FinOps, security, and compliance teams can discover tagged resources across supported AWS services, enumerate the tag vocabulary already in use, measure tag-policy gaps, and apply reviewed tag or untag changes to exact resource ARNs.

The connector supports six operations: get_resources, get_tag_keys, get_tag_values, get_compliance_summary, tag_resources, and untag_resources. Reads are bounded and can follow opaque provider pagination tokens. Mutations require operation-specific confirmation, run exactly once, and return AWS's per-resource failure map so a workflow can reconcile partial success without guessing.

Every call uses a verified IntegrationAccount. Raw credentials, authorization values, session tokens, and custom endpoints are rejected as workflow input. The AWS region is explicit because the Tagging API is regional: results in one region are not evidence of coverage in another.

get_resources returns resources that are currently tagged or were previously tagged. It does not discover every untagged AWS resource. Use AWS Resource Explorer or service-specific inventory when a workflow must prove the absence of tags across the full estate.

Usage

1. Decide which AWS regions and resource types the workflow is responsible for.
2. Grant only the Resource Groups Tagging API actions used by the workflow.
3. Store the AWS access-key pair in a ValkyrAI IntegrationAccount, verify it, and keep it in READY status.
4. Add AwsResourceGroupsTaggingModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Start with get_tag_keys, get_tag_values, or a tightly filtered get_resources call.
6. Use includeComplianceDetails for resource-level tag-policy evidence or get_compliance_summary for aggregated gaps.
7. For changes, supply exact resource ARNs and set only the confirmation that matches the requested operation.
8. Re-read the affected resources after a mutation, especially when AWS reports per-resource failures or the network outcome is uncertain.

Unknown and operation-inappropriate fields are rejected before provider access. This prevents a value intended for one operation from silently changing another request.

Inputs

Input	Type	Required	Default	Description
operation	string	Yes	—	One of the six documented operations.
region	string	Yes	—	Exact AWS region such as us-west-2.
nextToken	string	No	—	Opaque provider continuation token.
limit	integer	List operations	100	Total result bound from 1 to 1,000.
returnAll	boolean	List operations	false	Follow provider pages until limit or exhaustion.
resourceTypeFilters	array	No	[]	Up to 100 service or service:resourceType values.
tagFilters	array	No	[]	Up to 50 objects with a unique key and up to 20 optional values.
includeComplianceDetails	boolean	No	false	Include effective tag-policy compliance details with each resource.
excludeCompliantResources	boolean	No	false	Return only noncompliant resources; requires compliance details.
key	string	get_tag_values	—	Exact tag key whose values should be discovered.
regionFilters	array	No	[]	Regional filters for compliance summaries.
tagKeyFilters	array	No	[]	Tag-key filters for compliance summaries.
targetIdFilters	array	No	[]	Account, root, or organizational-unit targets for compliance summaries.
resourceArns	array	Mutations	—	One to 20 exact resource ARNs.
tags	object	tag_resources	—	One to 50 tag key/value pairs.
tagKeys	array	untag_resources	—	One to 50 exact tag keys.
confirmTagChange	boolean	tag_resources	false	Must be true for a tag write.
confirmUntagChange	boolean	untag_resources	false	Must be true for a tag removal.

Tag keys are limited to 128 characters and values to 256 characters. Reserved aws: keys, control characters, duplicate filter keys, malformed ARNs, invalid regions, oversized lists, and incompatible compliance flags are rejected locally.

Outputs

Every operation returns a stable envelope:

Output	Description
status	success or error.
operation	Normalized operation name.
attempts	Provider calls, including pages and safe read retries.
resultType	resources, tag_keys, tag_values, compliance_summaries, tag_failures, or untag_failures.
items / count	Bounded normalized results and returned count.
pages / hasMore / nextToken	Pagination evidence for list operations.
failureCount	Number of resource-specific failures returned by a mutation.
requestId	Safe AWS request identifier for operational correlation.
error	Stable code, redacted message, HTTP status, and retryability.

Resource results include the resource ARN, a bounded tag map, and optional compliance evidence: compliant, noncompliantKeys, and keysWithNoncompliantValues. Compliance summaries can include target, region, resource type, noncompliant resource count, and last-updated time.

Mutation results do not echo the submitted tag values. They contain only failed resource ARNs and bounded AWS failure codes, messages, and status codes. A zero failureCount means AWS did not report a per-resource failure for that request; workflows should still perform a read-after-write when the new state is business-critical.

IntegrationAccount Requirements

Use an AWS IntegrationAccount with:

• status: READY
• verified: true
• access key ID in the account API-key field
• secret access key in the protected password field

The connector never accepts credentials in workflow input and disables AWS SDK retries so ValkyrAI's attempt count remains authoritative.

Grant only the actions needed by the selected workflow:

tag:GetResources
tag:GetTagKeys
tag:GetTagValues
tag:GetComplianceSummary
tag:TagResources
tag:UntagResources

Read-only workflows do not need tag:TagResources or tag:UntagResources. Resource-level service permissions and tag-on-create policies can still affect whether AWS accepts a mutation. Some resource types support native service tagging but not Tagging API mutations, so confirm support for the targeted service rather than granting broad wildcard permissions.

Configuration

ExecModuleConfig supplies the IntegrationAccount and optional retry policy. Read operations retry only transient network, throttling, and provider failures, with one to five attempts and a default of three. Mutations never retry automatically.

get_resources requests at most 100 resources per provider page. get_compliance_summary requests at most 1,000 summaries per page. get_tag_keys and get_tag_values use AWS's provider-selected page size. ValkyrAI follows at most 100 pages and returns at most 1,000 items.

The module does not accept a custom endpoint. The AWS SDK derives the correct regional and partition-specific endpoint from the validated region.

Operations

get_resources

Returns tagged or previously tagged resources in the selected region. resourceTypeFilters narrow by service or resource type. Every tagFilters entry must match, while multiple values for one key are alternatives. Set includeComplianceDetails to see tag-policy evidence and combine it with excludeCompliantResources to focus on gaps.

Do not interpret an empty result as proof that the account has no resources or no untagged resources. Unsupported services, regional scope, IAM visibility, service-specific behavior, and the API's tagged-resource boundary all affect coverage.

get_tag_keys and get_tag_values

get_tag_keys enumerates tag keys used by resources in the selected account and region. get_tag_values enumerates values for one exact key. These operations are useful for detecting spelling drift, deprecated taxonomies, and unexpected environment or ownership values before writing any changes.

Tag vocabulary is not automatically a governance policy. Compare discovered keys and values with the authoritative taxonomy and tag policy before proposing normalization.

get_compliance_summary

Returns aggregated counts of noncompliant resources, optionally filtered by target, region, resource type, or tag key. Use this operation for routing and trend workflows; use get_resources with compliance details when the workflow needs exact resource-level evidence.

Compliance is evaluated against the account's effective AWS tag policy. A compliant tag-policy result does not prove cost allocation, ownership accuracy, data classification, or operational readiness unless those requirements are encoded and applied in the effective policy.

tag_resources

Applies one reviewed tag map to one to 20 exact resource ARNs. The operation requires confirmTagChange: true, sends the request once, and exposes every provider-reported resource failure. Existing values for submitted keys may be replaced according to the target service's tagging behavior.

untag_resources

Removes one to 50 exact tag keys from one to 20 resource ARNs. The operation requires confirmUntagChange: true and sends the request once. Removing ownership, cost, security, or lifecycle tags can change downstream automation and reporting, so route proposed removals through an accountable review step.

Errors and Failure Modes

Code	Meaning	Retry guidance
VALIDATION_ERROR	A required region, filter, ARN, tag, confirmation, or bound is invalid.	Correct input; no provider call was made.
INTEGRATION_ACCOUNT_ERROR	The account is missing, unverified, not READY, or incomplete.	Repair and verify the account.
UNSUPPORTED_OPERATION	The operation is outside this release.	Select one documented operation.
AWS_TAGGING_HTTP_400	AWS rejected a parameter, ARN, pagination token, or service-specific tag action.	Correct the request and inspect the request ID.
AWS_TAGGING_HTTP_403	IAM or the target resource denied access.	Add only the missing least-privilege action and resource permission.
AWS_TAGGING_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Reads retry automatically; reconcile mutations before retrying.
NETWORK_ERROR	ValkyrAI could not reach the regional tagging endpoint.	Retry reads; reconcile any mutation before deciding to repeat it.
EXECUTION_ERROR	An unexpected local failure was safely contained.	Inspect server logs; credentials and provider details remain redacted.

AWS can return HTTP 200 with resource-specific failures for tag_resources or untag_resources. Those failures appear in items and increase failureCount; they are not hidden behind a generic success message.

Example

Find tagged production resources that do not comply with the effective tag policy:

{
  "operation": "get_resources",
  "region": "us-west-2",
  "resourceTypeFilters": ["ec2:instance", "s3:bucket"],
  "tagFilters": [
    {"key": "Environment", "values": ["production"]}
  ],
  "includeComplianceDetails": true,
  "excludeCompliantResources": true,
  "returnAll": true,
  "limit": 200
}

Expected result shape:

{
  "status": "success",
  "operation": "get_resources",
  "attempts": 1,
  "resultType": "resources",
  "items": [
    {
      "resourceArn": "arn:aws:ec2:us-west-2:111122223333:instance/i-0123456789abcdef0",
      "tags": {
        "Environment": "production",
        "Owner": "platform"
      },
      "compliance": {
        "compliant": false,
        "noncompliantKeys": ["CostCenter"],
        "keysWithNoncompliantValues": []
      }
    }
  ],
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "requestId": "example-request-id"
}

A downstream workflow can join each ARN to the authoritative ownership system, request the missing value, obtain human approval, call tag_resources once, and then re-read the exact resource to verify the result.

Notes

• Pagination: Provider tokens are opaque and can expire. returnAll follows no more than 100 pages and never returns more than 1,000 items.
• Rate limits: Read retries are bounded. The module does not use unbounded polling or hidden SDK retries.
• API limits: Resource inventory, filter, ARN, tag, and page sizes are validated against conservative provider bounds before network access.
• Idempotency: Reads are repeatable. Tag writes may replace values; untag writes remove keys. Mutations are sent once and require read-after-write reconciliation when the outcome matters.
• Regional scope: Run explicit workflows per required region. One regional result is not global coverage evidence.
• Untagged resources: get_resources does not discover the complete untagged estate. Use AWS Resource Explorer or service-specific inventory for that requirement.
• Partial failure: A mutation can succeed for some ARNs and fail for others. Always inspect failureCount and items.
• Tag safety: Reserved aws: keys are rejected. Keep ownership, cost allocation, security classification, and lifecycle tags under explicit change control.
• Destructive behavior: The module does not delete AWS resources. untag_resources is reversible only if the removed value is known and reapplied, and it can still disrupt downstream policy or reporting.
• Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account is supplied.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsResourceGroupsTaggingModule through /v1/modules/metadata.

Related resources

• AWS Resource Groups Tagging API Reference
• GetResources API behavior and filters
• AWS Organizations ExecModule
• AWS Config ExecModule