Capabilities
What the KubeMQ Pub/Sub connector supports — the 38 v1 RPCs across Publisher, Subscriber, SchemaService, and IAMPolicy stubs, and the operations it rejects.
This reference defines exactly what the embedded KubeMQ Pub/Sub connector supports, what it
accepts-and-ignores, and what it rejects. The connector implements the real Pub/Sub v1
gRPC services — 38 RPCs total — so unmodified Google client libraries and gcloud pubsub talk
to KubeMQ exactly as they would to Google's local emulator. Use it to decide which Pub/Sub SDK
calls are safe to rely on and which ones are refused.
Milestone tags below: M1 core drop-in · M2 advanced delivery · M3 full parity.
The 38-RPC matrix
| Service | Count |
|---|---|
google.pubsub.v1.Publisher | 9 |
google.pubsub.v1.Subscriber | 16 |
google.pubsub.v1.SchemaService | 10 |
google.iam.v1.IAMPolicy | 3 (permissive stubs) |
| Total | 38 |
Publisher (9)
| # | RPC | M | Notes |
|---|---|---|---|
| 1 | CreateTopic | M1 | Validates the name; kms_key_name accepted-and-ignored; ingestion configs rejected (INVALID_ARGUMENT); retention clamped to the broker ceiling. Backing log gcp.{t} |
| 2 | GetTopic | M1 | Returns the requested (un-clamped) retention |
| 3 | ListTopics | M1 | Opaque page token |
| 4 | DeleteTopic | M1 | Tombstone — the record is retained so existing subscriptions survive; re-creating the topic reuses the log |
| 5 | Publish | M1 | Batch (≤ 1000); assigns id + publish-time; writes the topic log once, then fans out one queue copy per subscription (applying each sub's filter). M3 adds schema enforce-on-publish |
| 6 | ListTopicSubscriptions | M1 | |
| 7 | UpdateTopic | M2 | FieldMask over labels, message_retention_duration, schema_settings |
| 8 | ListTopicSnapshots | M3 | |
| 9 | DetachSubscription | M3 | Marks detached, drops backlog + leases; the subscription stays re-fillable by Seek |
Subscriber (16)
| # | RPC | M | Notes |
|---|---|---|---|
| 1 | CreateSubscription | M1 | Binds to a topic; queue gcp.sub.{s} created lazily. Export subscriptions (BigQuery/Cloud Storage/Bigtable) and ingestion are rejected. Filter compiled at create-time (immutable) |
| 2 | GetSubscription | M1 | Returns the requested (un-clamped) retention |
| 3 | ListSubscriptions | M1 | |
| 4 | DeleteSubscription | M1 | Drops backlog + leases |
| 5 | UpdateSubscription | M2 | FieldMask over ack deadline / retention / DLQ / retry / push / exactly-once / labels. name and filter are immutable |
| 6 | Pull | M1 | max_messages ≤ 1000; a detached subscription → FAILED_PRECONDITION |
| 7 | Acknowledge | M1 | Decodes ack_id → acks the broker sequence. Exactly-once subs return a status for invalid/expired ids (below) |
| 8 | ModifyAckDeadline | M1 | 0 = immediate nack/redeliver; >0 = extend (10..600 s) |
| 9 | StreamingPull | M1 | Bidirectional; per-stream flow control; exactly-once confirmations; periodic server-initiated close every StreamCloseSeconds |
| 10 | ModifyPushConfig | M2 | Switch pull ↔ push; an empty config returns to pull |
| 11 | Seek | M3 | To a timestamp or a snapshot; replays the topic log into the subscription queue, bounded by MaxSeekReplay |
| 12 | CreateSnapshot | M3 | Cursor snapshot, 7-day default expiry |
| 13 | GetSnapshot | M3 | |
| 14 | ListSnapshots | M3 | |
| 15 | UpdateSnapshot | M3 | May change labels and expire_time |
| 16 | DeleteSnapshot | M3 |
The 250 ms lease sweeper, retry backoff, dead-letter republish, and per-key ordering cursor are connector-internal mechanics behind these RPCs — see Subscribing and Reliability.
SchemaService (10, M3)
CreateSchema, GetSchema (BASIC/FULL), ListSchemas, ListSchemaRevisions, CommitSchema,
RollbackSchema, DeleteSchemaRevision (keeps ≥ 1), DeleteSchema, ValidateSchema,
ValidateMessage — over Avro and Protobuf definitions, each with server-assigned revision
ids and full revision history. A definition that fails to parse → INVALID_ARGUMENT; definitions
are capped at 300 KB. See Schema Validation.
IAMPolicy (3, M2)
GetIamPolicy returns an empty Policy{Version: 3}; SetIamPolicy and TestIamPermissions
echo the request. These are permissive stubs — there is no IAM enforcement (emulator
parity). The connector runs with no authentication.
Feature support
| Feature | Supported? | Notes |
|---|---|---|
| Basic publish / pull / ack | ● | M1 core drop-in |
| Batch publish (≤ 1000) | ● | Atomic — the whole batch is validated before anything is enqueued |
| StreamingPull + flow control | ● | Per-stream max_outstanding_messages / _bytes; ≤ 0 = unlimited (capped by MaxOutstandingMessages) |
| Ordering keys | ● | enable_message_ordering; at most one in flight per key, in-order redelivery |
| Attribute filtering | ● | CEL-subset, attributes-only, ≤ 256 chars, immutable, applied at fan-out |
| Dead-letter topic | ● | dead_letter_topic + max_delivery_attempts (5..100) |
| Push delivery | ● | Wrapped JSON envelope or no_wrapper; optional OIDC Bearer; HTTPS (HTTP only for localhost) |
| Exactly-once delivery | ● (node-local) | enable_exactly_once_delivery; an ack_id is valid only on the node that minted it |
| Seek to timestamp / snapshot | ● | Replays the topic log; a pre-window timestamp clamps to the earliest retained message |
| Snapshots | ● | 7-day default expiry, swept hourly |
| Schema validation (Avro / Protobuf) | ● | Enforce-on-publish; whole batch rejected on the first non-conforming message |
| Cross-protocol interop | ● | Pub/Sub publish ⇄ native KubeMQ consume on Events Store gcp.{t} |
| IAM enforcement | ○ | Permissive stubs only; no enforcement |
Accepted-and-ignored / rejected
These are documented non-goals. They are never used as working examples, and most are actively rejected by the connector with the error code shown:
| Operation / field | Behavior |
|---|---|
kms_key_name (on CreateTopic) | accepted and ignored — no KMS in emulator mode |
Project segment projects/{p}/… | parsed, validated, then ignored — single-tenant; resource ids are global across projects |
| Ingestion sources (topic / subscription) | rejected (INVALID_ARGUMENT) — no KubeMQ analog |
| Export subscriptions (BigQuery / Cloud Storage / Bigtable) | rejected (INVALID_ARGUMENT) |
| REST / JSON v1 (grpc-gateway) | not served — gRPC only |
| Google OAuth2 / JWT / IAM | not validated — emulator mode, no auth |
The documented gotchas
These behaviors deviate from real Google Cloud Pub/Sub and are easy to miss until a corner case hits production. Each is documented in depth where shown:
| # | Gotcha | Where documented |
|---|---|---|
| 1 | Exactly-once is node-local — an ack_id minted on one node is invalid on another; pin a subscription's StreamingPull to one node (sticky LB) or accept at-least-once across nodes | Subscribing, Reliability, Migrating from Google Cloud Pub/Sub |
| 2 | Project id parsed but ignored — resource ids are global across projects | Getting Started, Channel Mapping |
| 3 | Credentials cleared / insecure path when PUBSUB_EMULATOR_HOST is set — the SDK skips Google auth and dials insecure gRPC | Connectivity & Emulator Mode |
| 4 | Filtering is an attributes-only CEL-subset — malformed → INVALID_ARGUMENT | Message Filtering, Limits & Rules |
| 5 | Retention clamped to the broker maximum — GetTopic / GetSubscription echo the requested value; fan-out, seek, and the dashboard use the clamped value | Limits & Rules, Seek & Snapshots |
| 6 | max_delivery_attempts must be 5..100 (0 = unset) | Reliability, Limits & Rules |
| 7 | Topic ids may not start with sub. (reserved namespace) | Channel Mapping, Limits & Rules |
| 8 | Seek of a pre-window timestamp clamps to the earliest retained message (not an error) | Seek & Snapshots |
| 9 | gRPC only — no REST/JSON v1 (grpc-gateway not used) | Architecture, this page |
Two further documented deviations are surfaced in the reference docs but are not headline gotchas:
the unary invalid-ack returns FAILED_PRECONDITION + ErrorInfo(PERMANENT_FAILURE_INVALID_ACK_ID)
(matching the real SDK contract, not a literal INVALID_ARGUMENT), and export subscriptions /
ingestion are rejected while kms_key_name is accepted-and-ignored. Both live in
Error Codes and
Migrating from Google Cloud Pub/Sub.
Related
Channel Mapping
The gcp.{topic} / gcp.sub.{subscription} grammar, the per-key channels, and the reserved tags.
Limits & Rules
The Google-exact limits and the CONNECTORS_GCP_* config caps behind each rejection above.
Error Codes
The gRPC status codes the connector returns for each rejected operation.
Migrating from Google Cloud Pub/Sub
The deviations from real Pub/Sub and the endpoint-only switch.
Was this page helpful?
Subscribing
Consume over KubeMQ — Pull vs StreamingPull with flow control, ack-deadline leases, ModifyAckDeadline nack/extend, and exactly-once with its node-local note.
Channel Mapping
How Pub/Sub topics and subscriptions map to KubeMQ — the gcp.{topic} Events Store log, the gcp.sub.{subscription} Queue grammar, reserved tags, and project.