[New Service]: AWS User Notifications

[F-Xu]

Description

AWS announced User Notifications general availability on 3rd May 2023.

Requested Resource(s) and/or Data Source(s)

aws_usernotification_configuration
aws_usernotification_deliverychannel
aws_usernotification_hub

Potential Terraform Configuration

No response

References

https://aws.amazon.com/about-aws/whats-new/2023/05/aws-user-notifications-available/
https://docs.aws.amazon.com/notifications/latest/userguide/what-is-service.html

Would you like to implement a fix?

None

[github-actions]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please see our prioritization guide for information on how we prioritize.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.

[colonmelvin]

Per AWS documentation there is no API for User Notifications.

Does AWS User Notifications provide users with APIs to access notifications?
No, AWS User Notifications does not provide programmatic access to notifications.

[iwamot]

AWS User Notifications API is now available.
https://docs.aws.amazon.com/notifications/latest/APIReference/Welcome.html

[jatin-mehrotra-colorkrew]

https://aws.amazon.com/about-aws/whats-new/2024/11/aws-user-notifications-sdk/

SDK is available which also means API is also available

[DanHyland]

Bump now that the API and SDK are now available. Is there an ETA when we can have TF resources to manage AWS User Notifications?

[yshollander-selerity]

AWS User Notifications is the strategic direction for all notifications. It already supports notifications from AWS Health, Cloudwatch, and EC2, and will eventially handle Security Hub notifications as well.

AWS provider support of User notification is needed.

[srgoni]

The user notifications API also provides functionality for setting up managed notifications, as mentioned in the duplicate issue: #40292 (comment)

I think these should also be covered by Terraform resources.

Suggestion:

data "aws_managed_notification_configuration" "security" {
  // Options available at this time:
  // "Security", "Health Operations", "Account-Specific Issues", "Billing Notification"
  name = "Security"
}

resource "aws_managed_notification_contacts" "security" {
  configuration_arn = data.aws_managed_notification_configuration.security.arn
  // Options available at this time:
  // ACCOUNT_PRIMARY | ACCOUNT_ALTERNATE_BILLING | ACCOUNT_ALTERNATE_OPERATIONS | ACCOUNT_ALTERNATE_SECURITY
  // Making "contacts" a multi-value (dynamic) property wouldn't work well, because
  // it would make it difficult to remove existing (default) associations.
  // A list seems like a much better choice here.
  contacts = ["ACCOUNT_PRIMARY", "ACCOUNT_ALTERNATE_SECURITY"]
}

resource "aws_managed_notification_channel_association" "extra_security_contact" {
  configuration_arn = data.aws_managed_notification_configuration.security.arn
  // This will support the same ARNs as user notification associations.
  // Example with a proposed email contact resource (which doesn't exist yet):
  channel_arn = aws_notifications_email_contact.extra_security_contact.arn
}

It would also be great to manage the AWS User Notification opt-in status, but unfortunately, AWS did not officially document the API that is required to do this. They do mention IAM actions, and these are indeed the API calls sent by the AWS console: https://docs.aws.amazon.com/notifications/latest/userguide/managing-notification-features.html
It should be noted that this is neither required for managed notifications to function, nor for configuring custom notification channels, but there are some subtle differences between opted-out and opted-in status: https://docs.aws.amazon.com/notifications/latest/userguide/managed-notifications.html

By default, AWS managed notifications emails are sent to your existing account contacts (root, operations, billing, and security email addresses). Enabling managed notifications changes the prefix of these emails to match the service sending the notification and the domain of these emails to @aws.com. For example, AWS managed notifications from AWS Health are sent from health@aws.com instead of no-reply-aws@amazon.com. The format of these emails also change. If you previously set up email rules for AWS Health emails, such as routing an email by its sender or scraping content from the email itself, then you must update this setup to match the new email format.

[srgoni]

Here's a complete proposal of all new resources and data sources that should be created.

I'm not quite sure how the Organizations access and Notification Hub registrations should be handled best, and I also didn't include any data sources for ManagedNotificationEvent and ManagedNotificationChildEvent (they don't make a lot of sense in Terraform code to me).

Also note that notifications-contacts has a separate AWS service ID, but it's only used for managing notification email contacts so far. Putting this into a separate service package seems a bit overkill. But maybe it's easier to implement as a separate service.

Another thing: https://docs.aws.amazon.com/general/latest/gr/notifications.html doesn't list any service endpoints for User Notifications. As far as I know, there is only a global endpoint in the us-east-1 region.

Edit: Provided an alternative proposal for aws_notifications_managed_notification_contacts.
Edit 2: Changed the organization access resource to match similar resources for other AWS services. Examples: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/securityhub_organization_configuration https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/macie2_organization_configuration https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/detective_organization_configuration

// Deleting this resource won't disable organization access.
resource "aws_notifications_organization_configuration" "example" {
  enable_organization_access = true
}

// Deleting this resource will delete the notification hub instance.
// A maximum of three resources of this type can be created (according to the documentation).
resource "aws_notifications_notification_hub_registration" "us-east-1" {
  notification_hub_region = "us-east-1"
  // Attributes:
  // creation_time
  // last_activation_time
  // status_summary
}

data "aws_notifications_email_contact" "test_contact" {
  email_address = "test@example.com"
  // Attributes:
  // name
  // status
  // creation_time
  // update_time
  // arn
}

resource "aws_notifications_email_contact" "extra_security_contact" {
  email_address = "test@example.com"
  name = "Security Contact"
}

resource "aws_notifications_email_contact_activation" "extra_security_contact" {
  contact_arn = aws_notifications_email_contact.extra_security_contact.arn
  code = "abcd123"
}

// Deleting this resource should not disable organization access.
// Rather, the "active" property should control activation status.
resource "aws_notifications_organization_access" "org" {
  active = true
}

data "aws_notifications_managed_notification_configuration" "security" {
  // Options available at this time:
  // "Security", "Health Operations", "Account-Specific Issues", "Billing Notification"
  name = "Security"
}

resource "aws_notifications_managed_notification_contacts" "security" {
  configuration_arn = data.aws_notifications_managed_notification_configuration.security.arn
  // Options available at this time:
  // ACCOUNT_PRIMARY | ACCOUNT_ALTERNATE_BILLING | ACCOUNT_ALTERNATE_OPERATIONS | ACCOUNT_ALTERNATE_SECURITY
  // Making "contacts" a multi-value (dynamic) property wouldn't work well, because
  // it would make it difficult to remove existing (default) associations.
  // A list seems like a much better choice here.
  contacts = ["ACCOUNT_PRIMARY", "ACCOUNT_ALTERNATE_SECURITY"]
  // ***********
  // Alternative implementation: Separate properties.
  // If a property is not set here, the flag won't be touched.
  account_primary = true
  //account_alternate_billing = false
  account_alternate_operations = false
  account_alternate_security = true
  // ***********
}

resource "aws_notifications_managed_notification_channel_association" "extra_security_contact" {
  configuration_arn = data.aws_notifications_managed_notification_configuration.security.arn
  // Supported channel resources: chatbot, consoleapp, notifications-contacts
  // Example with an email contact resource:
  channel_arn = aws_notifications_email_contact.extra_security_contact.arn
}

data "aws_notifications_notification_configuration" "test_notification" {
  name = "Test_Notification"
  // Or:
  // arn = "arn:aws:notifications::111122223333:configuration/fjdghkj98894hfudg90ugf"
  // Attributes:
  // aggregation_duration
  // creation_time
  // description
  // name
  // status
}

resource "aws_notifications_notification_configuration" "notification" {
  name = "Custom_Notification"
  // Supported values: LONG | SHORT | NONE
  aggregation_duration = "NONE"
  description = "A custom user notification"
}

data "aws_notifications_event_rule" "test_rule" {
  // There doesn't seem to be a unique property for matching this resource, so require the ARN instead
  arn = "arn:aws:notifications::111122223333:configuration/fjdghkj98894hfudg90ugf/rule/h8gh0230fjfj0j"
  // Attributes:
  // creation_time
  // event_pattern
  // event_type
  // managed_rules
  // regions
  // source
  // status_summary_by_region
  // notification_configuration_arn
}

resource "aws_notifications_event_rule" "rule" {
  notification_configuration_arn = aws_notifications_notification_configuration.notification.arn
  source = "aws.health"
  // Unclear if this matches the detail-type string or the detail.type property
  event_type = "TBD"
  regions = [ "us-east-1", "us-west-1" ]
  // Extra patterns not matched by source, event_type and regions
  event_pattern = jsonencode({
    account = "111122223333"
  })
}

resource "aws_notifications_channel_association" "notification" {
  notification_configuration_arn = aws_notifications_notification_configuration.notification.arn
  // Supported channel resources: chatbot, consoleapp, notifications-contacts
  // Example with an email contact resource:
  channel_arn = aws_notifications_email_contact.extra_security_contact.arn
}

// No data sources for ManagedNotificationEvent and ManagedNotificationChildEvent

[marcinbelczewski]

@srgoni are willing to contribute the design proposed above or possibly you'd welcome some assistance? I could contribute as well.

[srgoni]

@srgoni are willing to contribute the design proposed above or possibly you'd welcome some assistance? I could contribute as well.

Yes, that was my intention. But I'm still working out how to do it, so feel free to start working on it if you like.

[marcinbelczewski]

Thanks for comment @srgoni. I will try to take a stab and if I'm successful I will create a draft PR. Cheers!

[wanis-fahmy]

since this is merged, would it be possible to release this in 5.x provider versions as well? I see already a 6.x-beta release but this would entail some migration efforts from our side for other resources to make use of this feature.

[srgoni]

@wanis-fahmy Please be patient a little longer, since the implementation is not finished yet. So far, we only have the services added, but there are no resources or data sources yet. @marcinbelczewski has just started with the first PRs, which need to be completed, reviewed and tested first.

[marcinbelczewski]

@wanis-fahmy, @srgoni here are first two PRs: #42544, #42575
Please vote!