DOCSEARCHbyAlgolia
Submit Docs

TyKO (Typesense Kubernetes Operator)

website·Indexed 31 days ago

https://akyriako.github.io/typesense-operator-docs

The Typesense Kubernetes Operator (TyKO) manages the deployment and lifecycle of Typesense clusters on Kubernetes. It provides self-healing capabilities, manages TypesenseCluster Custom Resource Definitions (CRDs), and handles quorum reconciliation and reconfiguration. Documentation covers installation via Helm, configuration for S3-compliant storage, and compatibility with Typesense 30.x+.

Tokens
11.1K
Snippets
42
Records
87
Agent score
70%

What's inside TyKO

  1. Overview of TyKO (Typesense Operator for Kubernetes)

    TyKO is a Kubernetes operator built with the Operator SDK designed to manage Typesense clusters. It provides automated lifecycle management including self-healing (automated failover, quorum recovery, and raft re-evaluation), zero-downtime rolling updates for upgrades or resizing, and native integration with Kubernetes resources like StatefulSets, ConfigMaps, Secrets, and Services. It supports S3-compatible object storage (e.g., AWS S3, OBS, RustFS) for data persistence and exposes node health and metrics for Prometheus monitoring. It also integrates with Kubernetes Ingress and the Gateway API for secure exposure and TLS termination.

  2. Overview of Typesense Kubernetes Operator (TyKO)

    The Typesense Kubernetes Operator (TyKO) is a tool developed in Go using the Operator SDK Framework. It is designed to automate the deployment and lifecycle management of Typesense clusters within Kubernetes environments, providing a scalable and automated way to manage these native applications.

  3. Understand Typesense Operator Networking and Deployment

    The operator manages the following Kubernetes resources to deploy a Typesense cluster:

    1. Headless Service: Used by the StatefulSet for internal node communication.
    2. ClusterIP Service: Used to expose REST/API endpoints to external systems.
    3. StatefulSet: Provisions the Typesense pods and mounts the NodesListConfigMap for quorum management.
    4. Ingress (Optional): Provisions an nginx workload (default nginx:alpine) to expose the API to specific referers.
    5. DocSearch Scrapers (Optional): Deploys CronJobs to periodically scrape target URLs and store results in Typesense.

  4. Understand Typesense cluster quorum and Raft consensus

    Typesense uses the Raft consensus algorithm to manage clusters. Nodes exist in three states: follower, candidate, or leader. A cluster of N nodes can tolerate a failure of at most (N-1)/2 nodes. If the number of available nodes falls below this threshold, the cluster loses quorum, meaning no leader can be elected and no log entries can be processed. To prevent split-brain issues, Typesense will stop accepting reads and writes until manual intervention occurs.

  5. Monitor Typesense nodes using Prometheus

    The Typesense operator deploys each node as a Kubernetes Pod containing three containers: the Typesense server, a metrics exporter sidecar (based on typesense-prometheus-exporter), and a cluster healthcheck sidecar. The metrics exporter collects data from the Typesense /metrics.json and /stats.json endpoints and exposes them in Prometheus format at the /metrics endpoint. The operator automatically creates a PodMonitor resource to enable Prometheus discovery and scraping.
    apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: ts-podmonitor
  namespace: default
  labels:
    release: { RELEASE_NAME }
spec:
  selector:
    matchLabels:
      { LABEL_OF_THE_STATEFULSET_PODS }
  namespaceSelector:
    matchNames:
      - default
  endpoints:
    - port: metrics
      path: /metrics
      interval: 15s
      scheme: http

  6. Access the Typesense healthcheck Web UI

    The typesense-healthcheck sidecar includes a built-in Vue.js monitoring dashboard that provides a real-time overview of the Typesense StatefulSet. It displays node states (leader/follower/candidate), committed indices, and queued writes, with auto-refresh every 3 seconds and color-coded health indicators.
    # Access the UI via browser
http://<POD_IP_ADDRESS_OR_FQDN>:<HEALTHCHECK_PORT>/

  7. Understand the Typesense Operator Quorum Reconciliation Loop

    The Typesense Operator implements a Quorum Reconciliation Loop to prevent clusters from entering a 'hot loop' where no leader can be elected due to conflicting majorities during configuration changes. The controller automates the recovery process—which would normally require manual scaling of the StatefulSet—by detecting quorum loss and forcing a downgrade to a single-node cluster to establish a healthy quorum, then gradually scaling back up. This automation works as long as the issue is not caused by memory or disk capacity limits.

  8. Deploy a High-Availability Typesense cluster using TyKO

    To deploy a highly-available (HA) Typesense cluster on Kubernetes using the TyKO operator, follow these three steps:

    1. Install the Operator: Deploy TyKO into the Kubernetes cluster using a Helm command.
    2. Declare a cluster: Create a TypesenseCluster custom resource (CR) that defines the cluster size, storage requirements, and exposure settings.
    3. Management: The operator automatically handles quorum, failover, upgrades, and scaling.

  9. Upgrade Typesense and DocSearch Scraper for version 30.x+

    When upgrading to Typesense version 30.0 or higher, you must upgrade the DocSearch Scraper simultaneously. Typesense 30.0 introduced breaking API changes for transferring synonyms and curation sets that are incompatible with DocSearch Scraper versions prior to 0.12.0.rc14.
    TypesenseDocSearch Scraper
    29.x0.11.0
    30.x+0.12.0.rc14+

  11. Set up JuiceFS CSI Driver and Redis for S3 storage

    To use S3-compliant object storage as persistent volumes (supporting ReadWriteOnce and ReadWriteMany as of v0.3.6), you must install the JuiceFS CSI Driver and a Redis cluster to serve as the metadata store.

    Caveats:

    • T Cloud Public users can skip this if using the everest-csi-provisioner.
    • Amazon S3 users do not require Redis as S3 provides its own metadata endpoints.
    # Install JuiceFS CSI Storage Driver
kubectl apply -f https://raw.githubusercontent.com/juicedata/juicefs-csi-driver/master/deploy/k8s.yaml

# Install Redis Cluster
kubectl create namespace redis
kubectl apply -f redis.yaml -n redis

  12. Migrate from IngressSpec to HttpRoute

    As of v0.4.0-rc.1, IngressSpec is deprecated in favor of the Kubernetes Gateway API (HttpRoute). While Ingress resources are still supported to avoid breaking changes, they will receive no new features or maintenance updates. New deployments should use HttpRoute.