Project: Operator Framework (App Definition and Development / Application Definition & Image Build)
File: kubebuilder-integration.md

title: Operator-SDK integrates Kubebuilder for Golang Operators authors: "@hasbro17" "@estroz" reviewers: "@joelanford" "@jmrodri" "@dmesser" approvers: "@joelanford" "@jmrodri" "@dmesser" creation-date: 2019-12-19 last-updated: 2020-03-05 status: implementable see-also: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/integrating-kubebuilder-and-osdk.md https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md replaces: [] superseded-by: [] \[x\] Enhancement is `implementable` \[x\] Design details are appropriately documented from clear requirements \[ \] Test plan is defined \[ \] Graduation criteria for dev preview, tech preview, GA \ The Operator SDK should become compatible with Kubebuilder so that it has the same project layout and CLI workflow for developing Go operators. To achieve this goal without duplicating upstream code, the SDK should integrate Kubebuilders CLI to reuse the scaffolding for project creation and lifecycle management. At the same time the SDK should still be able to provide SDK specific features that work with the new project layout. In order for the SDK to wrap and reuse Kubebuilder while still maintaining the SDK binary as the entrypoint, Kubebuilder should be extended with a CLI interface that supports registering plugins. This lets the SDK reuse Kubebuilders existing scaffolding code for Go operators, while still being able to extend the CLI for SDK specific features/sub-commands and provide custom plugins that will allow the SDK to scaffold different project types like Helm/Ansible in the future. The Operator SDK and Kubebuilder largely provide the same experience for developing Go operators since both projects defer to APIs provided by the same upstream projects. The two projects differentiate in their CLI and UX of project setup, layout, and lifecycle management. These differences are largely incidental of how the two projects developed over time and not due to any use cases that are only addressed by either UX. By adopting the same workflow and layout as Kubebuilder, the SDK gains better alignment with the upstream community for writing Go operators. This allows the SDK to be used interchangeably with Kubebuilder projects, which unifies the experience of writing Go operators and resolves confusion on why the Operator SDK and Kubebuilder differ in their UX to achieve the same goals. This lets the SDK focus more on features that are outside the scope of Kubebuilder, such as Operator Lifecycle Manager (OLM) integration and Scorecard. Reusing the project scaffolding from Kubebuilder also reduces duplication in the SDK. This frees up Operator SDK maintainers to focus more on collaborating with the Kubebuilder maintainers on the upstream controller-runtime and controller-tools projects Operator developers get the project layout and scaffolding for Golang Operators from Kubebuilder Operator developers can use the same command line switches as Kubebuilder to create and extend the project This ensures Operator SDK binary compatibility with existing Kubebuilder projects. An Operator Developer is notified about deprecation of `new --type=go` once `init` subcommand is in

An Operator Developer should see the current UX maintained for these features: CSV generation, scorecard, and test-framework Operator developers can re-use an existing Kubebuilder project for Go-based Operators Operator developers uses the same Dockerfile and base image as Kubebuilder when using the upstream operator-sdk An Operator Developer has documentation that tells them how to use a different base image. An Operator Developer can leverage the Makefile from kubebuilder to instantiate the Operator locally Operator Developers can use cert-manager to generate TLS certificates for their webhook servers An Operator Developer can use the new plugin interface to scaffold and manage helm and ansible projects While Kubebuilders new plugin based CLI architecture should allow the SDK to extend it for scaffolding Helm/Ansible projects, the implementation of those plugins is not currently in scope for this proposal. An Operator Developer can use the Makefile to run an Operator and is notified about the deprecation of `up local` Webhook support for Ansible/Helm based operators Status: Done The complete proposal can be viewed . After upstream discussions with the Kubebuilder maintainers there is consensus that Kubebuilder should support an interface to register plugins that would be used to provide the implementation of CLI commands. This way Kubebuilder would not have to directly expose its CLI for the SDKs consumption: the SDK would reuse Kubebuilders plugins to scaffold new projects (`init`) and modify existing ones (`create`) while also being able to register its own plugins to extend the CLI for SDK specific subcommands (ex. `generate csv`, `scorecard`). This plugin interface should also allow the SDK to provide custom plugin implementations for the `init` and `create` subcommands so that it can customize the scaffolding of Helm and Ansible projects. There is a on Kubebuilder for the design of such a plugin interface. The aim of this story is to address all reviewer comments to achieve consensus on the plugin architecture and merge the proposal. After the plugin interface proposal has been accepted, the implementations of the plugin interface and the CLI pkg should be added to Kubebuilder. This involves writing plugin implementations for the following scaffolding subcommands in Kubebuilder so that the SDK can register them for reuse in its own CLI: `kubebuilder init` `kubebuilder create api` `kubebuilder create webhook` The goal of this story is to ensure a release of Kubebuilder that supports the new plugin interface that the SDK can integrate downstream into its own CLI. Once Kubebuilder supports plugin registration, the SDK CLI should be modified to reuse Kubebuilders CLI and plugins so that the SDK workflow for developing Go operators is identical to Kubebuilders workflow. Project initialization and api/webhook scaffolding would be provided by the upstream Kubebuilder CLI and plugins: `operator-sdk new` ==> `operator-sdk init` `operator-sdk add api/controller` ==> `operator-sdk create api` `operator-sdk create webhook` Other SDK subcommands can be removed and replaced by their equivalent Makefile targets in the Kubebuilder workflow after ensuring that they fulfill all the same use

`operator-sdk generate k8s` ==> `make generate` `operator-sdk generate crds` ==> `make manifests` `operator-sdk build` ==> `make manager`, `make docker-build` If any of the old subcommands above are invoked for a Go operator project, the output should be a deprecation error that highlights the equivalent replacement for it in the new Kubebuilder workflow. A note on `operator-sdk run --local`: `kubebuilder` has a similar command `make run` to run an operator locally which `operator-sdk` should . However there is enough complexity in converting all functionality from `run --local` to `make run` that doing so is out of scope as of this update. To align with the goals of this proposal, both `operator-sdk run --local` and `make run` will be supported. Since features like the scorecard, CSV generation and test-framework have no equivalent in the Kubebuilder workflow, those subcommands would be unchanged on the CLI. `operator-sdk generate csv` `operator-sdk scorecard` `operator-sdk test` Where necessary the above commands should be adjusted to reflect the changes to their expected input and output manifest paths that is consistent with the new project layout. The existing e2e tests and CI scripts for testing Go operators would need to be updated to use the new layout so that CI passes for the new CLI workflow in the master branch. The user documentation for Go operators such as the user-guide, CLI reference, project layout, etc will need to be updated according to the new CLI and layout. These doc updates must include a detailed explanation of Dockerfile usage in Kubebuilder projects and how users can modify their vanilla Dockerfile to use a parent UBI image. The integration work for the Go Operator CLI workflow can be done in the master branch to avoid issues with merge conflicts from rebasing a separate branch at a later time. The new CLI can be worked on behind a hidden subcommand, `operator-sdk alpha`, until it is ready to replace the existing workflow. This would help avoid exposing it too early while still providing the ability to test it on the master branch. This proposal involves major breaking changes in all aspects of the project that will discourage users from making the upgrade to the release involving these changes. Besides having enough documentation to guide users to make the switch over to the new release, there should be some migration tooling to assist users in switching over their existing projects. TODO: These efforts will be addressed in a separate enhancement proposal. Once the SDK switches to using Kubebuilder for Go operators, the CLI UX for Go vs Ansible/Helm operators will be fragmented. While they dont target the same users it could be confusing to see the operator-sdk binary support different commands for initializing different project types. With the proposed plugin architecture it should be possible to update the workflow for Helm/Ansible operators to be the same as Kubebuilder. However that is not currently in scope for this proposal.