Gcp Pubsub

---
name: gcp-pubsub
description: "Expert coverage of Google Cloud Pub/Sub managed messaging service: topics, subscriptions (pull, push, BigQuery, Cloud Storage), ordering keys, exactly-once delivery, dead-letter topics, schemas, snapshots, seek, and monitoring. Use for \"GCP Pub/Sub\", \"Google Pub/Sub\", \"Cloud Pub/Sub\", \"Pub/Sub topic\", \"Pub/Sub subscription\", \"pull subscription\", \"push subscription\", \"BigQuery subscription\", \"Cloud Storage subscription\", \"ordering key\", \"exactly-once Pub/Sub\", \"dead letter topic\", \"DLT\", \"Pub/Sub schema\", \"Pub/Sub snapshot\", \"seek\", \"gcloud pubsub\", \"message filter Pub/Sub\", \"ack deadline\", \"Pub/Sub flow control\", \"streaming pull\". Do NOT use for general GCP architecture or non-messaging resource provisioning -- that's the `cloud-platforms` plugin."
license: MIT
---

# GCP Pub/Sub

This skill covers Google Cloud Pub/Sub, a fully managed serverless messaging service, including:

- Topics (message ordering, schema validation, retention, CMEK encryption)
- Subscription types: Pull (streaming pull), Push (HTTPS webhooks), BigQuery export, Cloud Storage export
- Message ordering (ordering keys, per-key throughput, hot key mitigation)
- Exactly-once delivery (pull subscriptions only, regional requirements)
- Dead-letter topics (DLT with max delivery attempts, IAM requirements)
- Message filtering (attribute-based immutable filters)
- Schema validation (Avro, Protocol Buffers, evolution, revisions)
- Snapshots and seek (point-in-time replay, backlog purge)
- Flow control (subscriber and publisher side)
- Monitoring (Cloud Monitoring metrics, delivery latency health score)
- IAM, VPC Service Controls, CMEK

## How to Approach Tasks

1. **Classify** the request:
   - **Architecture / design** -- Load `references/architecture.md` for topics, subscription types, ordering, exactly-once, DLT, schemas
   - **Best practices** -- Load `references/best-practices.md` for subscription selection, ordering key design, ack deadline tuning, flow control, cost optimization
   - **Troubleshooting** -- Load `references/diagnostics.md` for unacked buildup, delivery latency, DLT analysis, push endpoint errors

2. **Recommend** -- Provide actionable guidance with `gcloud pubsub` commands, Terraform examples, and SDK patterns.

## Core Architecture

### Per-Message Leasing (Not Partitioned)
Each message is individually leased to a subscriber. No partition management. Any subscriber can receive any message. Serverless auto-scaling.

### Topics
Named resource for publishing. Optional: message retention (10 min to 31 days), ordering (immutable at creation), schema validation, CMEK.

### Subscription Types
- **Pull:** Client requests messages. Best for high throughput, exactly-once. Streaming pull for lowest latency.
- **Push:** Pub/Sub sends HTTP POST to HTTPS endpoint. Best for Cloud Run, Cloud Functions.
- **BigQuery:** Direct export via Storage Write API. Schema mapping.
- **Cloud Storage:** Batch messages into files (text or Avro).

### Dead-Letter Topics
Messages forwarded after 5-100 delivery attempts. Requires IAM permissions for Pub/Sub service account.

## Anti-Patterns

| Anti-Pattern | Why It Fails | Instead |
|---|---|---|
| Ordering with low-cardinality keys | Hot keys block progress; 1 MBps per key limit | Use high-cardinality keys (per entity) |
| Acking before processing complete | Recovery requires seek; messages lost | Ack only after successful processing |
| Push to unreliable endpoint | 5xx triggers exponential backoff; delivery stalls | Use pull for unreliable consumers; fix endpoint |
| Large message retention without monitoring | Storage costs accumulate silently | Set appropriate retention; monitor orphaned subs |
| Ignoring ack deadline expiration | Messages redelivered; duplicate processing | Match ack deadline to P99 processing time |

## Reference Files

- `references/architecture.md` -- Topics, subscription types (pull/push/BigQuery/Cloud Storage), ordering keys, exactly-once, DLT, schemas, snapshots/seek, flow control
- `references/best-practices.md` -- Subscription selection, ordering key design, ack deadline tuning, flow control, retry policies, schema evolution, cost optimization
- `references/diagnostics.md` -- Unacked message buildup, delivery latency health score, DLT analysis, push endpoint errors, Cloud Monitoring metrics, alerting setup

## Cross-References

- The `overview` skill -- cross-broker comparisons and event-driven architecture design