• Topic — A named resource to which producers (publishers) send messages. A topic is the entry point for data flowing into the system. Topics may optionally enforce a schema on incoming messages.
• Subscription — A named resource representing a stream of messages from a single topic to be delivered to a subscribing application. Each subscription receives its own independent copy of every message published to the topic after the subscription was created. A topic can have many subscriptions; this is the fan-out mechanism.
• Pull delivery — The subscriber application explicitly requests messages from the subscription on its own schedule (using a client library, the CLI, or a streaming pull connection). Pull is well suited to high-throughput batch consumers and workers that control their own concurrency. Messages must be explicitly acknowledged (acked) after successful processing.
• Push delivery — Pub/Sub proactively sends each message as an HTTPS POST request to a configured endpoint (for example a Cloud Run service, Cloud Functions function, or any publicly reachable HTTPS URL). The endpoint acknowledges a message by returning a success HTTP status (

  102

  ,

  200

  ,

  201

  ,

  202

  , or

  204

  ). Push is well suited to serverless consumers and webhook-style integrations.
• Acknowledgement (ack) and ack deadline — A consumer must acknowledge a message to signal successful processing. If the message is not acked within the subscription's ack deadline, Pub/Sub redelivers it. This at-least-once delivery model means consumers must be designed to be idempotent.
• Dead Letter Topic (DLT) — A topic to which messages are forwarded after a subscription fails to deliver them more than a configured maximum number of times (

  --max-delivery-attempts

  ). Dead lettering isolates "poison" messages so they stop blocking healthy traffic and can be inspected or reprocessed later. The Pub/Sub service account must have permission to publish to the dead letter topic and to subscribe to the source subscription.
• Schema — An optional, versioned definition (Avro or Protocol Buffer) that constrains the structure of messages published to a topic. When a topic is associated with a schema and an encoding (

  JSON

  or

  BINARY

  ), Pub/Sub validates every published message and rejects non-conforming payloads. Schemas provide a contract between producers and consumers and prevent malformed data from entering the pipeline.

1. Enable the Pub/Sub API. The

   pubsub.googleapis.com

   service must be enabled on the target project.

   gcloud services enable pubsub.googleapis.com --project=PROJECT_ID

2. Install and update the gcloud CLI. Operations in this skill assume a recent Google Cloud CLI. Confirm it is installed and current.

   gcloud version
   gcloud components update --quiet

3. Authorize the CLI. Authenticate with an identity (user or service account) that holds the required roles described below.

   gcloud auth login
   gcloud config set project PROJECT_ID

   For automated or non-interactive environments, prefer Application Default Credentials backed by a dedicated service account:

   gcloud auth activate-service-account --key-file=KEY_FILE_PATH

4. Confirm the active project and account. Always verify the execution context before mutating resources.

   gcloud config list --format="value(core.project,core.account)"

roles/pubsub.admin

roles/pubsub.publisher

roles/pubsub.subscriber

roles/pubsub.viewer

roles/iam.serviceAccountUser

• Push subscriptions that call private services (for example an authenticated Cloud Run endpoint) require that the push service account is granted the invoker role on the target service (for example

  roles/run.invoker

  ), in addition to

  roles/iam.serviceAccountUser

  on that service account for the configuring identity.
• Dead letter delivery requires the Pub/Sub service agent (

  service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com

  ) to hold

  roles/pubsub.publisher

  on the dead letter topic and

  roles/pubsub.subscriber

  on the source subscription.

1. Configuration Parameters

undefined

avro

protocol-buffer

json

gcloud pubsub schemas create --type=json

--message-encoding

1. A schema attached to the topic (the data contract).
2. The topic's

   schemaSettings.encoding

   set to

   json

   (messages validated as JSON).

• "Schema is AVRO but I need JSON": That is a category error. AVRO is the schema type; JSON is the message encoding. Keep the AVRO schema and set the topic's

  --message-encoding=json

  . Do not try to change the schema type.
• Encoding shows empty / BINARY: the topic was created without

  --message-encoding=json

  (or without

  --schema

  ). Re-bind with

  gcloud pubsub topics update --schema=... --message-encoding=json

  .

• Verify resource names match requirements: Cross-reference the exact names of the Schema, Topic, and Subscription in the prompt or spec. Do not assume names.
• Verify labels are applied: If the prompt requests labels (e.g.

  windtunnel-eval

  ), verify they are present on both the Topic and Subscription.
• Verify resource existence: Run

  describe

  commands for the Schema, Topic, and Subscription and confirm the outputs show

  state: ACTIVE

  (for schema) and correct configurations.

• Before running any mutating command, restate in plain language what the command will do and to which resource. Confirm the resource name, the project, and the effect.
• Use

  --dry-run

  where the subcommand supports it, or run the read-only

  describe

  /

  list

  equivalent first to confirm the current state.
• Never execute a command whose effect you cannot precisely predict. If the outcome is ambiguous, stop and validate first.

• --limit

  — Cap the number of results when listing or pulling. For example,

  gcloud pubsub subscriptions pull SUBSCRIPTION_ID --limit=10

  .
• Server-side filtering — Apply

  --message-filter

  at subscription creation so unwanted messages are never delivered, rather than filtering after the fact. Use

  --filter

  on

  list

  commands to narrow results server-side where supported.
• Projection — Request only the fields you need with

  --format="value(...)"

  or

  --format="table(...)"

  instead of dumping full resource representations.

• Always append

  --project=PROJECT_ID

  to every command. Never rely solely on the ambient

  gcloud config

  project; explicit scoping prevents acting on the wrong project.
• For resources that support location or regional endpoints, specify the location explicitly rather than depending on defaults.

• Non-interactive mode — Append

  --quiet

  (or

  -q

  ) to suppress interactive prompts so commands are deterministic and automation-safe. This must not be used to bypass the human-approval requirements in the Safety section below.
• Single commands — Execute one discrete

  gcloud

  command at a time. Do not chain unrelated operations into a single invocation.
• No raw shell operators — Do not use shell pipes (

  |

  ), redirects (

  >

  ,

  >>

  ), command substitution (

  $(...)

  ), background operators (

  &

  ), or

  &&

  /

  ;

  chaining to compose Pub/Sub commands. Each command must stand alone and be independently auditable.

[!CAUTION] Pub/Sub operations can be destructive and irreversible. Deleting a topic or subscription permanently discards undelivered messages and breaks every producer and consumer bound to it. Changing IAM policy can silently cut off access for production services. Treat every mutating operation as production-impacting unless explicitly proven otherwise.

• Deleting a topic —

  gcloud pubsub topics delete ...

  . Destroys the topic and detaches all subscriptions.
• Deleting a subscription —

  gcloud pubsub subscriptions delete ...

  . Permanently drops all unacknowledged messages held by that subscription.
• Deleting or modifying a schema —

  gcloud pubsub schemas delete ...

  or schema revision changes that can invalidate in-flight producers.
• Purging/seeking messages destructively —

  gcloud pubsub subscriptions seek ...

  to a timestamp or snapshot that discards the current backlog.
• Changing critical IAM bindings — Adding, removing, or replacing

  roles/pubsub.admin

  ,

  roles/pubsub.publisher

  , or

  roles/pubsub.subscriber

  bindings on production topics or subscriptions, or any

  set-iam-policy

  operation that replaces an entire policy.
• Detaching a topic —

  gcloud pubsub topics detach-subscription ...

  , which immediately stops delivery to the affected subscription.

1. Confirm the active identity:

   gcloud config list --format="value(core.account)"

   .
2. Confirm the role on the resource matches the action (see the IAM table). For example, publishing requires

   roles/pubsub.publisher

   ; consuming requires

   roles/pubsub.subscriber

   .
3. For push to private endpoints, verify the push service account has the invoker role on the target service and that the configuring identity holds

   roles/iam.serviceAccountUser

   on that service account.
4. Confirm the API is enabled:

   gcloud services list --enabled --filter="pubsub" --project=PROJECT_ID

   .

1. Inspect the backlog and oldest unacked age in Cloud Monitoring metrics (

   subscription/num_undelivered_messages

   ,

   subscription/oldest_unacked_message_age

   ).
2. For pull consumers, scale out the number of consumer instances or increase per-instance concurrency so total throughput exceeds the publish rate.
3. Confirm consumers are acking successfully; failed processing leads to redelivery and inflated backlog.
4. Consider whether a

   --message-filter

   should reduce delivered volume, or whether the topic is over-fanned-out.

1. Verify the consumer is calling acknowledge after successful processing.
2. Check the

   --ack-deadline

   . If processing routinely takes longer than the deadline, increase it or extend the deadline programmatically; otherwise Pub/Sub redelivers before the consumer finishes.
3. Ensure consumers are idempotent — at-least-once delivery guarantees that duplicates can occur, and non-idempotent handlers compound the problem.
4. If specific "poison" messages never succeed, attach a dead letter topic with

   --max-delivery-attempts

   so they are isolated instead of redelivered forever.

1. Confirm the topic's bound schema and encoding:

   gcloud pubsub topics describe TOPIC_ID --project=PROJECT_ID

   .
2. Validate a sample message against the schema before publishing:

   gcloud pubsub schemas validate-message ...

   .
3. Confirm the producer serializes with the encoding the topic expects (

   JSON

   vs

   BINARY

   ); a mismatch causes rejection even for structurally valid data.
4. If the schema legitimately needs to change, commit a new, compatible schema revision rather than editing producers ad hoc — and treat schema deletion as a prohibited operation requiring approval.

• references/cli-usage.md

  — Comprehensive

  gcloud pubsub

  command reference, including publishing, pulling, acknowledging, seeking, snapshots, and output formatting recipes.

• references/iam-security.md

  — Detailed IAM role and policy guidance, least-privilege patterns, service-account configuration for push delivery, and dead-letter permission setup.

• references/client-libraries.md

  — Pointers to the official Google Cloud client libraries for programmatic publishing and consuming, with notes on when to prefer SDK code over the CLI.