Rymote.Synapse.Cluster.Kubernetes 1.0.0

Rymote.Synapse.Cluster.Kubernetes

Kubernetes Endpoints-watching IMembershipProvider for Rymote.Synapse.Cluster. Discovers cluster peers automatically by watching a headless Kubernetes Service's endpoint addresses.

How it works

The provider watches a Kubernetes Endpoints resource (v1 core API) for a named headless Service. Each ready EndpointAddress in the service's subsets becomes a peer node. Pod identity is derived deterministically from stable per-pod environment variables using a GUID v5 (SHA-1 namespace hash) — the same pod always resolves to the same NodeIdentity.

Membership changes (peers joining or leaving) are pushed to subscribers of IMembershipProvider.Changes. The watch runs in a background loop and reconnects automatically with exponential backoff on disconnect (Kubernetes drops watches approximately every 5 minutes).

PublishSubscriptionAsync and WithdrawSubscriptionAsync are no-ops — subscription propagation in Kubernetes deployments is handled peer-to-peer by the cluster's SubscriptionPropagator.

Requirements

In-cluster (default)

• The pod must run with a service account that has get and list and watch permissions on the endpoints resource in the target namespace.
• The following environment variables must be present in each pod spec:

At least one of SYNAPSE_NODE_ID, HOSTNAME, or POD_UID must be set. POD_IP is always required.

Local development (UseLocalKubeconfig = true)

Set UseLocalKubeconfig = true in options to use ~/.kube/config instead of in-cluster service account credentials.

Quickstart

<PackageReference Include="Rymote.Synapse.Cluster.Kubernetes" Version="*" />

services.AddSynapse(builder =>
{
    builder.UseKubernetesMembership(options =>
    {
        options.ServiceName = "my-app-headless";   // name of the headless Service
        options.Namespace   = "production";         // default: "default"
        options.Port        = 8443;                 // Synapse transport port on each pod
    });
});

RBAC example

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: synapse-endpoints-reader
rules:
  - apiGroups: [""]
    resources: ["endpoints"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: synapse-endpoints-reader
subjects:
  - kind: ServiceAccount
    name: default
roleRef:
  kind: Role
  name: synapse-endpoints-reader
  apiGroup: rbac.authorization.k8s.io

Pod spec Downward API example

env:
  - name: POD_IP
    valueFrom:
      fieldRef:
        fieldPath: status.podIP
  - name: POD_UID
    valueFrom:
      fieldRef:
        fieldPath: metadata.uid