Topics & Subscriptions

Topics and subscriptions are the two fundamental resources in Google Cloud Pub/Sub. Topics are where publishers send messages, and subscriptions are how subscribers receive them. Understanding how to create, configure, and manage these resources is essential for building reliable messaging systems.

---

Topics in Depth

A topic is a named resource that acts as a message channel. Publishers send messages to a topic, and Pub/Sub distributes copies of each message to all subscriptions attached to that topic.

Creating and Managing Topics

# Create a topic
gcloud pubsub topics create orders-topic

# Create a topic with a schema for message validation
gcloud pubsub topics create orders-topic \
  --schema=orders-schema \
  --message-encoding=json

# Add labels for organisation and billing
gcloud pubsub topics update orders-topic \
  --update-labels=team=payments,env=production

# Delete a topic (does not delete subscriptions)
gcloud pubsub topics delete orders-topic

Topic Configuration

Setting	Description	Default
Message retention	How long Pub/Sub retains published messages	7 days (max 31 days)
Schema	Validates message format (Avro, Protocol Buffers, or JSON)	None
Encryption	CMEK (Customer-Managed Encryption Keys)	Google-managed
Labels	Key-value pairs for organising resources	None

Message Retention on Topics

By default, Pub/Sub retains messages for 7 days. You can configure retention up to 31 days. Topic-level retention allows subscribers to seek back to a previous point in time and replay messages — even if they were already acknowledged.

# Set message retention to 14 days
gcloud pubsub topics update orders-topic \
  --message-retention-duration=14d

Schemas

Schemas enforce a contract between publishers and subscribers. When a schema is attached to a topic, Pub/Sub validates every published message against the schema and rejects messages that do not conform.

Supported schema formats:

• Avro — compact binary format with schema evolution support
• Protocol Buffers — Google's binary serialisation format
• JSON Schema — human-readable format for JSON payloads

# Create a schema
gcloud pubsub schemas create orders-schema \
  --type=avro \
  --definition-file=orders.avsc

# Attach the schema to a topic
gcloud pubsub topics create orders-topic \
  --schema=orders-schema \
  --message-encoding=json

---

Subscriptions in Depth

A subscription represents the stream of messages from a topic to a specific subscriber. Each subscription is independent — it has its own message backlog, acknowledgement state, and delivery configuration.

Subscription Types

Type	How It Works	Best For
Pull	Subscriber polls Pub/Sub for messages	Long-running workers, batch processing
Push	Pub/Sub sends messages to an HTTPS endpoint	Serverless, Cloud Run, App Engine
BigQuery	Pub/Sub writes messages directly to a BigQuery table	Analytics, data warehousing
Cloud Storage	Pub/Sub writes messages as files in a GCS bucket	Archival, compliance

Creating Subscriptions

# Pull subscription with custom ack deadline
gcloud pubsub subscriptions create orders-pull-sub \
  --topic=orders-topic \
  --ack-deadline=60

# Push subscription to a Cloud Run service
gcloud pubsub subscriptions create orders-push-sub \
  --topic=orders-topic \
  --push-endpoint=https://orders-service-abc123.run.app/push \
  --push-auth-service-account=pubsub-invoker@my-project.iam.gserviceaccount.com

# BigQuery subscription (writes directly to a table)
gcloud pubsub subscriptions create orders-bq-sub \
  --topic=orders-topic \
  --bigquery-table=my-project:orders_dataset.orders_table