sns_topic – Manages AWS SNS topics and subscriptions

From Get docs
Ansible/docs/2.8/modules/sns topic module


sns_topic – Manages AWS SNS topics and subscriptions

New in version 2.0.


Synopsis

  • The sns_topic module allows you to create, delete, and manage subscriptions for AWS SNS topics. As of 2.6, this module can be use to subscribe and unsubscribe to topics outside of your AWS account.

Requirements

The below requirements are needed on the host that executes this module.

  • boto
  • python >= 2.6

Parameters

Parameter Choices/Defaults Comments

aws_access_key

string

AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.


aliases: ec2_access_key, access_key

aws_secret_key

string

AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.


aliases: ec2_secret_key, secret_key

debug_botocore_endpoint_logs

boolean

added in 2.8

  • no

  • yes

Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action" API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used.

delivery_policy

-

Delivery policy to apply to the SNS topic

display_name

-

Display name of the topic

ec2_url

string

Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used.

name

- / required

The name or ARN of the SNS topic to manage

policy

-

Policy to apply to the SNS topic

profile

string

Uses a boto profile. Only works with boto >= 2.24.0.

purge_subscriptions

boolean

  • no
  • yes

Whether to purge any subscriptions not listed here. NOTE: AWS does not allow you to purge any PendingConfirmation subscriptions, so if any exist and would be purged, they are silently skipped. This means that somebody could come back later and confirm the subscription. Sorry. Blame Amazon.

region

string

The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region


aliases: aws_region, ec2_region

security_token

string

AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.


aliases: access_token

state

-

  • absent
  • present

Whether to create or destroy an SNS topic

subscriptions

-

Default:

[]

List of subscriptions to apply to the topic. Note that AWS requires subscriptions to be confirmed, so you will need to confirm any new subscriptions.

endpoint

- / required

Endpoint of subscription

protocol

- / required

Protocol of subscription

validate_certs

boolean

  • no
  • yes

When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.



Notes

Note

  • If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence AWS_URL or EC2_URL, AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY or EC2_ACCESS_KEY, AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY or EC2_SECRET_KEY, AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN, AWS_REGION or EC2_REGION
  • Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html
  • AWS_REGION or EC2_REGION can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file


Examples

- name: Create alarm SNS topic
  sns_topic:
    name: "alarms"
    state: present
    display_name: "alarm SNS topic"
    delivery_policy:
      http:
        defaultHealthyRetryPolicy:
            minDelayTarget: 2
            maxDelayTarget: 4
            numRetries: 3
            numMaxDelayRetries: 5
            backoffFunction: "<linear|arithmetic|geometric|exponential>"
        disableSubscriptionOverrides: True
        defaultThrottlePolicy:
            maxReceivesPerSecond: 10
    subscriptions:
      - endpoint: "[email protected]"
        protocol: "email"
      - endpoint: "my_mobile_number"
        protocol: "sms"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description

sns_arn

string

always

The ARN of the topic you are modifying


Sample:

arn:aws:sns:us-east-2:111111111111:my_topic_name

sns_topic

complex

always

Dict of sns topic details


attributes_set

list

always

list of attributes set during this run


check_mode

boolean

always

whether check mode was on


delivery_policy

string

when topic is owned by this AWS account

Delivery policy for the SNS topic


Sample:

{"http":{"defaultHealthyRetryPolicy":{"minDelayTarget":20,"maxDelayTarget":20,"numRetries":3,"numMaxDelayRetries":0, "numNoDelayRetries":0,"numMinDelayRetries":0,"backoffFunction":"linear"},"disableSubscriptionOverrides":false}}

display_name

string

when topic is owned by this AWS account

Display name for SNS topic


Sample:

My topic name

name

string

always

Topic name


Sample:

ansible-test-dummy-topic

owner

string

when topic is owned by this AWS account

AWS account that owns the topic


Sample:

111111111111

policy

string

when topic is owned by this AWS account

Policy for the SNS topic


Sample:

{"Version":"2012-10-17","Id":"SomePolicyId","Statement":[{"Sid":"ANewSid","Effect":"Allow","Principal":{"AWS":"arn:aws:iam::111111111111:root"}, "Action":"sns:Subscribe","Resource":"arn:aws:sns:us-east-2:111111111111:ansible-test-dummy-topic","Condition":{"StringEquals":{"sns:Protocol":"email"}}}]}

state

string

always

whether the topic is present or absent


Sample:

present

subscriptions

list

always

List of subscribers to the topic in this AWS account


subscriptions_added

list

always

List of subscribers added in this run


subscriptions_confirmed

string

when topic is owned by this AWS account

Count of confirmed subscriptions


Sample:

0

subscriptions_deleted

string

when topic is owned by this AWS account

Count of deleted subscriptions


Sample:

0

subscriptions_existing

list

always

List of existing subscriptions


subscriptions_new

list

always

List of new subscriptions


subscriptions_pending

string

when topic is owned by this AWS account

Count of pending subscriptions


Sample:

0

subscriptions_purge

boolean

always

Whether or not purge_subscriptions was set


Sample:

True

topic_arn

string

when topic is owned by this AWS account

ARN of the SNS topic (equivalent to sns_arn)


Sample:

arn:aws:sns:us-east-2:111111111111:ansible-test-dummy-topic

topic_created

boolean

always

Whether the topic was created


topic_deleted

boolean

always

Whether the topic was deleted





Status

Authors

  • Joel Thompson (@joelthompson)
  • Fernando Jose Pando (@nand0p)
  • Will Thames (@willthames)

Hint

If you notice any issues in this documentation you can edit this document to improve it.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/sns_topic_module.html