operator-sdk carries a deprecation notice before it carries anything else

kube-rbac-proxy images are going away from gcr.io

The readme opens with an important notice rather than a description, and that ordering is informative. Images under gcr.io/kubebuilder/ will be unavailable soon. If your project uses gcr.io/kubebuilder/kube-rbac-proxy it will be affected, and the project may simply fail to work if the image cannot be pulled. The advice is to move as soon as possible, with the timeline given as sometime from early 2025 when the GCR goes away.

What replaced it is specified rather than left open. The usage of kube-rbac-proxy was discontinued from Kubebuilder and from the Operator SDK, and the similar protection is now provided using authentication and authorization through controller-runtime's WithAuthenticationAndAuthorization feature. The readme points at a kubebuilder discussion for the longer reasoning. If you are reading this because a project will not start, that notice is the first thing to check.

The framework sits on controller-runtime, not on raw client-go

The SDK describes itself as a framework that uses controller-runtime to make writing operators easier. That single choice explains most of what the project is. The problems it claims to solve are low level APIs, boilerplate, and a lack of modularity that leads to duplication, and the three things it provides in response are high level APIs and abstractions for writing operational logic more intuitively, tools for scaffolding and code generation to bootstrap a project quickly, and extensions covering common Operator use cases.

The module file reflects that layering. sigs.k8s.io/controller-runtime is required at v0.21.0, with sigs.k8s.io/kubebuilder/v4 at v4.6.0 for the scaffolding machinery, sigs.k8s.io/controller-tools at v0.18.0, and the Kubernetes libraries api, apimachinery, client-go, kubectl, cli-runtime and apiextensions-apiserver all pinned at v0.33.9. So the dependency you actually reason about is controller-runtime, and the SDK is the layer that makes it pleasant.

The Makefile still carries versions for two departing subprojects

One line in the Makefile carries more history than it looks like it does. IMAGE_VERSION is exported as v1.42.3, and a comment above it explains that this value represents the helm-operator and scorecard subproject versions. It must be updated to the release tag of the most recent release, and the change has to happen in the release commit.

The comment then states the plan: IMAGE_VERSION will be removed once each subproject that uses this value is moved to a separate repo and release process. So the repository is in the middle of a split, with helm-operator and scorecard still versioned from here, and the mechanism that keeps their images consistent scheduled for deletion.

For anyone vendoring or mirroring images, that is the practical consequence. The version they will be tagged with is decided in one place in one file, and that place has a removal condition attached to it in the source.

Version information is stamped in at link time

There is no version file to edit. The Makefile derives everything from git and injects it through linker flags. SIMPLE_VERSION is the exact tag when HEAD sits on one, and the nearest tag plus a git suffix otherwise, so a build from a commit reads differently from a release build. GIT_VERSION and GIT_COMMIT come from git describe and git rev-parse.

Those values are written into the binary with a set of -X ldflags targeting the internal/version package, one per field: Version, GitVersion, GitCommit, KubernetesVersion and ImageVersion. The Kubernetes one is prefixed with a v in the flag, so a K8S_VERSION of 1.33.1 is stamped as v1.33.1.

Two other build settings matter if you reproduce a build. CGO_ENABLED is exported as 0, and the build tag containers_image_openpgp is set. Build paths are also trimmed out of the binary with -trimpath for both the compiler and the assembler, which is why GO_ASMFLAGS and GO_GCFLAGS look nearly identical.

The plugin set is where Ansible and Helm live

The Go module shows how wide the surface is, and it is wider than controller-runtime alone. operator-framework/ansible-operator-plugins is required at v1.42.3, matching the SDK's own version, which is how the Ansible operator path is carried inside this repository. helm.sh/helm/v3 comes in at v3.18.6 for the Helm side. Two more Operator Framework projects appear as direct requirements: operator-lib at v0.19.0 and operator-registry at v1.59.0, along with operator-manifest-tools at v0.10.0.

Around those sit the tools a Kubernetes Go project normally needs, including cobra, viper, pflag and afero for the command line, testify plus ginkgo and gomega for tests, counterfeiter for generated fakes, and a handful of small helpers such as strcase, inflect, go-funk and go-diff. The effect is that the SDK is not a thin wrapper: it is a distribution of the pieces an operator project ends up needing anyway.

Kubernetes 1.33 and Go 1.26 are the current constants

Two numbers tell you what the current line is built against. The module file requires Go 1.26.3, and the Makefile exports K8S_VERSION as 1.33.1, which lines up with the k8s.io libraries pinned at v0.33.9 in the module file. KIND_VERSION is exported as 0.29.0, which is the Kubernetes-in-Docker runtime the integration tests are expected to use.

The readme does not hardcode these for your project; it points you at references instead. Release binaries are built with the Go compiler version specified in the developer guide, and the Go version for a Go Operator project is the one in its own go.mod file. Supported Kubernetes versions are determined by the compatibility guide, and the supported platform tables cover all binaries and images.

That division of labour is the sensible one to internalise: this repository's numbers describe how the SDK itself was built, and the two guides describe what your project should target.

The tree carries the process as well as the code

Alongside cmd/, internal/, config/, test/ and testdata/, the repository keeps the artefacts of being a foundation project. changelog/ and release/ sit next to proposals/, OWNERS and OWNERS_ALIASES describe who reviews what, and .cncf-maintainers records the CNCF maintainer entries. SECURITY.md, code-of-conduct.md and CONTRIBUTING.MD cover the process side, while .goreleaser.yml drives releases and .golangci.yml drives linting.

The website directory and the top-level netlify.toml explains the long link reference definitions in the readme, since the documentation site is what those references resolve to. hack/ holds the generators, and the generate target makes the point that generated files are checked in: it removes testdata and regenerates it by running go run ./hack/gen, which also produces the CLI docs and samples. The tools directory holds binaries under tools/bin and scripts under tools/scripts, and the Makefile puts tools/bin and the build directory on PATH.

Editorial conclusion

Take operator-sdk when you are writing a Go operator and want controller-runtime's machinery with scaffolding around it. Do not take it on the assumption that kube-rbac-proxy is still available, since that usage was discontinued from both Kubebuilder and the SDK in favour of controller-runtime's WithAuthenticationAndAuthorization filter. Before you start, check the compatibility guide for your Kubernetes version, read the developer guide for the Go compiler version release binaries are built with, and confirm your own go.mod matches what you intend to compile against.

Frequently asked questions

Official sources

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