Home› Blog› AWS Daily Intelligence #81 - The tag filter is an …
AWS Daily Intelligence AWS

AWS Daily Intelligence #81 - The tag filter is an OR, and an account tag matches as if it were the resource's

Verified against current vendor documentation on 20 November 2026. Pricing, limits and API behaviour were checked against the official docs on that date. Cloud services change fast — if you are reading this much later, treat the specifics as a starting point and re-check the linked sources.

The EC2 performance status check in #80 was a new signal that changes an alarm you already have. This one is the opposite shape: a genuinely useful enrichment whose filtering semantics are precisely documented, widely assumed, and the two are not the same thing.

“Matching is case sensitive, and the filter matches when at least one key in the map matches.”

Executive summary

“AWS Health now supports resource and account tags in Health events”. The capability “enables you to enrich Health events with resource tags and account tags, providing additional context to help you manage and respond to events more effectively”, so that “you can now view resource tags directly within Health events for supported AWS services” and “account-level tags help you categorize and filter events across your organization, making it easier to route notifications and automate responses based on your organizational structure”.

That is a real gap closed. A Health event that names i-1234567890abcdef0 and nothing else has always required a second lookup against the owning service before anyone could decide whether it mattered. Carrying the tags on the event removes that hop, and the announcement is right that tags in Health events “enable more granular event filtering in AWS Health Dashboard and AWS Health API responses”.

The API reference then supplies the part that decides whether your filter does what you think. The tags filter unions its keys rather than intersecting them, it matches resource tags and account tags without distinguishing them, and the account-tag map is documented as arriving from only one of the two retrieval operations.

What changed

Two new maps on the AffectedEntity object. resourceTags is “A map of resource tag key-value pairs attached to the affected entity”. accountTags is “A map of account tag key-value pairs for the account that owns the affected entity”.

And a new tags filter on the request side, which is where the behaviour lives:

“A map of tag keys to lists of tag values. A tag matches when its key is in the map and its value is one of the values listed for that key. Matching is case sensitive, and the filter matches when at least one key in the map matches.”

Read that last clause slowly. A filter naming two keys is satisfied by either of them. The intuition most people bring to a map-shaped filter — that adding a key narrows the result — is inverted here: adding a key widens it.

Architecture

Diagram: AWS Health now supports resource and account tags in Health events, enriching events with resource tags and account tags so you can view resource tags directly within Health events for supported AWS services, while account-level tags help you categorize and filter events across your organization and enable more granular event filtering in the AWS Health Dashboard and AWS Health API responses. The behaviour that matters is in the EntityAccountFilter reference: the tags filter is a map of tag keys to lists of tag values, a tag matches when its key is in the map and its value is one of the values listed for that key, matching is case sensitive, and the filter matches when at least one key in the map matches. That makes a multi-key filter a union rather than an intersection, so a filter naming both an environment key and a cost-centre key returns entities matching either one, which is wider than the conjunction most people intend to write. The filter also does not distinguish the two tag sources: an entity is returned when the tags of the resource, or of the account it belongs to, match, so there is no documented way to filter on resource tags alone, even though the response separates them into a resourceTags map and an accountTags map. When you specify several filters in organizationEntityAccountFilters the tags must be identical in every filter, so one organizational call cannot carry a different tag predicate per account. The retrieval paths differ too: accountTags is documented as returned only by DescribeAffectedEntitiesForOrganization and not populated by DescribeAffectedEntities, even though the single-account operation response syntax shows the accountTags key, so a member-account caller reading it gets nothing and no error. Both maps cap at a maximum of 10 items, tag keys at 127 characters and values at 255, and the filter value array holds a maximum of 50 items per key, giving a ceiling of 500 tag values expressible in one filter. For EventBridge, the announcement promises sophisticated routing and handling of Health events based on tag values, but the AWS Health EventBridge schema reference documents affectedEntities as carrying entityValue, lastUpdatedtime and status only and does not document a tag field, so an event pattern should be written against an observed event rather than from the schema page; pagination occurs only on resources and if the 256KB size limit is exceeded for another reason the communication fails. Finally, tag enrichment is a step rather than a default: to enable tag enrichment, visit the AWS Health Dashboard. Calling the AWS Health API requires a Business, Enterprise On-Ramp, or Enterprise Support plan and the US East North Virginia Region endpoint.

What the filter actually evaluates

Filter you write What a reader assumes What the reference documents
{Environment: [prod]} Entities tagged prod Entities whose resource or owning account is tagged prod
{Environment: [prod], CostCenter: [4812]} prod AND cost centre 4812 Either one — “at least one key in the map matches”
{Environment: [prod, staging]} Both environments Both — values within a key are a list, and any one of them matches
{environment: [prod]} Same as Environment No match — “Matching is case sensitive”

So the only filter whose meaning is unambiguous is a single-key one. Everything else returns a superset of what you meant, and a superset arriving at an automation that creates tickets is not a harmless over-fetch.

The two tag sources are matched together and returned apart

“An entity is returned when the tags of the resource, or of the account it belongs to, match.”

The response separates the two — resourceTags and accountTags are distinct maps. The filter does not. There is no documented way to ask for entities whose resource is tagged Environment=prod while ignoring the account tag of the same name.

In a typical organisation that is exactly the collision you have. Accounts are tagged by environment because account-per-environment is the standard pattern, and resources inside them are tagged by environment too. A filter for Environment=prod against a production account matches every affected entity in it, tagged or not. The filter is still useful; it is useful as a coarse account-and-resource sieve, not as the resource-level predicate the announcement's framing suggests.

If you need the distinction, the tags are in the response. Filter broadly, then branch on resourceTags in your own code.

One tag predicate per organizational call

“When you specify several filters in organizationEntityAccountFilters, the tags must be identical in every filter.”

organizationEntityAccountFilters takes up to 10 account filters, so the natural design — one filter per account, each with that account's own tag convention — is not available. Differing tag conventions across accounts mean one call per convention.

The field that is in the shape but not in the payload

“This field is returned only by DescribeAffectedEntitiesForOrganization and is not populated by DescribeAffectedEntities.”

That is accountTags. The documented response syntax for DescribeAffectedEntities — the single-account operation — still shows an accountTags key, because both operations return the same AffectedEntity object. A member-account script that reads it finds nothing there, and nothing in the response says why.

The organizational operation is the one that populates it, and it has prerequisites: “Before you can call this operation, you must first enable AWS Health to work with AWS Organizations”, which is a management-account action. So account tags are a management-account and delegated-administrator capability in practice, not something a workload account can read about itself.

Ceilings

ThingDocumented limit
tags filter, keysMaximum number of 10 items
tags filter, values per keyMaximum number of 50 items
Filter key / value length127 / 255 characters
resourceTags, accountTags in the responseMaximum number of 10 items each
organizationEntityAccountFiltersMaximum number of 10 items

Ten keys of fifty values is 500 tag values in a single filter, which is generous for the OR semantics it actually implements. The ten-entry cap on the returned maps is the one to think about: a resource carrying more tags than that has some subset surfaced, and the reference does not say which. Do not build a decision on a tag key being absent from the map.

EventBridge, where the announcement runs ahead of the schema

The announcement is specific: the feature “enables sophisticated routing and handling of Health events based on tag values, supporting use cases such as automatically creating tickets in your IT service management system or sending targeted notifications to specific teams”.

The AWS Health EventBridge schema reference, checked today, documents affectedEntities as carrying entityValue, lastUpdatedtime and status. No tag field appears in that table or in any of its five sample payloads.

That is a statement about the documentation, not a claim that tags are absent from events. The reference may simply trail the launch. The operational conclusion is the same either way: capture a real tagged Health event and write your event pattern against the JSON you observed, rather than against a field name you inferred from the announcement. An EventBridge rule whose pattern never matches is silent — no error, no metric, no indication that the routing you built is routing nothing.

One related constraint worth carrying into the design: “Pagination occurs only on resources. If the 256KB size limit is exceeded for another reason, the communication to fail.” Health events already split across pages on resource count, and a consumer that handles only page one was already incomplete.

Business value

The enrichment is worth having on its own. Health events identify resources the way the owning service does, which is rarely the way a human reasons about them. Tags on the event mean the first question — whose is this, and does it matter tonight — is answerable from the event.

The routing case is real too, with the filter semantics understood. Sending an event about a CostCenter=4812 resource to the team that owns 4812 is the kind of thing every organisation builds badly from an account-ID lookup table that goes stale. Tags are maintained by the teams themselves.

The cost-allocation framing in the announcement — improve cost allocation tracking for health-related events — is the weakest of the three. Health events are not billing records, and correlating an impairment with a cost centre tells you who was affected, not what it cost.

Security considerations

Tags are now a disclosure surface on a new channel. AWS's own tagging guidance is blunt — “Do not store personally identifiable information (PII) or other confidential or sensitive information in tags” — and that guidance now applies to anywhere Health events land: an EventBridge bus, an SNS topic, a ticketing system, a chat channel. A tag key naming an internal project or a customer is now in the notification path.

The retrieval asymmetry is a boundary worth noticing rather than working around. Account tags come from the organizational operation, which requires management-account enablement, and DescribeAffectedEntitiesForOrganization “doesn't support resource-level permissions” — so access to it is all-or-nothing across the organization's events. That is an argument for keeping it in the management or delegated-administrator account and fanning out derived notifications, rather than granting workload accounts the organizational read.

And if you route on tags, the tag becomes an authorisation input of sorts. Whoever can tag a resource can change which team gets paged about it. That is usually fine and occasionally is not.

Cost considerations

The announcement states no price for the feature, and no Region list. What the surrounding documentation does state is the access requirement: “Organizational view is available in the AWS Health console for all AWS Support plans at no additional cost”, but “You must have a Business, Enterprise On-Ramp, or Enterprise Support plan to call the AWS Health API”, and “You must use the US East (N. Virginia) Region endpoint”.

So the console half of this is available broadly and the programmatic half is gated on a paid support plan. For anyone already paying for one, the marginal cost of the tag enrichment is whatever your downstream consumers charge — EventBridge targets, Lambda invocations, ticket creation.

Operational considerations

Enrichment is a step, not a default: “To enable tag enrichment, visit the AWS Health Dashboard or view the AWS Health User Guide for more information.” Until someone does that, events carry no tags, and the symptom is an empty map rather than an error.

Which produces the ambiguity to design around. An entity with no tags in a Health event can mean the resource is untagged, enrichment is not enabled, or the service is not one of the “supported AWS services” the announcement scopes this to and does not enumerate. Three different problems, one indistinguishable signal. A consumer that treats a missing tag as not mine will silently drop events in all three cases.

The safe default is the inverse: route on a tag when it is present, and route to a catch-all when it is absent. Never filter an event away because a tag did not arrive.

Tradeoffs

ApproachWhat you getWhat it costs
Filter server-side with tags Less data over the wire; one call per convention OR semantics, no resource-versus-account distinction, case-sensitive exact match
Fetch broadly, filter in code Exact predicate you intended, including conjunctions and resource-tags-only matching More pages, more API calls against a rate-limited service
Route in EventBridge on tag values No polling; event-driven fan-out Pattern written against a payload the schema reference does not yet document
Keep the existing account-ID lookup table Behaviour you have already debugged Staleness, and none of the resource-level context this launch adds

Implementation guidance

Enable tag enrichment from the AWS Health Dashboard first, then capture one real event before writing anything that depends on its shape. For the API path, call from the management or delegated administrator account against us-east-1, with organizational access already enabled.

Write single-key tag filters. If you need a conjunction, filter on the most selective key and apply the rest in code against the returned resourceTags and accountTags maps — which is also the only way to require that a match came from the resource rather than its account.

Normalise case before you filter. Tag keys and values are case sensitive in AWS generally and the filter is explicitly case sensitive, so a convention that tolerates prod and Prod in the tag estate needs both listed in the values array.

Best practices

  • Treat a missing tag as unknown, never as excluded. Route unmatched events to a catch-all.
  • Do not depend on a specific tag key being present in the returned map — it caps at ten entries and the reference does not say which ten.
  • Keep the organizational read in the management or delegated administrator account; it has no resource-level permissions to narrow it with.
  • Audit tag values for anything sensitive before routing events into chat or ticketing.
  • Alarm on your EventBridge rule matching nothing. A pattern against an undocumented field fails silently.

Who should adopt this and when

Now, for the enrichment: anyone running more than a handful of accounts who currently resolves Health event resource IDs by hand. Enable it and read the tags in the dashboard; there is no downside and no filter semantics involved.

Now, carefully, for the API filter: teams building organizational Health automation, with the OR semantics and the resource-or-account matching understood and the narrowing done in code.

Wait, for EventBridge tag routing: not because it will not work, but because the schema reference does not yet document the field you would pattern-match on. Capture an event, confirm the shape, then build.

Key takeaways

The enrichment is straightforwardly good: “you can now view resource tags directly within Health events for supported AWS services”, removing a lookup that every Health consumer has been doing by hand.

The filter is the part to read twice. “the filter matches when at least one key in the map matches” makes a multi-key filter wider than a single-key one, and “An entity is returned when the tags of the resource, or of the account it belongs to, match” means you cannot ask for resource tags alone.

And two silent failures to design against: accountTags is “not populated by DescribeAffectedEntities” while still appearing in its response syntax, and the EventBridge schema reference documents no tag field yet — so a pattern written from the announcement rather than from a captured event matches nothing, forever, without complaint.

Official AWS references

Comments

How was your experience?
Your feedback helps improve this site.
PoorExcellent