Connectors

Session affinity is not optional for the AWS and GCP connectors on a multi-replica cluster. Both protocols hand the client a token that only the replica that minted it can honor:

• AWS — an SQS receipt handle is bound to the replica that issued it, and it is the only way to delete a message. A delete that lands on another replica is refused, the message reappears at the visibility timeout, and the queue never drains. A client holding a single keep-alive connection is pinned by accident and never sees this; it bites when the connection breaks, or when the client does not pool connections.
• GCP Pub/Sub — an ack id minted by one replica and acked on another is refused, with no disruption required to trigger it. Ordered subscriptions additionally need stickiness to preserve per-key ordering.

Set sessionAffinity: ClientIP on both:

aws:
  enabled: true
  expose: NodePort
  sessionAffinity: ClientIP
  nodePort: 30171
gcp:
  enabled: true
  expose: NodePort
  sessionAffinity: ClientIP
  nodePort: 32439

ClientIP affinity is unreliable when clients share a NAT or egress IP — every client behind it looks like one address and lands on one replica. Where an ingress exists, prefer cookie-based affinity on the ingress instead.

AMQP 0.9.1 and AMQP 1.0 share one listener, and one Service. Both ride 5672/5671; enabling both is supported and both are served through the <release>-amqp Service. Enabling amqp10 additionally creates a <release>-amqp10 Service as a discoverability alias onto that same listener. expose and sessionAffinity are shared between the two blocks — last one wins — so set them consistently. The operator raises an AmqpSessionAffinityConflict warning event if the two disagree.

Kafka exposure on a multi-replica cluster needs one address per broker. Kafka hands every client an address per broker in its Metadata response, so a single Service — ClusterIP, NodePort, or LoadBalancer alike — is one address that round-robins across all replicas and cannot address a 3-broker cluster. Setting kafka.expose: LoadBalancer on a multi-replica cluster does not give you working external Kafka.

• In-cluster, any replica count: leave spec.kafka.advertisedHost unset. The operator derives per-broker addresses from the pods' stable DNS names and gives each pod its own advertised host. Nothing to configure.
• External, single replica: expose + advertisedHost works.
• External, multi-replica: you must provision one client-reachable address per broker — a Service or LoadBalancer per pod, or a per-pod NodePort — and list them in spec.kafka.peers. The operator does not create per-broker addressing for you. Leave advertisedHost unset in this case: with a peer map each broker advertises itself from its own entry, and one advertisedHost could only ever be right for one of them.

CloudEvents has no port or Service of its own. It rides the server's shared HTTP listener alongside REST, and is reached and exposed through spec.rest.expose / spec.rest.nodePort. There is deliberately no spec.ce.expose.

The MCP env prefix is CONNECTORSMCP_ — no underscore between CONNECTORS and MCP. The natural CONNECTORS_MCP_* form does not bind — the server starts, accepts the variable without error, and silently ignores it. Unlike CloudEvents, MCP has no natural-name alias, so CONNECTORSMCP_ENABLE / CONNECTORSMCP_TOOL_TIMEOUT_SECONDS / CONNECTORSMCP_TRUSTED_ORIGINS are the only working names.

The A2A env prefix is CONNECTORSA2_A_ — not CONNECTORS_A2A_. The convertEnvFormat rule splits A2A into A2_A (the regex breaks between the digit and the trailing A), so the agent variables read CONNECTORSA2_A_MAX_AGENTS, CONNECTORSA2_A_AGENT_TTL_SECONDS, and so on. Neither CONNECTORS_A2A_* nor CONNECTORSA2A_* binds — both are silently ignored. Note also that the CRD group is spec.agents.*, not spec.a2a.*.

CloudEvents accepts both env forms. The primary name is the collapsed CONNECTORSCE_* (e.g. CONNECTORSCE_ENABLE), but CE is the one connector that also binds the natural CONNECTORS_CE_* alias (CONNECTORS_CE_ENABLE, CONNECTORS_CE_TIMEOUT_SECONDS, …). Both resolve to the same setting — this compensating alias exists only for CloudEvents; MCP, A2A, and MQTT do not have it.

But the server warns that the alias is IGNORED, and that warning is wrong. The unknown-variable warner does not track the alias binding, so a CONNECTORS_CE_* variable is reported as ignored while its value is being applied. Meanwhile a typo in the collapsed form (CONNECTORSC_ENABLE) produces no warning at all, because collapsed names sit outside the warner's namespace list. See the reference legend for the full picture.

The MQTT env prefix is CONNECTORSMQTT_ — no underscore between CONNECTORS and MQTT. The natural CONNECTORS_MQTT_* form does not bind and is silently ignored. This applies to every MQTT variable, including the nested CONNECTORSMQTT_CAPABILITIES_* keys. Unlike CloudEvents, MQTT has no natural-name alias.

Some MQTT capabilities are forced, not configurable. At server construction the connector pins RetainAvailable = 0 (retained messages rejected), SharedSubAvailable = 1, and WildcardSubAvailable = 1 regardless of config. A partially-specified capabilities block leaves unset safety caps (maxPacketSizeBytes, receiveMaximum, maxSessionExpirySeconds) at 0, which the server clamps back to their safe defaults rather than treating as "unlimited" — the effective caps are logged at startup. At least one listener port (port, tlsPort, or wsPort) must be non-empty, and no two may share the same value.

Two cross-checks against the queue limits. The server rejects the config unless amqp.maxReceiveCount ≤ queue.maxReceiveCount and amqp.getBatchSize ≤ queue.maxNumberOfMessages. Keep the AMQP values within the queue ceilings (see Storage & Queues).

AMQP 1.0 shares port 5672 (and TLS 5671) with AMQP 0.9.1. The two protocols are demultiplexed on a single shared listener, so running both on the default ports is fine. If you set a different port for one, keep the pair consistent so clients reach the listener you intend.

Kafka requires the next storage engine — but it's zero-config. On a fresh store with Kafka enabled and Store.Engine unset, the server auto-selects next (a NOTICE is logged) — no manual store.engine=next step needed. It fails closed only when the store directory already holds legacy data (a config error naming the conflicting directory) or Store.Engine=legacy is set explicitly alongside Kafka. Pinning STORE_ENGINE=next skips the probe entirely and always wins. See Storage Engines.

Kafka env-var trap: CONNECTORS_KAFKA_MAX_TRANSACTIONAL_I_DS. The MaxTransactionalIDs field renders to ..._MAX_TRANSACTIONAL_I_DS (an extra underscore before DS), not the intuitive ..._MAX_TRANSACTIONAL_IDS. The wrong form does not bind and is silently ignored. All other Kafka names follow the normal CONNECTORS_KAFKA_* rule.

Kafka SASL credentials are secret/file-only. Unlike AWS, there is no CredentialsData env-var escape hatch and no CRD field — supply the credentials list through a mounted config.yaml (or Secret-mounted file). On Kubernetes the delivery mechanism is spec.envFromSecrets, which projects an existing Secret into the pod without the values transiting the operator. Plan the credential delivery path before enabling SASL on Kubernetes.

Both OAUTHBEARER env forms work — use the readable one. The generic snake-caser fuses Kafka and OAuthBearer into one word and produces the unguessable CONNECTORS_KAFKAO_AUTH_BEARER_*. Because nobody can guess that, the server also binds the natural CONNECTORS_KAFKA_OAUTH_BEARER_* form deliberately, and both resolve to the same setting. Prefer the natural form:

CONNECTORS_KAFKA_OAUTH_BEARER_ISSUER=https://idp.example.com
CONNECTORS_KAFKA_OAUTH_BEARER_CLIENT_ID=kubemq

One caveat: the server's unknown-variable warner does not know about the alias, so setting the natural form prints an IGNORED warning even though the value is applied. The warning is wrong. Do not "fix" a working issuer because of it — confirm the effective value in the dashboard instead.

Skip-flags are hard-rejected on Kafka, not just warned. Setting Insecure skip signature check, Skip issuer check, or Skip expiry check to true on the Kafka listener is rejected outright by Validate() — stricter than the generic OIDC authentication path, which only warns. Skip client-ID check is the one permitted skip. (OAuthBearer.Issuer also requires a non-empty TlsPort — see the Issuer row above.)

AWS credentials go through a Secret, not a plain CRD value. The spec.aws.credentialsData field exists but the operator writes it into a Kubernetes Secret (CONNECTORS_AWS_CREDENTIALS_DATA), never a ConfigMap. On Docker, set connectors.aws.credentialsdata (JSON or base64-of-JSON) or the CONNECTORS_AWS_CREDENTIALS_DATA env var. The fully-structured connectors.aws.credentials list is config-file-only and has no env/CRD route.

Enable GCP Pub/Sub explicitly. A stock kubemq-server does not bind port 8085 until you set CONNECTORS_GCP_ENABLE=true (Docker) or spec.gcp.enabled: true (Kubernetes). Point clients at the connector with PUBSUB_EMULATOR_HOST=localhost:8085 — no auth, no TLS (emulator mode).