# Configuration reference (/connectors/gcp-pub-sub/reference/configuration)



All values below are verified against `[Connectors.Gcp]` (`GcpConfig`) in the KubeMQ server. For
the framing behind these settings — enabling the connector and its security posture — see
[Configuration concepts](../concepts/configuration).

## Configuration fields [#configuration-fields]

Compound camelCase fields are snake-split in their env form — e.g. `MaxMessageBytes` →
`CONNECTORS_GCP_MAX_MESSAGE_BYTES`, `DefaultAckDeadlineSeconds` →
`CONNECTORS_GCP_DEFAULT_ACK_DEADLINE_SECONDS`.

| Env var                                        | Default    | Meaning / validation                                                                                                                  |
| ---------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTORS_GCP_ENABLE`                        | `false`    | **Opt-in.** `true` enables the connector and binds port 8085.                                                                         |
| `CONNECTORS_GCP_PORT`                          | `"8085"`   | The gRPC listen port (the emulator convention). Must be valid and **distinct** from any enabled gRPC/REST/HTTP or AWS-connector port. |
| `CONNECTORS_GCP_ADVERTISED_ENDPOINT`           | `""`       | Cosmetic `host:port` shown in the dashboard's `PUBSUB_EMULATOR_HOST` hint. Does not affect listening.                                 |
| `CONNECTORS_GCP_MAX_MESSAGE_BYTES`             | `10485760` | Max total message size (10 MiB). Also sizes the gRPC receive frame.                                                                   |
| `CONNECTORS_GCP_DEFAULT_ACK_DEADLINE_SECONDS`  | `10`       | Default ack deadline for new subscriptions. Must be **10..600**.                                                                      |
| `CONNECTORS_GCP_MAX_OUTSTANDING_MESSAGES`      | `1000`     | Per-`StreamingPull`-stream flow-control ceiling when the client requests unlimited.                                                   |
| `CONNECTORS_GCP_MAX_INFLIGHT_PER_SUBSCRIPTION` | `20000`    | Hard cap on leased (un-acked) messages per subscription.                                                                              |
| `CONNECTORS_GCP_MAX_CONCURRENT_POLLS`          | `1024`     | Poller-slot budget (a DoS guard).                                                                                                     |
| `CONNECTORS_GCP_DELIVERY_SHARDS`               | `16`       | Size of the striped delivery-worker pool (fan-out concurrency). Must be **1..256**.                                                   |
| `CONNECTORS_GCP_MAX_ACK_EXTENSION_SECONDS`     | `600`      | Ack-deadline keep-alive budget for the ordered head. `0` disables the keep-alive (expiry → redeliver); otherwise **10..3600**.        |
| `CONNECTORS_GCP_STREAM_CLOSE_SECONDS`          | `1800`     | Periodic `StreamingPull` close interval (forces a transparent SDK reconnect; bounds per-stream resource lifetime).                    |
| `CONNECTORS_GCP_MAX_SEEK_REPLAY`               | `1000000`  | Max messages replayed by a single `Seek` (hits the cap → `WARN`, never silent loss).                                                  |
| `CONNECTORS_GCP_ENABLE_REFLECTION`             | `false`    | Register gRPC server reflection (for debugging).                                                                                      |

<Callout type="info">
  `Validate()` is a no-op when the connector is disabled. When enabled, the port must be valid
  and unique, the ack deadline must be 10..600, `DeliveryShards` must be 1..256,
  `MaxAckExtensionSeconds` must be `0` or 10..3600, and the six remaining numeric knobs must be
  positive. See
  [Limits & rules](/connectors/gcp-pub-sub/reference/limits-and-rules) for the full numeric
  table.
</Callout>

## Examples [#examples]

The same settings can be supplied through a TOML config file, environment variables, or
`docker run` flags. Every environment variable uses the `CONNECTORS_GCP_` prefix (with the
underscore between `CONNECTORS` and `GCP`).

<Tabs groupId="config-source" items="['TOML', 'Environment', 'Docker']">
  <Tab value="TOML">
    ```toml title="config.toml"
    [Connectors.Gcp]
      Enable = true
      Port = "8085"
      AdvertisedEndpoint = ""
      MaxMessageBytes = 10485760
      DefaultAckDeadlineSeconds = 10
      MaxOutstandingMessages = 1000
      MaxInflightPerSubscription = 20000
      MaxConcurrentPolls = 1024
      DeliveryShards = 16
      MaxAckExtensionSeconds = 600
      StreamCloseSeconds = 1800
      MaxSeekReplay = 1000000
      EnableReflection = false
    ```
  </Tab>

  <Tab value="Environment">
    ```bash title="gcp.env"
    CONNECTORS_GCP_ENABLE=true
    CONNECTORS_GCP_PORT=8085
    CONNECTORS_GCP_ADVERTISED_ENDPOINT=
    CONNECTORS_GCP_MAX_MESSAGE_BYTES=10485760
    CONNECTORS_GCP_DEFAULT_ACK_DEADLINE_SECONDS=10
    CONNECTORS_GCP_MAX_OUTSTANDING_MESSAGES=1000
    CONNECTORS_GCP_MAX_INFLIGHT_PER_SUBSCRIPTION=20000
    CONNECTORS_GCP_MAX_CONCURRENT_POLLS=1024
    CONNECTORS_GCP_DELIVERY_SHARDS=16
    CONNECTORS_GCP_MAX_ACK_EXTENSION_SECONDS=600
    CONNECTORS_GCP_STREAM_CLOSE_SECONDS=1800
    CONNECTORS_GCP_MAX_SEEK_REPLAY=1000000
    CONNECTORS_GCP_ENABLE_REFLECTION=false
    ```
  </Tab>

  <Tab value="Docker">
    <RunKubeMQ
      ports="[8085, 50000]"
      env="{
      CONNECTORS_GCP_ENABLE: 'true',
      CONNECTORS_GCP_ADVERTISED_ENDPOINT: 'kubemq.example.com:8085',
      CONNECTORS_GCP_MAX_INFLIGHT_PER_SUBSCRIPTION: '50000',
    }"
    />
  </Tab>
</Tabs>

<Callout type="info">
  The Docker example includes `CONNECTORS_GCP_ENABLE=true` — without it the connector stays
  disabled and port 8085 is not bound. `CONNECTORS_GCP_ADVERTISED_ENDPOINT` is a **cosmetic**
  dashboard hint (the `PUBSUB_EMULATOR_HOST` value to copy); it never changes the listening port.
</Callout>

## Related [#related]

<Cards>
  <Card title="Getting Started" href="/connectors/gcp-pub-sub/tutorials/getting-started" description="Point your Pub/Sub SDK at port 8085 and run a publish-and-pull round-trip end-to-end in minutes." />

  <Card title="Architecture" href="/connectors/gcp-pub-sub/concepts/architecture" description="The gRPC emulator listener, the 38-RPC surface, and the publish-once-then-fan-out model." />

  <Card title="Connectivity & emulator mode" href="/connectors/gcp-pub-sub/how-to/connectivity-and-emulator-mode" description="The PUBSUB_EMULATOR_HOST drop-in, per-language emulator opt-in, and the insecure-gRPC posture." />

  <Card title="Limits & rules" href="/connectors/gcp-pub-sub/reference/limits-and-rules" description="Ack deadline, max delivery attempts, filter and schema sizes, batch caps, and the config ceilings." />
</Cards>