- Go 88.2%
- Starlark 9.8%
- Shell 1.6%
- Go Template 0.3%
| .agents/rules | ||
| .devcontainer | ||
| .forgejo/workflows | ||
| .zed | ||
| api | ||
| build | ||
| cmd | ||
| config | ||
| dev | ||
| docs | ||
| hack | ||
| internal | ||
| openspec | ||
| platforms | ||
| test | ||
| tools | ||
| .bazelrc | ||
| .bazelversion | ||
| .custom-gcl.yml | ||
| .dockerignore | ||
| .editorconfig | ||
| .envrc | ||
| .gitattributes | ||
| .gitignore | ||
| .golangci.yml | ||
| .kata.toml | ||
| .nogo.json | ||
| AGENTS.md | ||
| analyzers.go | ||
| apm.lock.yaml | ||
| apm.yml | ||
| BUILD.bazel | ||
| CLAUDE.md | ||
| cliff.toml | ||
| crd-docs.yaml | ||
| go.mod | ||
| go.sum | ||
| justfile | ||
| LICENSE | ||
| MODULE.bazel | ||
| MODULE.bazel.lock | ||
| PROJECT | ||
| README.md | ||
| renovate.json | ||
meilisearch-operator
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.
Instanceresources go through a validating admission webhook (internal/webhook/v1alpha1/), and the CRDs carry CEL validation rules (for example, aBackupStorageLocationmust configure exactly one backend). - Zero config — sensible production defaults, so a minimal
Instanceis a usable one: non-root pod security context, dropped capabilities,RuntimeDefaultseccomp, 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
(
MasterKeyReadycondition). - Version upgrades — two workflows in
internal/controller/workflow_upgrade.go: the default dump/import path, or in-place database migration viaspec.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/:
instance.md— theInstanceresourceindex.md— theIndexresource and search settingsbackup_storage_location.md— backup targetsapi/meilisearch.k8s.icb4dc0.de.md— generated API reference for every kind and field
License
MIT. See LICENSE.