# gcpubsub – Create and Delete Topics/Subscriptions, Publish and pull messages on PubSub

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- Create and Delete Topics/Subscriptions, Publish and pull messages on PubSub. See https://cloud.google.com/pubsub/docs for an overview.

## Requirements

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

- google-auth >= 0.5.0
- google-cloud-pubsub >= 0.22.0

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
ack_deadline - |  | Subfield of subscription. Not required. Default deadline for subscriptions to ACK the message before it is resent. See examples.
name - |  | Subfield of subscription. Required if subscription is specified. See examples.
publish - |  | List of dictionaries describing messages and attributes to be published. Dictionary is in message(str):attributes(dict) format. Only message is required.

pull
-

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 - |  | 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
-

Choices:
- absent
- present ←

State of the topic or queue.
Applies to the most granular resource.
If subscription isspecified we remove it.
If only topic is specified, that is what is removed.
NOTE - A topic can be removed without first removing the subscription.

subscription - |  | Dictionary containing a subscription 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 - / required |  | GCP pubsub topic name. Only the name, not the full path, is required.

## Notes

Note

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

## Examples

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

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

    # Setting absent will keep the messages from being sent
    - name: Publish multiple messages, with attributes (key:value available with the message)
      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

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

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

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

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

    # only pull keyword is required.
    - name: Pull messages from subscription
      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, the following are the fields unique to this module:

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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Tom Melendez (@supertom) <tom@supertom.com>

Hint

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