W3cubDocs

/Ansible

gcpubsub - Create and Delete Topics/Subscriptions, Publish and pull messages on PubSub.

New in version 2.3.

Synopsis

Requirements (on host that executes module)

  • python >= 2.6
  • google-auth >= 0.5.0
  • google-cloud-pubsub >= 0.22.0

Options

parameter required default choices comments
ack_deadline
 no
Subfield of subscription. Not required. Default deadline for subscriptions to ACK the message before it is resent. See examples.
name
 no
Subfield of subscription. Required if subscription is specified. See examples.
publish
 no
List of dictionaries describing messages and attributes to be published. Dictionary is in message(str):attributes(dict) format. Only message is required.
pull
 no
Subfield of subscription. Not required. If specified, messages will be retrieved from topic via the provided subscription name. max_messages (int; default None; max number of messages to pull), message_ack (bool; default False; acknowledge the message) and return_immediately (bool; default True, don't wait for messages to appear). If the messages are acknowledged, changed is set to True, otherwise, changed is False.
push_endpoint
 no
Subfield of subscription. Not required. If specified, message will be sent to an endpoint. See https://cloud.google.com/pubsub/docs/advanced#push_endpoints for more information.
state
 no present
State of the topic or queue (absent, present). Applies to the most granular resource. Remove the most granular resource. If subcription is specified we remove it. If only topic is specified, that is what is removed. Note that a topic can be removed without first removing the subscription.
subscription
 no
Dictionary containing a subscripton name associated with a topic (required), along with optional ack_deadline, push_endpoint and pull. For pulling from a subscription, message_ack (bool), max_messages (int) and return_immediate are available as subfields. See subfields name, push_endpoint and ack_deadline for more information.
topic
 yes
GCP pubsub topic name. Only the name, not the full path, is required.

Examples

# Create a topic and publish a message to it
# (Message will be pushed; there is no check to see if the message was pushed before
# Topics:
## Create Topic
gcpubsub:
  topic: ansible-topic-example
  state: present

## Delete Topic
### Subscriptions associated with topic are not deleted.
gcpubsub:
  topic: ansible-topic-example
  state: absent

## Messages: publish multiple messages, with attributes (key:value available with the message)
### setting absent will keep the messages from being sent
gcpubsub:
  topic: "{{ topic_name }}"
  state: present
  publish:
    - message: "this is message 1"
      attributes:
        mykey1: myvalue
        mykey2: myvalu2
        mykey3: myvalue3
    - message: "this is message 2"
      attributes:
        server: prod
        sla: "99.9999"
        owner: fred

# Subscriptions
## Create Subscription (pull)
gcpubsub:
  topic: ansible-topic-example
  subscription:
  - name: mysub
  state: present

## Create Subscription with ack_deadline and push endpoint
### pull is default, ack_deadline is not required
gcpubsub:
  topic: ansible-topic-example
  subscription:
  - name: mysub
    ack_deadline: "60"
    push_endpoint: http://pushendpoint.example.com
  state: present

## Subscription change from push to pull
### setting push_endpoint to "None" converts subscription to pull.
gcpubsub:
  topic: ansible-topic-example
  subscription:
    name: mysub
    push_endpoint: "None"

## Delete subscription
### Topic will not be deleted
gcpubsub:
  topic: ansible-topic-example
  subscription:
  - name: mysub
  state: absent

## Pull messages from subscription
### only pull keyword is required.
gcpubsub:
  topic: ansible-topic-example
  subscription:
    name: ansible-topic-example-sub
    pull:
      message_ack: yes
      max_messages: "100"

Return Values

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

name description returned type sample
topic
Name of topic.
 Always str mytopic
state
The state of the topic or subscription. Value will be either 'absent' or 'present'.
 Always str present
publish
List of dictionaries describing messages and attributes to be published. Dictionary is in message(str):attributes(dict) format. Only message is required.
 Only when specified list publish: ['message': 'my message', attributes: {'key1': 'value1'}]
pulled_messages
list of dictionaries containing message info. Fields are ack_id, attributes, data, message_id.
 Only when subscription.pull is specified list [{'attributes': {'...': None, 'key1': 'val1'}, 'ack_id': 'XkASTCcYREl...', 'data': 'this is message 1', 'message_id': '49107464153705'}, '..']
subscription
Name of subscription.
 When subscription fields are specified str mysubscription

Notes

Note

  • Subscription pull happens before publish. You cannot publish and pull in the same task.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2017 Michael DeHaan
© 2017 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/gcpubsub_module.html