GO — Healthy across the board

• Last commit 3d ago
• 16 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Operator SDK is a framework for building Kubernetes Operators—applications that manage complex stateful services on Kubernetes—using high-level Go APIs and controller-runtime. It provides scaffolding, code generation, and abstractions to eliminate boilerplate, allowing developers to write operational logic intuitively rather than working directly with low-level Kubernetes APIs. Monorepo structure: internal/ contains core SDK logic, hack/ holds build/test utilities, test/ has integration tests, internal/plugins/ provides scaffold plugins (Go, Helm, Ansible). CLI entry point likely in cmd/operator-sdk/. Changelog managed via fragments in changelog/fragments/ that compile into generated/ release notes.

Go developers and platform engineers building production Kubernetes Operators who need to manage stateful applications (databases, message brokers, monitoring systems) without writing hundreds of lines of API boilerplate. Also used by operators.coreos.com maintainers who package operators for distribution.

Highly mature and production-ready. The codebase spans 1.3M+ lines of Go with active CI/CD workflows (test-go.yml, integration.yml, deploy.yml), generated changelogs through v1.20.0, and explicit support for Kubernetes 1.33.9 and Go 1.25.7. Weekly releases and maintained OWNERS files indicate active stewardship within the Operator Framework.

Low risk for core functionality but moderate dependency surface: 50+ direct Go dependencies including kubernetes/client-go, controller-runtime, and kubebuilder/v4. Notable recent concern: migration away from gcr.io/kubebuilder/kube-rbac-proxy (announced end-of-life early 2025), requiring projects to adopt controller-runtime's WithAuthenticationAndAuthorization. Breaking changes require careful changelog review between versions.

Active maintenance with recent releases (v1.20.0 changelog present). Current focus areas inferred from README: migration of projects away from deprecated kube-rbac-proxy, image freshening workflows (.github/workflows/freshen-images/), and integration testing across multiple Kubernetes versions. Dependabot configured for automated dependency updates.

git clone https://github.com/operator-framework/operator-sdk && cd operator-sdk && make install # builds operator-sdk binary (Makefile present, Go 1.25.7+ required per go.mod). Then operator-sdk init --domain example.com --repo github.com/example/myoperator to scaffold a new operator project.

Daily commands: make install # builds operator-sdk CLI; make test # runs Ginkgo suite; make integration # runs e2e tests. For development: make generate # runs code generation (controller-gen), make fmt # lints with golangci-lint (.golangci.yml). See Makefile and .github/workflows/test-go.yml for full build matrix.

• cmd/operator-sdk/main.go — Primary entry point for the operator-sdk CLI tool; all contributors must understand how commands are dispatched and initialized
• cmd/helm-operator/main.go — Entry point for the Helm Operator runtime; essential for understanding how Helm-based operators are executed
• go.mod — Declares all critical dependencies including controller-runtime, operator-lib, and operator-registry; version changes affect entire SDK behavior
• Makefile — Defines build, test, and release targets; contributors need this to understand the development workflow and CI/CD pipeline
• CONTRIBUTING.MD — Outlines contribution guidelines, code standards, and review process; mandatory reading for all contributors
• .github/workflows/test-go.yml — Primary CI/CD workflow validating Go code; shows how tests are run and what quality gates must pass
• hack/generate/olm_bindata.sh — Generates OLM (Operator Lifecycle Manager) bindata; critical for understanding how operator manifests are embedded

Add a New CLI Command

1. Create command handler in appropriate subpackage under cmd/operator-sdk following existing command patterns (cmd/operator-sdk/main.go)
2. Register command in the root CLI dispatcher, ensuring proper flag definitions and subcommand structure (cmd/operator-sdk/main.go)
3. Add integration test in .github/workflows/test-go.yml or create new workflow if testing against Kubernetes clusters (.github/workflows/test-go.yml)
4. Generate CLI documentation via hack/generate/cli-doc/gen-cli-doc.go and update README.md with usage examples (hack/generate/cli-doc/gen-cli-doc.go)

Add a New Operator Type or Plugin

1. Create scaffolding template in cmd/operator-sdk with initialization logic following helm-operator or ansible-operator patterns (cmd/operator-sdk/main.go)
2. Define CRD bases and manifests in config/crd/bases/ for your operator's API resources (config/crd/bases/_.yaml)
3. Create sample project in hack/generate/samples demonstrating the new operator type (hack/generate/samples)
4. Add workflow in .github/workflows/ (e.g., test-custom-operator.yml) to validate scaffolded operators (.github/workflows/test-go.yml)

Release a New SDK Version

1. Add changelog fragment in changelog/fragments describing changes for this release (changelog/fragments/00-template.yaml)
2. Update go.mod with any new dependency versions and run go mod tidy (go.mod)
3. Configure version and build settings in .goreleaser.yml to generate cross-platform binaries (.goreleaser.yml)
4. Trigger deploy.yml workflow which validates, builds, and publishes release artifacts (.github/workflows/deploy.yml)

Add Quality Gates or Linting Rules

1. Define linting rules and tool configuration in .golangci.yml (.golangci.yml)
2. Create validation script in hack/ directory (e.g., hack/check-*.sh) for custom checks (hack/check-license.sh)
3. Integrate check into test-go.yml workflow to run during CI/CD pipeline (.github/workflows/test-go.yml)

• Go 1.25.7 — Type-safe, fast compilation for cross-platform CLI tools; matches Kubernetes ecosystem standard
• controller-runtime (implicit via dependencies) — Core abstraction for Kubernetes operators; provides reconciliation loop, RBAC, and metrics patterns
• operator-registry — Enables OLM (Operator Lifecycle Manager) integration for distributing operators via catalogs
• Helm (via helm-operator) — Allows packaging existing Helm charts as Kubernetes operators without custom Go code
• Ansible (via ansible-operator-plugins) — Enables operators written in Ansible for users unfamiliar with Go
• GitHub Actions Workflows — Native CI/CD integrated with repository; validates code quality, tests, and automates releases

• Multi-language support (Go, Helm, Ansible) instead of single-language SDK

  • Why: Lowers barrier to entry; users can choose tools matching their expertise
  • Consequence: Increased maintenance burden; must test and support multiple scaffolding paths and runtimes

• Explicit code generation (scaffolding) rather than embedded DSL or heavy reflection

  • Why: Generated code is readable, debuggable, and doesn't hide complexity; users own all code
  • Consequence: SDK changes don't automatically propagate to existing projects; users must manually upgrade patterns

• Heavy reliance on go.mod dependency pinning rather than vendoring or bundling

  • Why: Cleaner repo structure; faster builds; easier to manage transitive dependencies
  • Consequence: Vulnerable to supply chain attacks; dependency updates can break compatibility

• OLM (Operator Lifecycle Manager) integration as first-class feature

  • Why: Aligns with OpenShift/K8s ecosystem standard for operator distribution and lifecycle management
  • Consequence: Adds complexity; OLM concepts may be unfamiliar to users building simple operators

• Does not manage Kubernetes cluster provisioning or setup; assumes target cluster exists
• Does not provide persistent data storage abstraction; assumes operators manage their own storage via Kubernetes primitives
• Does not enforce authentication/authorization between operators and Kubernetes API; relies on RBAC
• Does not provide operator-to-operator communication framework; each operator manages its own integration
• Does not offer graphical UI for operator development; CLI-first tool

No single obviously hidden trap, but several awareness points: (1) The kube-rbac-proxy deprecation (README warning) means scaffolded projects may need manual refactoring—check if your scaffold uses it. (2) Code generation is critical: make generate must run before tests pass; controller-tools and kubebuilder are implicit build dependencies. (3) Kubernetes version compatibility is non-trivial—see the compatibility guide URL in README; not all operator-sdk versions support all k8s versions. (4) Local testing requires a running Kubernetes cluster (via envtest or similar) visible in test/.

• Reconciliation Loop — Core pattern of operator-sdk: custom controllers repeatedly reconcile observed cluster state to desired state defined in CRDs; understanding this is essential to writing any operator
• Custom Resource Definition (CRD) — Operators extend Kubernetes by defining custom resources; operator-sdk scaffolds CRDs automatically and generates code to handle their lifecycle
• Webhook (Validating & Mutating) — operator-sdk generates webhook scaffolding to validate and mutate custom resources before they enter etcd; critical for API safety and defaults
• Code Generation (controller-gen) — operator-sdk relies on controller-tools (controller-gen) to generate deepcopy methods, CRD manifests, and RBAC from struct tags; must run before compilation
• RBAC (Role-Based Access Control) Generation — operator-sdk automatically generates Kubernetes RBAC manifests (Roles, RoleBindings, ClusterRoles) from operator code to enforce least privilege
• Operator Lifecycle Manager (OLM) Bundles — operator-sdk can package operators into OLM bundles (CSV, CRD manifests) for distribution on OperatorHub; bundle command handles this
• Finalizers & Garbage Collection — operator-sdk patterns use Kubernetes finalizers to clean up external resources when custom resources are deleted, preventing orphaned infrastructure

• kubernetes-sigs/kubebuilder — Parent/sibling framework providing CRD generation (controller-tools) and core patterns that operator-sdk wraps with higher-level APIs
• kubernetes-sigs/controller-runtime — Foundational library providing the reconciliation loop and webhook infrastructure that operator-sdk operators depend on (v0.21.0 in go.mod)
• operator-framework/api — Defines Operator Lifecycle Manager (OLM) CRDs and APIs that operator-sdk projects use to declare capabilities and versioning
• operator-framework/operator-registry — Companion tool for packaging, indexing, and serving Operators built with operator-sdk; used in the bundle and catalog workflows
• brancz/kube-rbac-proxy — Legacy RBAC proxy that many operator-sdk scaffolds currently reference but which is being deprecated (see README migration notice)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Helm operator scaffolding in test-helm.yml workflow

The .github/workflows/test-helm.yml workflow exists but there's no evidence of comprehensive integration tests for Helm-based operators. Given that operator-sdk supports Helm operators as a primary scaffold type (alongside Go and Ansible), new contributors could add end-to-end tests that verify: Helm chart generation, dependency resolution, and deployment validation. This directly supports the repository's core functionality.

• [ ] Review existing .github/workflows/test-helm.yml to understand current coverage gaps
• [ ] Create integration test cases in internal/cmd/operator-sdk/scaffolds (or appropriate test directory) that scaffold a Helm operator and verify its structure
• [ ] Add test cases that verify Helm chart templating, values.yaml generation, and basic deployment scenarios
• [ ] Update .github/workflows/test-helm.yml to execute new integration tests with documented assertions
• [ ] Document test cases in CONTRIBUTING.MD with Helm-specific testing guidelines

Add missing changelog fragments documentation and automation

The repo has a changelog/fragments directory with a template (00-template.yaml) but lacks clear contributor guidance on the fragment format and automated validation. The changelog system appears mature (v1.3.0 through v1.39.0 releases tracked), but new contributors often miss fragment requirements. This causes CI delays and maintainer rework.

• [ ] Document changelog fragment requirements in CONTRIBUTING.MD with examples of each fragment type (feat, bugfix, breaking, etc.)
• [ ] Create a GitHub Actions workflow (.github/workflows/validate-changelog.yml) that checks PRs include appropriate changelog/fragments/ entries
• [ ] Add validation script (similar to .github/workflows/check-docs-only.sh) that ensures fragment filenames follow the pattern and YAML is valid
• [ ] Update PULL_REQUEST_TEMPLATE.md to remind contributors about changelog fragments with a link to the documentation

Implement smoke tests for kube-rbac-proxy deprecation migration guidance

The README prominently warns about gcr.io/kubebuilder/ images becoming unavailable and references the switch to WithAuthenticationAndAuthorization. However, there's no automated test verifying that newly scaffolded operators don't inadvertently reference deprecated images. This is a critical migration concern for the community.

• [ ] Create a validation test in internal/cmd/operator-sdk/scaffolds (or appropriate test location) that runs 'operator-sdk init' and 'operator-sdk create api' for Go/Helm/Ansible operators
• [ ] Add assertions that verify generated Dockerfile, manager deployment manifests, and CI configurations do NOT reference gcr.io/kubebuilder/kube-rbac-proxy
• [ ] Create a test that validates controller-runtime metrics configuration uses WithAuthenticationAndAuthorization where applicable
• [ ] Add this test to .github/workflows/test-go.yml, .github/workflows/test-helm.yml, and integration.yml to catch regressions
• [ ] Document the expected image sources and authentication approach in internal documentation or CONTRIBUTING.MD

• Add missing integration tests for the Helm plugin scaffold—test/e2e/ likely lacks comprehensive helm-specific e2e scenarios (plugin manifests exist but coverage gaps suggest test opportunities)
• Improve internal/api/ documentation with godoc comments on exported types (controller-runtime expects well-documented CRD structs; many core types lack inline comments)
• Add a missing migration guide in docs for projects still using gcr.io/kubebuilder/kube-rbac-proxy—the README warns of deprecation but internal/ and scaffolding likely still reference it in templates

The operator-sdk repository shows a generally reasonable security posture with documented security policies, but has a critical issue with storing an encrypted GPG secret keyring in version control. Additionally, the Go version declaration appears suspicious (1.25.7 is unrealistic), and there is incomplete visibility into the full dependency tree due to file truncation. Key recommendations include: (1) immediately removing the GPG secret key from version control, (2) verifying the Go version, (3) conducting a full vulnerability scan of all dependencies, and (4) implementing secure secret management practices outside of source control. The codebase lacks visible injection vulnerabilities based on file structure analysis, but proper dependency scanning is essential before full clearance.

• High · Encrypted GPG Secret Key Stored in Repository — .ci/gpg/secring.auto.gpg. The file '.ci/gpg/secring.auto.gpg' appears to be an encrypted GPG secret keyring stored in the repository. While encrypted, storing secret keys in version control (even encrypted) is a security risk and violates key management best practices. If the encryption is compromised or the passphrase is leaked, the secret key is exposed. Fix: Remove the secret keyring from version control immediately. Use secure secret management practices: store keys in environment variables, CI/CD secrets management, or dedicated key management services (e.g., HashiCorp Vault). Add .ci/gpg/secring.auto.gpg to .gitignore.
• Medium · Outdated Go Version — go.mod (module file). The module declares 'go 1.25.7' which appears to be an unrealistic Go version (as of the analysis context). This suggests either a configuration error or an intentionally future version declaration that could mask dependency issues. Current Go versions are in the 1.20-1.23 range. Fix: Verify and update the Go version to a currently supported and stable release (1.22 or later). Ensure all dependencies are compatible with the declared Go version.
• Medium · Multiple Indirect Dependencies with Potential Vulnerabilities — go.mod (entire dependency list). The dependency file is truncated and shows many indirect dependencies that should be audited. Several common packages used in the dependencies (Kubernetes client libraries, Helm, controller-runtime) may have known CVEs that need checking. The file appears to be incomplete ('github.c' truncation suggests cut-off content). Fix: Run 'go list -json -m all | nancy sleuth' or 'govulncheck ./...' to identify known vulnerabilities in dependencies. Review the complete go.mod file for any flagged CVEs and update affected packages to patched versions.
• Medium · GPG Keyring Creation Script in Repository — .ci/gpg/create-keyring.sh. The '.ci/gpg/create-keyring.sh' script is present in the repository. Automated keyring creation scripts can be leveraged to regenerate or misuse keys if an attacker gains repository access. The script's permissions and usage should be strictly controlled. Fix: Remove key generation scripts from the repository or move them to a secure, access-controlled CI/CD system. If needed, document that key generation should only occur in isolated, authenticated CI environments. Ensure the script is not executable by default.
• Low · Public GPG Public Keyring Exposed — .ci/gpg/pubring.auto. The '.ci/gpg/pubring.auto' file contains the public GPG keyring. While public keys are not sensitive by design, storing them alongside secret keys in the same directory increases the risk of inadvertent exposure of associated metadata. Fix: If this public key is needed by the project, document its purpose clearly. Consider storing it in a dedicated public key location or referencing it from a trusted key server instead of bundling it in the repository.
• Low · Incomplete Dependency File Review — go.mod (truncated at indirect dependencies). The go.mod file content is truncated ('github.c' incomplete), preventing complete security analysis of all dependencies. Several packages like helm.sh, k8s.io, and sigs.k8s.io are large frameworks with extended dependency trees that require full visibility. Fix: Provide the complete go.mod and go.sum files for full security analysis. Regularly run 'go mod verify' to ensure integrity and 'go mod tidy' to remove unused dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/operator-framework/operator-sdk shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live operator-framework/operator-sdk repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/operator-framework/operator-sdk.

What it runs against: a local clone of operator-framework/operator-sdk — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in operator-framework/operator-sdk | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of operator-framework/operator-sdk. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/operator-framework/operator-sdk.git
#   cd operator-sdk
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of operator-framework/operator-sdk and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "operator-framework/operator-sdk(\\.git)?\\b" \\
  && ok "origin remote is operator-framework/operator-sdk" \\
  || miss "origin remote is not operator-framework/operator-sdk (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/operator-sdk/main.go" \\
  && ok "cmd/operator-sdk/main.go" \\
  || miss "missing critical file: cmd/operator-sdk/main.go"
test -f "cmd/helm-operator/main.go" \\
  && ok "cmd/helm-operator/main.go" \\
  || miss "missing critical file: cmd/helm-operator/main.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "CONTRIBUTING.MD" \\
  && ok "CONTRIBUTING.MD" \\
  || miss "missing critical file: CONTRIBUTING.MD"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/operator-framework/operator-sdk"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.