No description
  • Go 88.2%
  • Starlark 9.8%
  • Shell 1.6%
  • Go Template 0.3%
Find a file
Renovate 3787ccea9c
All checks were successful
Validate / validate (pull_request) Successful in 10m4s
Validate / validate (push) Successful in 5m47s
fix(deps): update module github.com/kisielk/errcheck to v1.30.0
2026-10-14 20:33:10 +02:00
.agents/rules APM: onboard 2026-09-21 18:53:16 +02:00
.devcontainer chore(deps): update golang docker tag to v1.27 2026-09-08 17:41:55 +00:00
.forgejo/workflows ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
.zed Upgrade: improve upgrade workflow 2026-09-10 19:40:13 +02:00
api Backup: fix PVC backup storage support 2026-09-18 20:47:05 +02:00
build Upgrade: improve upgrade workflow 2026-09-10 19:40:13 +02:00
cmd Analyzers: onboard cyclop and funlen 2026-09-21 11:46:34 +02:00
config ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
dev ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
docs Instance: allow overriding the security context for both pods and containers 2026-09-17 20:02:26 +02:00
hack feat: initial setup of project 2026-04-30 20:37:40 +02:00
internal Analyzers: fix cyclop and funlen issues 2026-09-21 20:01:17 +02:00
openspec LLM: remove RTK 2026-09-21 18:28:14 +02:00
platforms ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
test Analyzers: onboard cyclop and funlen 2026-09-21 11:46:34 +02:00
tools ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
.bazelrc ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
.bazelversion chore(bazel): configure project defaults 2026-05-25 18:24:42 +02:00
.custom-gcl.yml feat: initial setup of project 2026-04-30 20:37:40 +02:00
.dockerignore feat: initial setup of project 2026-04-30 20:37:40 +02:00
.editorconfig feat: initial setup of project 2026-04-30 20:37:40 +02:00
.envrc feat: initial setup of project 2026-04-30 20:37:40 +02:00
.gitattributes ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
.gitignore APM: onboard 2026-09-21 18:53:16 +02:00
.golangci.yml feat: initial setup of project 2026-04-30 20:37:40 +02:00
.kata.toml Planning: add backup storage location based on PVCs 2026-09-11 16:02:00 +02:00
.nogo.json Analyzers: onboard cyclop and funlen 2026-09-21 11:46:34 +02:00
AGENTS.md LLM: remove RTK 2026-09-21 18:28:14 +02:00
analyzers.go Analyzers: onboard cyclop and funlen 2026-09-21 11:46:34 +02:00
apm.lock.yaml ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
apm.yml APM: add roborev MCP 2026-09-23 13:29:08 +02:00
BUILD.bazel ci: run workflows on fedora-tiny with Bazel remote execution (#144) 2026-10-07 16:42:33 +00:00
CLAUDE.md Agents: rework planning setup and general agent instructions 2026-07-04 14:39:04 +00:00
cliff.toml CI: fix release notes 2026-07-01 18:18:49 +00:00
crd-docs.yaml feat: initial setup of project 2026-04-30 20:37:40 +02:00
go.mod fix(deps): update module github.com/kisielk/errcheck to v1.30.0 2026-10-14 20:33:10 +02:00
go.sum fix(deps): update module github.com/kisielk/errcheck to v1.30.0 2026-10-14 20:33:10 +02:00
justfile Backup: support PVCs as BackupStorageLocation 2026-09-14 06:19:33 +00:00
LICENSE Initial commit 2026-04-29 19:22:35 +00:00
MODULE.bazel chore(deps): update dependency bazel_env.bzl to v0.10.0 2026-10-14 20:03:21 +02:00
MODULE.bazel.lock chore(deps): update dependency bazel_env.bzl to v0.10.0 2026-10-14 20:03:21 +02:00
PROJECT Instance: split image into separate fields in new struct and add validation webhook 2026-09-08 18:56:55 +02:00
README.md docs: make 'just dev' the default README quick start 2026-10-04 09:05:21 +00:00
renovate.json Renovate: fix config 2026-07-04 14:44:30 +00:00

meilisearch-operator

Go

A Kubernetes operator that manages Meilisearch instances natively inside a cluster: provisioning, master keys, API keys, indexes, backups and version upgrades, all driven by Custom Resources.

What it does, and who it is for

The operator is aimed at cluster admins running Meilisearch for several teams, and at DevOps/SRE engineers who want provisioning, upgrades and backups automated rather than hand-held.

It is built around three design principles:

  • Declarative first — designed for GitOps. Everything about a managed instance is expressed in a Custom Resource, not in an imperative setup step.
  • Fail fast — configurations are validated rather than half-applied. Instance resources go through a validating admission webhook (internal/webhook/v1alpha1/), and the CRDs carry CEL validation rules (for example, a BackupStorageLocation must configure exactly one backend).
  • Zero config — sensible production defaults, so a minimal Instance is a usable one: non-root pod security context, dropped capabilities, RuntimeDefault seccomp, and a generated master key.

Capabilities currently implemented in-tree:

  • Instance lifecycle — the operator owns the Deployment, Service, PersistentVolumeClaim and ServiceMonitor for an instance, and generates its master key into a Secret (MasterKeyReady condition).
  • Version upgrades — two workflows in internal/controller/workflow_upgrade.go: the default dump/import path, or in-place database migration via spec.dumplessUpgrade.
  • API key management — self-service scoped keys with optional expiry and rotation.
  • Index management — indexes and their full search settings reconciled from CRs.
  • Backups — native Meilisearch snapshots and dumps shipped to a storage location through an rclone sidecar. Namespaced and cluster-scoped storage locations, with S3, GCS, Azure Blob, PVC and custom-rclone backends.
  • Observability — optional Prometheus metrics per instance plus a ServiceMonitor (config/prometheus/).

Custom resources

All kinds live in API group meilisearch.k8s.icb4dc0.de, version v1alpha1 (see api/v1alpha1/). CRD manifests are generated into config/crd/bases/.

Kind Scope What it is for
Instance Namespaced A Meilisearch deployment: version, container image, resources, PVC storage, telemetry, backup config and upgrade strategy. The operator generates and stores its master key.
APIKey Namespaced A Meilisearch API key scoped to a set of actions and indexes, with optional expiresAt/expiresAfter and description. The key is written to a Secret.
Index Namespaced An index on an Instance, including primary key and the full search settings (searchable/filterable/sortable attributes, ranking rules, stop words, synonyms, typo tolerance) and a Delete/Retain reclaim policy.
Snapshot Namespaced A record of one Meilisearch snapshot in remote storage — task UID, filename, rclone remote and path, and the Meilisearch version it can be restored into.
Dump Namespaced A record of one Meilisearch dump in remote storage — dump UID, filename, rclone remote and path, plus a phase (Pending/Completed/Failed).
BackupStorageLocation Namespaced A backup target usable by instances in the same namespace. Exactly one of s3, gcs, azure, customRclone or pvc.
ClusterBackupStorageLocation Cluster The same, shared across namespaces. pvc is rejected here — it is namespaced-only.

A minimal instance, taken from config/samples/meilisearch_v1alpha1_instance.yaml:

apiVersion: meilisearch.k8s.icb4dc0.de/v1alpha1
kind: Instance
metadata:
  name: instance-sample
spec:
  version: v1.49.0
  meilisearch:
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 100m
        memory: 512Mi
  storage:
    size: 2Gi
    accessModes:
      - ReadWriteOnce

Quick start

Not verified in this form. The commands below are the repository's own recipes (justfile, AGENTS.md, dev/BUILD.bazel), but they were not executed while this README was written — the authoring environment had no Bazel, Docker or Kubernetes available. Treat them as untested end to end.

Prerequisites: Bazel (via bazelisk), Docker, and optionally just. The remaining tooling — Go, kind, kubectl, kustomize, hugo, buildifier — is fetched by Bazel; bazel run //tools:bazel_env puts it on your PATH.

# 1. Start a local Kind cluster.
#    Creates the "meilisearch-operator-debug" cluster plus a local registry on
#    localhost:5005, then applies config/deps: cert-manager, prometheus-operator,
#    SeaweedFS (an S3 target for backup tests) and this operator's CRDs.
just start-dev-cluster      # or: bazel run //dev:start_cluster

# 2. Build, deploy and run the operator in the cluster, with sample resources.
just dev                    # or: bazel run //dev:dev

just dev compiles the operator, builds the controller container image, pushes it to the local registry created by just start-dev-cluster, and applies the CRDs, the operator manifests and the sample resources from config/dev to the Kind context. After these two commands the operator is running in the cluster and you can debug it there.

Tear the cluster down with just teardown-cluster (bazel run //dev:teardown_cluster).

Running the operator from your shell (e.g. under dlv) should also be possible with bazel run //:go -- run ./cmd/main.go against the Kind cluster, but this is untested and normally not needed.

cmd/main.go takes the usual controller-runtime flags — --metrics-bind-address, --health-probe-bind-address, --leader-elect, --metrics-secure, --cluster-domain and the webhook certificate paths. Run it with --help for the full list.

For a real cluster, config/release/default is the released overlay; it pins the controller image by digest (registry.icb4dc0.de/k8s/meilisearch-operator/controller). Upgrading means bumping that newTag/digest pair and re-applying — CRDs are included in the overlay, so apply them with kustomize build + kubectl apply --server-side.

Build, test and format

Same caveat as above: these are the commands from AGENTS.md and the justfile, not run here.

# Build everything, including nogo static analysis (this is the lint gate)
just build                  # or: bazel build //...

# Full test suite, including the envtest-backed controller tests
just test                   # or: bazel test //...

# Narrower: a single package. The controller and webhook tests need envtest;
# packages like internal/version, internal/rclone and internal/jsonmerge do not.
bazel test //internal/version/...

# Format Go and Bazel files
just format                 # bazel run //:format && bazel run //:buildifier -- -r .

# Regenerate Bazel build files after adding/moving Go packages
just gazelle                # or: bazel run //:gazelle

# Regenerate CRD manifests, deepcopy code and API reference docs
just generate-crd-manifests # or: bazel run //dev:generate_crd_code

# Refresh go-snaps snapshots
bazel run //dev:update_snapshots

# Tidy modules
bazel run //:go -- mod tidy

bazel build //... is the quality gate — the //:nogo target runs a large analyzer set (staticcheck plus golangci-lint analyzers bridged into nogo; see the nogo rule in BUILD.bazel and the mirrored import list in analyzers.go) as part of every build, so there is no separate lint step.

Tests use Ginkgo v2 + Gomega with envtest for the controllers, go-snaps for snapshot assertions and alecthomas/assert/v2 for plain assertions. Controller tests live next to their controller in internal/controller/.

CI runs on Forgejo Actions (.forgejo/workflows/go.yaml): the full bazel test //... on every push to main and every pull request, plus a multi-arch image build. Tagged pushes additionally publish the image.

Repository layout

Path Contents
api/v1alpha1/ CRD Go types and generated deepcopy code
cmd/main.go Operator entrypoint
internal/controller/ Reconcilers for Instance, APIKey, Index, Snapshot and Dump, plus the provisioning and upgrade workflows and the Meilisearch task webhook receiver
internal/webhook/v1alpha1/ The Instance validating admission webhook
internal/meilisearch/ Meilisearch HTTP client and helpers
config/ Kustomize overlays: crd, default, dev, release, rbac, prometheus, samples, deps
dev/ Kind cluster setup, local dev deploy, code/manifest generation
docs/content/ User documentation
test/ End-to-end and integration tests
build/, tools/ Bazel toolchains, envtest binaries, bazel_env tool wiring

Documentation

Full documentation lives in docs/content/docs/:

License

MIT. See LICENSE.