operator-sdk-extra

operator-sdk-extra

This framework is an extension of operator-sdk. Its goal is to eliminate repetitive boilerplate when writing Kubernetes operators: finalizer management, status tracking, resource diff computation, and automatic create/update/delete orchestration.

After writing several operators, we identified 3 distinct use cases, each handled by a dedicated reconciler pattern:

Patterns overview

Multiphase Reconciler

Use it when your CRD creates and orchestrates a sequence of Kubernetes resources (e.g. a ConfigMap, then a Deployment). Each resource type is handled by its own step reconciler, executed sequentially by a main reconciler.

A Server-Side Apply (SSA) engine delegates diff computation and conflict detection to the Kubernetes API server, producing apply / delete operations automatically.

Read the full documentation

Remote Reconciler

Use it when your CRD manages resources external to Kubernetes via API calls (e.g. Elasticsearch roles, database users, cloud resources).

The pattern relies on a generic RemoteExternalReconciler that wraps your API client (Build, Get, Create, Update, Delete) and a 3-way merge diff that stores the last applied configuration as a compressed object in the CRD status.

Read the full documentation

Sentinel Reconciler

Use it when you need to watch standard Kubernetes resources that your operator does not own — such as Ingresses, Secrets or ConfigMaps — and create derived resources based on their annotations or labels.

Unlike the other patterns, the Sentinel reconciler does not use a finalizer: child resources are cleaned up automatically by Kubernetes garbage collection through owner references.

Read the full documentation

Project structure

operator-sdk-extra/
├── pkg/
│   ├── apis/                   Status type definitions (DefaultObjectStatus, shared types)
│   │   ├── multiphase/         DefaultMultiPhaseObjectStatus
│   │   ├── remote/             DefaultRemoteObjectStatus
│   │   └── shared/             PhaseName, ConditionName, FinalizerName
│   ├── controller/
│   │   ├── controller.go       Controller interface and setup helpers
│   │   ├── reconciler.go       Reconciler interface (finalizer, logger, recorder)
│   │   ├── multiphase/         Multiphase pattern implementation
│   │   ├── remote/             Remote pattern implementation (generic [k8sObject, apiObject, apiClient])
│   │   └── sentinel/           Sentinel pattern implementation (generic [k8sObject])
│   ├── helper/                 Utilities: diff, merge, slice ops, rate limiter, zip, CRD detection
│   ├── mock/                   Generated mocks for testing
│   ├── object/                 ObjectStatus, MultiPhaseObject, RemoteObject interfaces
│   └── test/                   TestCase / TestStep framework for integration tests
├── cmd/crd/                    CLI tool: clean-crd (remove @clean tagged fields from CRD YAML)
├── samples/
│   ├── memcached-operator/       Multiphase pattern sample
│   ├── elasticsearch-operator/   Remote pattern sample
│   └── ingress-sentinel-operator/ Sentinel pattern sample
├── documentations/             Pattern-specific documentation
├── ci/dagger/                  Dagger CI pipeline module
├── dagger.json                 Dagger module configuration
└── Makefile                    Local development targets

Quick start

Prerequisites

• Go 1.24+
• Dagger CLI
• kubectl
• direnv (recommended)

As a Go module dependency

go get github.com/disaster37/operator-sdk-extra/v3@latest

Refer to the Multiphase, Remote or Sentinel documentation to implement the pattern that fits your use case.

Upgrading from v1? This is a major, breaking release (new /v2 module path, package split, and a switch from client-side 3-way diff to Server-Side Apply for the multiphase and sentinel patterns). Follow the v1 → v2 migration guide.

Upgrading from v2? This release adds a new /v3 module path. Follow the v2 → v3 migration guide.

Run the full CI pipeline locally (without pushing)

dagger call --src . ci

See CONTRIBUTING.md for the full list of available commands.

Ignore reconciliation

If you need to manually update a resource managed by an operator without it being reconciled back, add the following annotation:

annotations:
  operator-sdk-extra.webcenter.fr/ignoreReconcile: "true"

Key features

• Finalizer management: automatic add / remove on create / delete
• Status tracking: deep-copy + deferred-update only persists status when it actually changed
• Server-Side Apply: multiphase and sentinel patterns use SSA for precise apply / delete with native field ownership
• 3-way merge diff (remote pattern): current vs. expected vs. last-applied-configuration to compute precise create / update / delete lists
• Rate limiter: less aggressive than the default (1s to 1000s exponential backoff, 10 QPS bucket)
• Annotation-based reconciliation skip via operator-sdk-extra.webcenter.fr/ignoreReconcile
• Sentinel pattern: watch any K8s resource, derive children, rely on GC for cleanup

Samples

Each pattern has a reference operator implementation in samples/ with its own go.mod and a replace directive pointing to the framework source:

To build a sample, run go build ./... from its directory. The replace directive in its go.mod uses the framework from the local source tree (../../).

License

Apache 2.0 — see LICENSE.