Connectivity and emulator mode

This guide covers how a Google Cloud Pub/Sub client reaches the connector: the standard PUBSUB_EMULATOR_HOST drop-in (the zero-code-change contract), the per-language emulator opt-in, the no-auth / insecure-gRPC posture, the cosmetic AdvertisedEndpoint dashboard hint, the gRPC-only constraint, and the sticky-load-balancer caveat for clusters.

The emulator protocol — zero code changes

The connector is a dedicated gRPC listener (default port 8085, the Pub/Sub emulator convention) inside KubeMQ. Every official Pub/Sub client library (Go, Python, Java, Node.js, C#, Ruby) and gcloud honour the standard PUBSUB_EMULATOR_HOST environment variable. When that variable is set, the SDK clears its Google credentials, skips Google auth, and dials insecure gRPC — exactly as it would against Google's own local emulator. Pointing an unmodified Pub/Sub application at KubeMQ therefore requires no code changes:

export PUBSUB_EMULATOR_HOST=localhost:8085   # connector default gRPC port; SDK uses the insecure path
export PUBSUB_PROJECT_ID=my-project          # any id; the project segment is parsed but ignored
# Some clients and gcloud also read this alias:
# export GOOGLE_CLOUD_PROJECT=my-project

There is no bespoke wrapper variable — the standard Google env var is the contract, and that zero-code-change drop-in is the connector's headline value proposition.

Per-language emulator opt-in

Most clients auto-detect the emulator from PUBSUB_EMULATOR_HOST with no extra code; two need an explicit flag or constructor argument:

The three clients that need explicit emulator wiring are Java, C#, and Ruby:

// When PUBSUB_EMULATOR_HOST is set, build a plaintext channel and clear credentials.
String host = System.getenv("PUBSUB_EMULATOR_HOST"); // e.g. localhost:8085
ManagedChannel channel = ManagedChannelBuilder.forTarget(host).usePlaintext().build();
TransportChannelProvider channelProvider =
    FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel));
CredentialsProvider credentialsProvider = NoCredentialsProvider.create();

TopicAdminClient topicAdmin = TopicAdminClient.create(
    TopicAdminSettings.newBuilder()
        .setTransportChannelProvider(channelProvider)
        .setCredentialsProvider(credentialsProvider)
        .build());

// EmulatorDetection reads PUBSUB_EMULATOR_HOST and switches to the insecure path.
var publisher = await new PublisherServiceApiClientBuilder
{
    EmulatorDetection = EmulatorDetection.EmulatorOnly
}.BuildAsync();

# Ruby does not auto-detect the emulator — pass emulator_host: explicitly.
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new(
  project_id: ENV["PUBSUB_PROJECT_ID"],
  emulator_host: ENV["PUBSUB_EMULATOR_HOST"], # e.g. localhost:8085
)

No auth, no TLS

The connector runs in emulator mode: no Google OAuth2/JWT validation, no IAM enforcement (the IAMPolicy RPCs are permissive stubs), and no TLS. The transport is insecure gRPC.

DoS guards remain active even with no auth:

• CONNECTORS_GCP_MAX_MESSAGE_BYTES — a gRPC receive-size body cap (default 10 MiB);
• CONNECTORS_GCP_MAX_INFLIGHT_PER_SUBSCRIPTION — hard cap on leased (un-acked) messages per subscription (20,000);
• CONNECTORS_GCP_MAX_CONCURRENT_POLLS — poller slot budget (1,024);
• CONNECTORS_GCP_MAX_SEEK_REPLAY — max messages a single Seek may replay (1,000,000);
• push-delivery backoff.

These knobs are documented in Configuration.

The advertised-endpoint hint

CONNECTORS_GCP_ADVERTISED_ENDPOINT (default empty) is a cosmetic host:port string the dashboard shows as the suggested PUBSUB_EMULATOR_HOST value. It does not change how the listener binds or behaves; set it to the externally reachable address (e.g. kubemq.mycompany.svc:8085) so operators copy the right host into their env.

gRPC only — no REST/JSON

Periodic stream reconnect

A StreamingPull stream is closed by the server after CONNECTORS_GCP_STREAM_CLOSE_SECONDS (default 1800 s / 30 min) with UNAVAILABLE; client libraries transparently reconnect. This bounds per-stream resource lifetime and is normal — your receive callback keeps running across the reconnect. See Subscribing.

Sticky-stream caveat (cluster)

Message data itself is not replicated by the connector — it rides the existing Events Store / Queues replication.

Traffic gate

While the message broker is not ready, the traffic-gate interceptor short-circuits requests; on a not-ready → ready transition the connector drops all in-memory leases (their downstream transactions are dead) and the poller rebuilds. SDKs see a transient UNAVAILABLE and retry.

Related