@pulumi/aws
Version:
A Pulumi package for creating and managing Amazon Web Services (AWS) cloud resources.
428 lines (427 loc) • 20.9 kB
TypeScript
import * as pulumi from "@pulumi/pulumi";
import { Topic } from "./index";
/**
* Provides a resource for subscribing to SNS topics. Requires that an SNS topic exist for the subscription to attach to. This resource allows you to automatically place messages sent to SNS topics in SQS queues, send them as HTTP(S) POST requests to a given endpoint, send SMS messages, or notify devices / applications. The most likely use case for provider users will probably be SQS queues.
*
* > **NOTE:** If the SNS topic and SQS queue are in different AWS regions, the `aws.sns.TopicSubscription` must use an AWS provider that is in the same region as the SNS topic. If the `aws.sns.TopicSubscription` uses a provider with a different region than the SNS topic, this provider will fail to create the subscription.
*
* > **NOTE:** Setup of cross-account subscriptions from SNS topics to SQS queues requires the provider to have access to BOTH accounts.
*
* > **NOTE:** If an SNS topic and SQS queue are in different AWS accounts but the same region, the `aws.sns.TopicSubscription` must use the AWS provider for the account with the SQS queue. If `aws.sns.TopicSubscription` uses a Provider with a different account than the SQS queue, this provider creates the subscription but does not keep state and tries to re-create the subscription at every `apply`.
*
* > **NOTE:** If an SNS topic and SQS queue are in different AWS accounts and different AWS regions, the subscription needs to be initiated from the account with the SQS queue but in the region of the SNS topic.
*
* > **NOTE:** You cannot unsubscribe to a subscription that is pending confirmation. If you use `email`, `email-json`, or `http`/`https` (without auto-confirmation enabled), until the subscription is confirmed (e.g., outside of this provider), AWS does not allow this provider to delete / unsubscribe the subscription. If you `destroy` an unconfirmed subscription, this provider will remove the subscription from its state but the subscription will still exist in AWS. However, if you delete an SNS topic, SNS [deletes all the subscriptions](https://docs.aws.amazon.com/sns/latest/dg/sns-delete-subscription-topic.html) associated with the topic. Also, you can import a subscription after confirmation and then have the capability to delete it.
*
* ## Example Usage
*
* ### Basic usage
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const userUpdates = new aws.sns.Topic("user_updates", {name: "user-updates-topic"});
* const sqsQueuePolicy = aws.iam.getPolicyDocumentOutput({
* policyId: "arn:aws:sqs:us-west-2:123456789012:user_updates_queue/SQSDefaultPolicy",
* statements: [{
* sid: "user_updates_sqs_target",
* effect: "Allow",
* principals: [{
* type: "Service",
* identifiers: ["sns.amazonaws.com"],
* }],
* actions: ["SQS:SendMessage"],
* resources: ["arn:aws:sqs:us-west-2:123456789012:user-updates-queue"],
* conditions: [{
* test: "ArnEquals",
* variable: "aws:SourceArn",
* values: [userUpdates.arn],
* }],
* }],
* });
* const userUpdatesQueue = new aws.sqs.Queue("user_updates_queue", {
* name: "user-updates-queue",
* policy: sqsQueuePolicy.apply(sqsQueuePolicy => sqsQueuePolicy.json),
* });
* const userUpdatesSqsTarget = new aws.sns.TopicSubscription("user_updates_sqs_target", {
* topic: userUpdates.arn,
* protocol: "sqs",
* endpoint: userUpdatesQueue.arn,
* });
* ```
*
* ### Example Cross-account Subscription
*
* You can subscribe SNS topics to SQS queues in different Amazon accounts and regions:
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const config = new pulumi.Config();
* const sns = config.getObject<any>("sns") || {
* "account-id": "111111111111",
* displayName: "example",
* name: "example-sns-topic",
* region: "us-west-1",
* "role-name": "service/service",
* };
* const sqs = config.getObject<any>("sqs") || {
* "account-id": "222222222222",
* name: "example-sqs-queue",
* region: "us-east-1",
* "role-name": "service/service",
* };
* const snsTopicPolicy = aws.iam.getPolicyDocument({
* policyId: "__default_policy_ID",
* statements: [
* {
* actions: [
* "SNS:Subscribe",
* "SNS:SetTopicAttributes",
* "SNS:RemovePermission",
* "SNS:Publish",
* "SNS:ListSubscriptionsByTopic",
* "SNS:GetTopicAttributes",
* "SNS:DeleteTopic",
* "SNS:AddPermission",
* ],
* conditions: [{
* test: "StringEquals",
* variable: "AWS:SourceOwner",
* values: [sns["account-id"]],
* }],
* effect: "Allow",
* principals: [{
* type: "AWS",
* identifiers: ["*"],
* }],
* resources: [`arn:aws:sns:${sns.region}:${sns["account-id"]}:${sns.name}`],
* sid: "__default_statement_ID",
* },
* {
* actions: [
* "SNS:Subscribe",
* "SNS:Receive",
* ],
* conditions: [{
* test: "StringLike",
* variable: "SNS:Endpoint",
* values: [`arn:aws:sqs:${sqs.region}:${sqs["account-id"]}:${sqs.name}`],
* }],
* effect: "Allow",
* principals: [{
* type: "AWS",
* identifiers: ["*"],
* }],
* resources: [`arn:aws:sns:${sns.region}:${sns["account-id"]}:${sns.name}`],
* sid: "__console_sub_0",
* },
* ],
* });
* const sqsQueuePolicy = aws.iam.getPolicyDocument({
* policyId: `arn:aws:sqs:${sqs.region}:${sqs["account-id"]}:${sqs.name}/SQSDefaultPolicy`,
* statements: [{
* sid: "example-sns-topic",
* effect: "Allow",
* principals: [{
* type: "AWS",
* identifiers: ["*"],
* }],
* actions: ["SQS:SendMessage"],
* resources: [`arn:aws:sqs:${sqs.region}:${sqs["account-id"]}:${sqs.name}`],
* conditions: [{
* test: "ArnEquals",
* variable: "aws:SourceArn",
* values: [`arn:aws:sns:${sns.region}:${sns["account-id"]}:${sns.name}`],
* }],
* }],
* });
* const snsTopic = new aws.sns.Topic("sns_topic", {
* name: sns.name,
* displayName: sns.display_name,
* policy: snsTopicPolicy.then(snsTopicPolicy => snsTopicPolicy.json),
* });
* const sqsQueue = new aws.sqs.Queue("sqs_queue", {
* name: sqs.name,
* policy: sqsQueuePolicy.then(sqsQueuePolicy => sqsQueuePolicy.json),
* });
* const snsTopicTopicSubscription = new aws.sns.TopicSubscription("sns_topic", {
* topic: snsTopic.arn,
* protocol: "sqs",
* endpoint: sqsQueue.arn,
* });
* ```
*
* ### Example with Delivery Policy
*
* This example demonstrates how to define a `deliveryPolicy` for an HTTPS subscription. Unlike the `aws.sns.Topic` resource, the `deliveryPolicy` for `aws.sns.TopicSubscription` should not be wrapped in an `"http"` object.
*
* ```typescript
* import * as pulumi from "@pulumi/pulumi";
* import * as aws from "@pulumi/aws";
*
* const exampleWithDeliveryPolicy = new aws.sns.TopicSubscription("example_with_delivery_policy", {
* topic: "arn:aws:sns:us-west-2:123456789012:my-topic",
* protocol: "https",
* endpoint: "https://example.com/endpoint",
* rawMessageDelivery: true,
* deliveryPolicy: `{
* "healthyRetryPolicy": {
* "minDelayTarget": 20,
* "maxDelayTarget": 20,
* "numRetries": 3,
* "numMaxDelayRetries": 0,
* "numNoDelayRetries": 0,
* "numMinDelayRetries": 0,
* "backoffFunction": "linear"
* },
* "sicklyRetryPolicy": null,
* "throttlePolicy": null,
* "requestPolicy": {
* "headerContentType": "text/plain; application/json"
* },
* "guaranteed": false
* }
* `,
* });
* ```
*
* ## Import
*
* Using `pulumi import`, import SNS Topic Subscriptions using the subscription `arn`. For example:
*
* ```sh
* $ pulumi import aws:sns/topicSubscription:TopicSubscription user_updates_sqs_target arn:aws:sns:us-west-2:123456789012:my-topic:8a21d249-4329-4871-acc6-7be709c6ea7f
* ```
*/
export declare class TopicSubscription extends pulumi.CustomResource {
/**
* Get an existing TopicSubscription resource's state with the given name, ID, and optional extra
* properties used to qualify the lookup.
*
* @param name The _unique_ name of the resulting resource.
* @param id The _unique_ provider ID of the resource to lookup.
* @param state Any extra arguments used during the lookup.
* @param opts Optional settings to control the behavior of the CustomResource.
*/
static get(name: string, id: pulumi.Input<pulumi.ID>, state?: TopicSubscriptionState, opts?: pulumi.CustomResourceOptions): TopicSubscription;
/**
* Returns true if the given object is an instance of TopicSubscription. This is designed to work even
* when multiple copies of the Pulumi SDK have been loaded into the same process.
*/
static isInstance(obj: any): obj is TopicSubscription;
/**
* ARN of the subscription.
*/
readonly arn: pulumi.Output<string>;
/**
* Integer indicating number of minutes to wait in retrying mode for fetching subscription arn before marking it as failure. Only applicable for http and https protocols. Default is `1`.
*/
readonly confirmationTimeoutInMinutes: pulumi.Output<number | undefined>;
/**
* Whether the subscription confirmation request was authenticated.
*/
readonly confirmationWasAuthenticated: pulumi.Output<boolean>;
/**
* JSON String with the delivery policy (retries, backoff, etc.) that will be used in the subscription - this only applies to HTTP/S subscriptions. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/DeliveryPolicies.html) for more details.
*/
readonly deliveryPolicy: pulumi.Output<string | undefined>;
/**
* Endpoint to send data to. The contents vary with the protocol. See details below.
*/
readonly endpoint: pulumi.Output<string>;
/**
* Whether the endpoint is capable of [auto confirming subscription](http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html#SendMessageToHttp.prepare) (e.g., PagerDuty). Default is `false`.
*/
readonly endpointAutoConfirms: pulumi.Output<boolean | undefined>;
/**
* JSON String with the filter policy that will be used in the subscription to filter messages seen by the target resource. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/message-filtering.html) for more details.
*/
readonly filterPolicy: pulumi.Output<string | undefined>;
/**
* Whether the `filterPolicy` applies to `MessageAttributes` (default) or `MessageBody`.
*/
readonly filterPolicyScope: pulumi.Output<string>;
/**
* AWS account ID of the subscription's owner.
*/
readonly ownerId: pulumi.Output<string>;
/**
* Whether the subscription has not been confirmed.
*/
readonly pendingConfirmation: pulumi.Output<boolean>;
/**
* Protocol to use. Valid values are: `sqs`, `sms`, `lambda`, `firehose`, and `application`. Protocols `email`, `email-json`, `http` and `https` are also valid but partially supported. See details below.
*/
readonly protocol: pulumi.Output<string>;
/**
* Whether to enable raw message delivery (the original message is directly passed, not wrapped in JSON with the original message in the message property). Default is `false`.
*/
readonly rawMessageDelivery: pulumi.Output<boolean | undefined>;
/**
* JSON String with the redrive policy that will be used in the subscription. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html#how-messages-moved-into-dead-letter-queue) for more details.
*/
readonly redrivePolicy: pulumi.Output<string | undefined>;
/**
* Region where this resource will be [managed](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints). Defaults to the Region set in the provider configuration.
*/
readonly region: pulumi.Output<string>;
/**
* JSON String with the archived message replay policy that will be used in the subscription. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/message-archiving-and-replay-subscriber.html) for more details.
*/
readonly replayPolicy: pulumi.Output<string | undefined>;
/**
* ARN of the IAM role to publish to Kinesis Data Firehose delivery stream. Refer to [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/sns-firehose-as-subscriber.html).
*/
readonly subscriptionRoleArn: pulumi.Output<string | undefined>;
/**
* ARN of the SNS topic to subscribe to.
*
* The following arguments are optional:
*/
readonly topic: pulumi.Output<string>;
/**
* Create a TopicSubscription resource with the given unique name, arguments, and options.
*
* @param name The _unique_ name of the resource.
* @param args The arguments to use to populate this resource's properties.
* @param opts A bag of options that control this resource's behavior.
*/
constructor(name: string, args: TopicSubscriptionArgs, opts?: pulumi.CustomResourceOptions);
}
/**
* Input properties used for looking up and filtering TopicSubscription resources.
*/
export interface TopicSubscriptionState {
/**
* ARN of the subscription.
*/
arn?: pulumi.Input<string>;
/**
* Integer indicating number of minutes to wait in retrying mode for fetching subscription arn before marking it as failure. Only applicable for http and https protocols. Default is `1`.
*/
confirmationTimeoutInMinutes?: pulumi.Input<number>;
/**
* Whether the subscription confirmation request was authenticated.
*/
confirmationWasAuthenticated?: pulumi.Input<boolean>;
/**
* JSON String with the delivery policy (retries, backoff, etc.) that will be used in the subscription - this only applies to HTTP/S subscriptions. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/DeliveryPolicies.html) for more details.
*/
deliveryPolicy?: pulumi.Input<string>;
/**
* Endpoint to send data to. The contents vary with the protocol. See details below.
*/
endpoint?: pulumi.Input<string>;
/**
* Whether the endpoint is capable of [auto confirming subscription](http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html#SendMessageToHttp.prepare) (e.g., PagerDuty). Default is `false`.
*/
endpointAutoConfirms?: pulumi.Input<boolean>;
/**
* JSON String with the filter policy that will be used in the subscription to filter messages seen by the target resource. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/message-filtering.html) for more details.
*/
filterPolicy?: pulumi.Input<string>;
/**
* Whether the `filterPolicy` applies to `MessageAttributes` (default) or `MessageBody`.
*/
filterPolicyScope?: pulumi.Input<string>;
/**
* AWS account ID of the subscription's owner.
*/
ownerId?: pulumi.Input<string>;
/**
* Whether the subscription has not been confirmed.
*/
pendingConfirmation?: pulumi.Input<boolean>;
/**
* Protocol to use. Valid values are: `sqs`, `sms`, `lambda`, `firehose`, and `application`. Protocols `email`, `email-json`, `http` and `https` are also valid but partially supported. See details below.
*/
protocol?: pulumi.Input<string>;
/**
* Whether to enable raw message delivery (the original message is directly passed, not wrapped in JSON with the original message in the message property). Default is `false`.
*/
rawMessageDelivery?: pulumi.Input<boolean>;
/**
* JSON String with the redrive policy that will be used in the subscription. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html#how-messages-moved-into-dead-letter-queue) for more details.
*/
redrivePolicy?: pulumi.Input<string>;
/**
* Region where this resource will be [managed](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints). Defaults to the Region set in the provider configuration.
*/
region?: pulumi.Input<string>;
/**
* JSON String with the archived message replay policy that will be used in the subscription. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/message-archiving-and-replay-subscriber.html) for more details.
*/
replayPolicy?: pulumi.Input<string>;
/**
* ARN of the IAM role to publish to Kinesis Data Firehose delivery stream. Refer to [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/sns-firehose-as-subscriber.html).
*/
subscriptionRoleArn?: pulumi.Input<string>;
/**
* ARN of the SNS topic to subscribe to.
*
* The following arguments are optional:
*/
topic?: pulumi.Input<string | Topic>;
}
/**
* The set of arguments for constructing a TopicSubscription resource.
*/
export interface TopicSubscriptionArgs {
/**
* Integer indicating number of minutes to wait in retrying mode for fetching subscription arn before marking it as failure. Only applicable for http and https protocols. Default is `1`.
*/
confirmationTimeoutInMinutes?: pulumi.Input<number>;
/**
* JSON String with the delivery policy (retries, backoff, etc.) that will be used in the subscription - this only applies to HTTP/S subscriptions. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/DeliveryPolicies.html) for more details.
*/
deliveryPolicy?: pulumi.Input<string>;
/**
* Endpoint to send data to. The contents vary with the protocol. See details below.
*/
endpoint: pulumi.Input<string>;
/**
* Whether the endpoint is capable of [auto confirming subscription](http://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.html#SendMessageToHttp.prepare) (e.g., PagerDuty). Default is `false`.
*/
endpointAutoConfirms?: pulumi.Input<boolean>;
/**
* JSON String with the filter policy that will be used in the subscription to filter messages seen by the target resource. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/message-filtering.html) for more details.
*/
filterPolicy?: pulumi.Input<string>;
/**
* Whether the `filterPolicy` applies to `MessageAttributes` (default) or `MessageBody`.
*/
filterPolicyScope?: pulumi.Input<string>;
/**
* Protocol to use. Valid values are: `sqs`, `sms`, `lambda`, `firehose`, and `application`. Protocols `email`, `email-json`, `http` and `https` are also valid but partially supported. See details below.
*/
protocol: pulumi.Input<string>;
/**
* Whether to enable raw message delivery (the original message is directly passed, not wrapped in JSON with the original message in the message property). Default is `false`.
*/
rawMessageDelivery?: pulumi.Input<boolean>;
/**
* JSON String with the redrive policy that will be used in the subscription. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/sns-dead-letter-queues.html#how-messages-moved-into-dead-letter-queue) for more details.
*/
redrivePolicy?: pulumi.Input<string>;
/**
* Region where this resource will be [managed](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints). Defaults to the Region set in the provider configuration.
*/
region?: pulumi.Input<string>;
/**
* JSON String with the archived message replay policy that will be used in the subscription. Refer to the [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/message-archiving-and-replay-subscriber.html) for more details.
*/
replayPolicy?: pulumi.Input<string>;
/**
* ARN of the IAM role to publish to Kinesis Data Firehose delivery stream. Refer to [SNS docs](https://docs.aws.amazon.com/sns/latest/dg/sns-firehose-as-subscriber.html).
*/
subscriptionRoleArn?: pulumi.Input<string>;
/**
* ARN of the SNS topic to subscribe to.
*
* The following arguments are optional:
*/
topic: pulumi.Input<string | Topic>;
}