Setup

This page covers the configuration you will change after deploying the chart. For cluster requirements and the install command, start with Self-hosted deployment.

All settings live in the chart's values.yaml under api, events and cluster.

Authentication

Authentication is off by default. Turn it on before exposing the API.

Option 1: OIDC / JWT

Any OpenID Connect provider works — Microsoft Entra ID, Keycloak, Auth0, Dex:

api:
  config:
    authentication:
      enabled: true
      metadataAddress: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
      audience: api://konnektr-graph
      issuer: https://sts.windows.net/<tenant-id>/

metadataAddress is the provider's discovery document. The API validates the signature, aud and iss of every bearer token against it.

If you previously ran the managed Konnektr service, the identity-provider values shipped in older chart versions point at it and are inert while authentication is disabled. Replace all three values with your own provider.

Option 2: API keys

For service-to-service calls without an identity provider:

api:
  config:
    authentication:
      enabled: true
    # keys are compared in constant time; rotate by listing the new one first

See Configuration reference for the exact key names and the Parameters: overrides that the API reads at startup.

Event sinks and routes

Events are produced by the Events service, not the API. Enable it and declare where events go, then which event formats are routed to which sink:

events:
  enabled: true
  config:
    eventSinks:
      kafka:
        - name: KafkaSink1
          brokerList: "kafka-0:9092,kafka-1:9092"
          topic: "twin-events"
          saslMechanism: PLAIN
          saslUsername: "graph"
      kusto:
        - name: AdxSink1
          ingestionUri: "https://<cluster>.<region>.kusto.windows.net"
          database: "graph"
      mqtt: []
    eventRoutes:
      - sinkName: KafkaSink1
        eventFormat: EventNotification
      - sinkName: AdxSink1
        eventFormat: DataHistory

• EventNotification — real-time twin create/update/delete and relationship changes.
• DataHistory — the historical format compatible with Azure Digital Twins data history.

Secrets (SASL passwords, connection strings) belong in a Kubernetes Secret, injected via extraEnv, not in values.yaml:

events:
  extraEnv:
    - name: EventSinks__Kafka__0__SaslPassword
      valueFrom:
        secretKeyRef:
          name: kafka-sasl-password
          key: password

Database

The chart can create its own PostgreSQL cluster (CloudNativePG) or connect to one you operate.

cluster:
  enabled: true
  type: postgresql
  version:
    major: 18
    age: "1.7.0"
  cluster:
    instances: 1
    storage:
      size: 5Gi

Requirements for an external database:

• PostgreSQL 16, 17 or 18 with the Apache AGE extension installed
• pgvector if you want scoped vector memory search
• the extensions created and the graph initialised (the API does the latter on first use)

If you run a single-instance cluster, leave api.database.readOnlyHost: auto (the default). It avoids advertising the CloudNativePG read-only service when no replica can exist — on some CNIs connections to that service hang instead of failing.

Scaling

api:
  replicaCount: 2
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10

The API is stateless; scale it horizontally. Query throughput is bounded by PostgreSQL, so size the database before adding replicas. api.config.parameters carries the pool and rate-limit knobs (maxPoolSize, connectionTimeout, rateLimitingEnabled, maxQueryComplexityPerWindow).

Observability

api:
  logLevel: Information          # Error | Warning | Information | Debug | Trace
  openTelemetry:
    enabled: true
    exporterEndpoint: http://otel-collector.opentelemetry.svc.cluster.local:4317

The API exposes /health for probes and Prometheus-format metrics. The chart's probes already point at /health; wire openTelemetry to your collector for traces.

Next steps

• Event routing — the event model in detail
• Configuration reference — every setting the API reads
• Performance — tuning queries and pooling
• Native SDK — talk to PostgreSQL directly, without HTTP