Info icon
End of Life Notice: For Trend Cloud One™ - Conformity Customers, Conformity will reach its End of Sale on “July 31st, 2025” and End of Life “July 31st, 2026”. The same capabilities and much more is available in TrendAI Vision One™ Cloud Risk Management. For details, please refer to Upgrade to TrendAI Vision One™
Logo of TrendAI
Use the Knowledge Base AI to help improve your Cloud Posture

Enable Dead Lettering for Google Pub/Sub Subscriptions

TrendAI Vision One™ provides continuous assurance that gives peace of mind for your cloud infrastructure, delivering over 1400 automated best practice checks.

Risk Level: Low (generally tolerable level of risk)

Ensure that each Google Cloud Pub/Sub subscription is configured to use a dead-letter topic, also known as dead-letter queue, in order to capture undeliverable messages. Your Pub/Sub subscriptions are configured with a maximum number of delivery attempts. When a message cannot be delivered, it is republished to the specified dead-letter topic.

Reliability
Operational
excellence

When a message can't be acknowledged, Google Cloud Pub/Sub service can forward the message to a dead-letter topic that stores the message for later access. Configuring dead-letter topics (queues) for your Pub/Sub subscriptions can make your cloud applications more resilient and durable by capturing and storing messages that can't be delivered due to client errors or server errors for further analysis or reprocessing.

Audit

To determine if dead lettering is enabled for all your Pub/Sub subscriptions, perform the following operations:

Using GCP Console

  1. Sign in to Google Cloud Management Console.

  2. Select the Google Cloud Platform (GCP) project that you want to access from the console top navigation bar.

  3. Navigate to Pub/Sub console at https://console.cloud.google.com/cloudpubsub.

  4. In the navigation panel, select Subscriptions to access the Pub/Sub subscriptions created for the selected GCP project.

  5. Click on the identifier (ID) of the subscription that you want to examine.

  6. In the Subscription details section, check the Dead lettering configuration setting status. If the Dead lettering setting status is set to Disabled, the selected Google Cloud Pub/Sub subscription does not have a dead-letter topic configured to capture messages that can't be delivered successfully to subscribers.

  7. Repeat step no. 5 and 6 for each Pub/Sub subscription available for the selected project.

  8. Repeat steps no. 2 – 7 for each project deployed within your Google Cloud account.

Using GCP CLI

  1. Run projects list command (Windows/macOS/Linux) using custom query filters to list the IDs of all the Google Cloud Platform (GCP) projects available in your cloud account:

    gcloud projects list
				--format="table(projectId)"

  2. The command output should return the requested GCP project identifiers:

    PROJECT_ID
cc-dataflow-project-123123
cc-analytics-project-112233

  3. Run pubsub subscriptions list command (Windows/macOS/Linux) using custom filtering to describe the fully qualified identifier of each Pub/Sub subscription created within the selected Google Cloud project:

    gcloud pubsub subscriptions list
				--project cc-dataflow-project-123123
				--format="table(name)"

  4. The command output should return the requested subscription identifier(s):

    NAME
projects/cc-dataflow-project-123123/subscriptions/cc-customer-subscription
projects/cc-dataflow-project-123123/subscriptions/cc-web-data-subscription

  5. Run pubsub subscriptions describe command (Windows/macOS/Linux) using the fully qualified identifier of the Google Cloud Pub/Sub subscription that you want to examine as identifier parameter and custom query filters, to describe the identifier (ID) of the dead-letter topic configured for the selected subscription:

    gcloud pubsub subscriptions describe projects/cc-dataflow-project-123123/subscriptions/cc-customer-subscription
				--format="json(deadLetterPolicy.deadLetterTopic)"

  6. The command output should return the requested topic ID:

    null

    If the pubsub subscriptions describe command output returns null, as shown in the example above, the selected Google Cloud Pub/Sub subscription does not have a dead-letter topic configured to capture undeliverable messages.

  7. Repeat step no. 5 and 6 for each Pub/Sub subscription created for the selected project.

  8. Repeat steps no. 3 – 7 for each GCP project deployed within your Google Cloud account.

Remediation / Resolution

To enable and configure dead lettering for your Google Cloud Pub/Sub subscriptions, perform the following operations:

Using GCP Console

  1. Sign in to Google Cloud Management Console.

  2. Select the Google Cloud Platform (GCP) project that you want to access from the console top navigation bar.

  3. The best practice is to use a dead-letter topic that is different than the Pub/Sub topic(s) you are subscribing to. Navigate to Pub/Sub console at https://console.cloud.google.com/cloudpubsub and click on the CREATE TOPIC button from the dashboard top menu to initiate the dead-letter topic setup process.

  4. Within Create a topic configuration box, perform the following actions:

    1. Provide a unique identifier for the new topic in the Topic ID box.
    2. In the Encryption section, choose Customer-managed key, and select your own CMK from the Select a customer-managed key dropdown list.
    3. Inside "The service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com service account does not have permissions to encrypt/decrypt with the selected key." box, click Grant to grant the specified service account the required IAM role on the selected CMK.
    4. Click CREATE TOPIC to deploy your new Pub/Sub dead-letter topic.

  5. The dead-letter topic should have at least one subscription so that dead-lettered messages will not be lost. Click on the newly created Pub/Sub topic, select the SUBSCRIPTIONS tab, then click CREATE SUBSCRIPTION to create the required subscription.

  6. In the navigation panel, select Subscriptions to access the Pub/Sub subscriptions available for the selected GCP project.

  7. Click on the ID of the subscription that you want to reconfigure, and choose the EDIT button from the dashboard top menu.

  8. On the Edit subscription page, in the Dead lettering section, select Enable dead lettering checkbox, and choose the dead-letter topic created at the previous steps from the Select a dead letter topic dropdown list. (Optional) In the Maximum delivery attempts field, specify an integer between 5 and 100, based on your application needs. Click UPDATE to apply the changes.

  9. Once the configuration changes are applied to the selected subscription, select the DEAD LETTERING tab, and click on the GRANT PUBLISHER ROLE and GRANT SUBSCRIBER ROLE to assign the Publisher and Subscriber roles. The Pub/Sub service account for the selected GCP project needs the Publisher role to publish dead-lettered messages to the specified topic and the Subscriber role to forward messages from this subscription to the dead-letter topic. The selected subscription can dead letter messages to the new dead-letter topic once it exceeds the specified delivery attempt count.

  10. Repeat steps no. 7 – 9 to enable dead lettering for other Pub/Sub subscriptions available within the selected project.

  11. Repeat steps no. 2 – 10 for each GCP project available in your Google Cloud account.

Using GCP CLI

  1. The best practice is to use a dead-letter topic that is different than the Pub/Sub topic(s) you are subscribing to. Run pubsub topics create command (Windows/macOS/Linux) using the name of the GCP project that you want to access as identifier parameter, to create a new Pub/Sub dead-letter topic that will capture undeliverable messages:

    gcloud pubsub topics create cc-dead-letter-topic
				--project cc-dataflow-project-123123

  2. The command output should return the full resource identifier of the newly created topic:

    Created topic [projects/cc-dataflow-project-123123/topics/cc-dead-letter-topic].

  3. The new dead-letter topic should have at least one subscription so that dead-lettered messages will not be lost. Run pubsub subscriptions create command (Windows/macOS/Linux) to create the required subscription for the newly created Pub/Sub dead-letter topic:

    gcloud pubsub subscriptions create cc-dead-letter-subscription
				--topic=cc-dead-letter-topic
				--topic-project=cc-dataflow-project-123123

  4. The command output should return the resource ID of the new Pub/Sub subscription:

    Created subscription [projects/cc-dataflow-project-123123/subscriptions/cc-dead-letter-subscription].

  5. Run pubsub subscriptions update command (Windows/macOS/Linux) using the ID of the Pub/Sub subscription that you want to reconfigure as identifier parameter, to enable dead lettering for the selected subscription:

    gcloud pubsub subscriptions update cc-customer-subscription
				--dead-letter-topic=cc-dead-letter-topic
				--max-delivery-attempts=10
				--dead-letter-topic-project=cc-dataflow-project-123123

  6. The command output should return the URL of the reconfigured Pub/Sub subscription:

    Updated subscription [projects/cc-dataflow-project-123123/subscriptions/cc-customer-subscription].

  7. The Pub/Sub service account for the selected Google Cloud project needs the publisher role to publish dead-lettered messages to the newly created dead-letter topic. To grant Pub/Sub permission to publish messages to the specified topic, run pubsub topics add-iam-policy-binding command (Windows/macOS/Linux). Replace <project-number> with your own GCP project number:

    gcloud pubsub topics add-iam-policy-binding cc-dead-letter-topic
				--member="serviceAccount:service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com"
				--role="roles/pubsub.publisher"

  8. The command output should return the Google Cloud IAM policy binding metadata:

    Updated IAM policy for topic [cc-dead-letter-topic].
bindings:
- members:
				- serviceAccount:service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com
				role: roles/pubsub.publisher
etag: abcdabcdabcd
version: 1

  9. The Pub/Sub service account for the selected Google Cloud project needs the subscriber role to forward messages from the reconfigured subscription to the dead-letter topic. To grant Pub/Sub permission to acknowledge forwarded messages and remove them from the specified subscription, run pubsub subscriptions add-iam-policy-binding command (Windows/macOS/Linux). Replace <project-number> with your own GCP project number:

    gcloud pubsub subscriptions add-iam-policy-binding cc-customer-subscription
				--member="serviceAccount:service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com"
				--role="roles/pubsub.subscriber"

  10. The command output should return the Google Cloud IAM policy binding metadata:

    Updated IAM policy for subscription [cc-customer-subscription].
bindings:
- members:
				- serviceAccount:service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com
				role: roles/pubsub.subscriber
etag: abcdabcdabcd
version: 1

  11. Repeat steps no. 5 – 10 to enable dead lettering for other Pub/Sub subscriptions created for the selected project.

  12. Repeat steps no. 1 – 11 for each GCP project deployed in your Google Cloud account.

References

Publication date May 10, 2021

Related CloudPubSub rules