Operator SDK: scaffolding and high-level APIs for Kubernetes operators

What Operator SDK removes from the operator-writing job

Writing an operator without a framework means handling low-level client-go APIs, repeating boilerplate for watches and reconciliation, and copying project structure from an earlier operator because there is no generator. The README names exactly those three problems: low-level APIs, boilerplate, and a lack of modularity that leads to duplication.

Operator SDK is a framework built on controller-runtime. It adds three things on top: high-level APIs and abstractions for operational logic, scaffolding and code generation to bootstrap a project, and extensions for common operator use cases. It is one component of the Operator Framework, the wider toolkit for managing Kubernetes-native applications.

The intended user is a team that treats an operator as a product with its own release cycle, not someone writing a throwaway controller. The repository layout supports that reading: cmd/, internal/, config/, test/, testdata/, release/, proposals/, changelog/ and website/ all sit at the top level, which is the shape of a project that generates other projects and publishes a CLI.

How the scaffolding, plugins and generated code fit together

The SDK is a CLI that generates and then drives a project. The generated project depends on controller-runtime, which is the library that actually talks to the API server and runs reconcile loops. Operator SDK does not replace it; the README describes the SDK as a framework that uses controller-runtime to make operators easier to write.

The module graph shows how thin the SDK's own runtime layer is and how much it delegates. The go.mod requires sigs.k8s.io/controller-runtime v0.21.0, sigs.k8s.io/controller-tools v0.18.0 for code generation, sigs.k8s.io/kubebuilder/v4 v4.6.0 for the scaffolding engine, and k8s.io/client-go v0.33.9 plus the matching k8s.io/api and k8s.io/apimachinery at v0.33.9. Helm-based and Ansible-based operators are not separate codebases: the module pulls in helm.sh/helm/v3 v3.18.6 and github.com/operator-framework/ansible-operator-plugins v1.42.3, so those project types are plugins over the same CLI.

Two details in the Makefile show how versions are pinned. K8S_VERSION is set to 1.33.1 and KIND_VERSION to 0.29.0, and the build injects these into the binary through -ldflags, writing internal/version.KubernetesVersion and internal/version.ImageVersion. IMAGE_VERSION is set to v1.42.3, matching the most recent release, and the Makefile comment states that this value must be updated to the release tag of the most recent release in the release commit. Builds also set CGO_ENABLED = 0 and use the containers_image_openpgp build tag, which matters if you build the CLI yourself rather than downloading a binary.

Installing operator-sdk and scaffolding a first Go project

The README does not carry install instructions. It points at the Operator SDK website for documentation and at the developer guide for the Go compiler version used to build release binaries. Get the CLI from the project's documented installation path, then confirm it answers before generating anything.

The README gives no command syntax, so the only reliable way to see the available subcommands and flags is the CLI's own help output. Nothing in the README or the repository files given here shows a concrete invocation, so there is no command to quote.

Generated projects declare their Go version in go.mod, and the README states that a Go operator project's Go version can be found there. Read that file first if your build environment has an older toolchain, because it is the authoritative statement for the project rather than the SDK repository's own go directive.

For the operator itself, the workflow the SDK is built around is: scaffold the API type, write the reconcile logic, run the code generation targets from the Makefile, and deploy the resulting manifests from config/ to a cluster. The Makefile's generate target removes testdata/ and runs ./hack/gen to regenerate CLI docs and samples, which is the same generator path the project uses on itself.

The kube-rbac-proxy removal is the migration you have to plan

The most consequential thing in the README is a warning, not a feature. Images under gcr.io/kubebuilder/ will become unavailable, and any project that pulls gcr.io/kubebuilder/kube-rbac-proxy is affected. The README states plainly that such a project may fail to work if the image cannot be pulled and that you must move as soon as possible, with the GCR registry going away from early 2025.

This is a breaking change delivered outside your release cycle. A running operator that references that image is fine until the node needs to pull it again, at which point the failure appears during a reschedule or a fresh install rather than during development.

The replacement is not another sidecar. The README says kube-rbac-proxy was discontinued in both Kubebuilder and Operator SDK and replaced with similar protection using authentication and authorization through controller-runtime's WithAuthenticationAndAuthorization feature. That means the protection moves into the metrics endpoint configuration inside your manager rather than sitting in front of it as a separate container. The README points at a Kubebuilder discussion for guidance; it does not provide a migration recipe itself, which is the weakest part of the documentation on this point.

Where Operator SDK is the wrong choice

If you want a single controller with no product packaging around it, the SDK adds a layer you will not use. Its scaffolding engine is Kubebuilder v4.6.0, and controller-runtime does the actual work either way. Choosing the SDK means adopting its CLI, its plugin model and its release process on top of the same foundation.

The version coupling is a second constraint. The SDK pins k8s.io/client-go v0.33.9 and controller-runtime v0.21.0, and the Makefile pins K8S_VERSION to 1.33.1. The README defers supported Kubernetes versions to a compatibility guide on the website rather than listing them. If you run a cluster outside that range, check the guide before starting, because the pinned client libraries are what your operator will use.

A third case is a team that cannot rebuild images on demand. Because the kube-rbac-proxy change is a registry removal, an operator frozen on an old scaffold has a real operational risk that has nothing to do with its own code quality. The SDK cannot fix that for you; only regenerating and redeploying can.

Operator SDK compared with Kubebuilder and the language-specific SDKs

Kubebuilder is the closest alternative and the honest comparison, because Operator SDK embeds it. The difference is scope: Kubebuilder is the scaffolding and code-generation tool for Go operators, while Operator SDK is a CLI that adds project types beyond Go, a plugin architecture and packaging and release tooling around the same controller-runtime base. If your operator is Go-only and you do not need the extra project types, the SDK's additional surface buys you little. If you need Ansible or Helm based operators, or you want the SDK's release machinery, the comparison reverses.

The language-specific SDKs are a different kind of alternative. A Java Operator SDK or a Python operator framework targets teams whose operational logic already lives in that language, at the cost of a runtime that is not the Go toolchain the SDK's release binaries are built with. The search data around this project shows steady interest in Java, Python, Ansible and Helm variants, which matches the plugin structure in go.mod: Ansible and Helm are supported inside this repository, while other languages are separate projects with separate trade-offs.

One more distinction worth keeping straight: an operator is not the same thing as a controller. A controller is the reconcile loop; an operator is the packaging of one or more controllers plus the CRDs and deployment manifests that make it installable. Operator SDK generates the second thing, which is why its output includes config/ and release/ directories rather than only Go source.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-17, five days before this writing. Releases are frequent: v1.42.1 on 2026-03-09, v1.42.2 on 2026-03-19, and v1.42.3 on 2026-06-26. The changelog/ and proposals/ directories at the top level are where design changes are recorded before they land.

The upgrade cost is dominated by the pinned dependency set, not by the CLI itself. Moving to a new SDK release moves controller-runtime, controller-tools, client-go and the Kubernetes libraries together, and the Makefile's IMAGE_VERSION comment shows the project's own discipline of bumping that value in the release commit. Your project will feel the same bump in its go.mod, and the compatibility guide is the place to confirm the Kubernetes version your cluster runs is still in range.

Operator SDK is under the Apache 2.0 license, and the LICENSE file is at the repository root. Apache 2.0 includes an explicit patent grant and requires that notices be preserved, which matters if you vendor or redistribute the CLI. This is a description of the licence text, not legal advice; check your own obligations with counsel if you redistribute.

Editorial conclusion

Adopt Operator SDK if you are building a Kubernetes operator as a deliverable and want Go, Ansible or Helm scaffolding plus generated API types rather than hand-written controller plumbing. Do not adopt it if you only need one small controller, because Kubebuilder gives you the same controller-runtime base without the extra CLI and release machinery. Before committing, verify three things against your own cluster: that the Kubernetes version you run is listed in the compatibility guide, that no manifest still references gcr.io/kubebuilder/kube-rbac-proxy, and that your project's Go version in go.mod matches the compiler the release binaries are built with. The gcr.io/kubebuilder registry is the one item with a hard deadline attached to it.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. operator-framework/operator-sdk on GitHub
3. Project website
4. README
5. Releases