sigs.k8s.io/kubebuilder/v3@v3.14.0/README.md (about) 1 [](https://github.com/kubernetes-sigs/kubebuilder/actions/workflows/lint.yml) 2 [](https://github.com/kubernetes-sigs/kubebuilder/actions/workflows/unit-tests.yml) 3 [](https://goreportcard.com/report/sigs.k8s.io/kubebuilder) 4 [](https://coveralls.io/github/kubernetes-sigs/kubebuilder?branch=master) 5 [](https://github.com/kubernetes-sigs/kubebuilder/lreleases) 6 7 ## Kubebuilder 8 9 Kubebuilder is a framework for building Kubernetes APIs using [custom resource definitions (CRDs)](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions). 10 11 Similar to web development frameworks such as *Ruby on Rails* and *SpringBoot*, 12 Kubebuilder increases velocity and reduces the complexity managed by 13 developers for rapidly building and publishing Kubernetes APIs in Go. 14 It builds on top of the canonical techniques used to build the core Kubernetes APIs to provide simple abstractions that reduce boilerplate and toil. 15 16 Kubebuilder does **not** exist as an example to *copy-paste*, but instead provides powerful libraries and tools 17 to simplify building and publishing Kubernetes APIs from scratch. It 18 provides a plugin architecture allowing users to take advantage of optional helpers 19 and features. To learn more about this see the [Plugin section][plugin-section]. 20 21 Kubebuilder is developed on top of the [controller-runtime][controller-runtime] and [controller-tools][controller-tools] libraries. 22 23 ### Kubebuilder is also a library 24 25 Kubebuilder is extensible and can be used as a library in other projects. 26 [Operator-SDK][operator-sdk] is a good example of a project that uses Kubebuilder as a library. 27 [Operator-SDK][operator-sdk] uses the plugin feature to include non-Go operators _e.g. operator-sdk's Ansible and Helm-based language Operators_. 28 29 To learn more see [how to create your own plugins][your-own-plugins]. 30 31 ### Installation 32 33 It is strongly recommended that you use a released version. Release binaries are available on the [releases](https://github.com/kubernetes-sigs/kubebuilder/releases) page. 34 Follow the [instructions](https://book.kubebuilder.io/quick-start.html#installation) to install Kubebuilder. 35 36 ## Getting Started 37 38 See the [Getting Started](https://book.kubebuilder.io/quick-start.html) documentation. 39 40  41 42 Also, ensure that you check out the [Deploy Image](https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html) 43 Plugin. This plugin allows users to scaffold API/Controllers to deploy and manage an 44 Operand (image) on the cluster following the guidelines and best practices. It abstracts the 45 complexities of achieving this goal while allowing users to customize the generated code. 46 47 ## Documentation 48 49 Check out the Kubebuilder [book](https://book.kubebuilder.io). 50 51 ## Resources 52 53 - Kubebuilder Book: [book.kubebuilder.io](https://book.kubebuilder.io) 54 - GitHub Repo: [kubernetes-sigs/kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) 55 - Slack channel: [#kubebuilder](https://slack.k8s.io/#kubebuilder) 56 - Google Group: [kubebuilder@googlegroups.com](https://groups.google.com/forum/#!forum/kubebuilder) 57 - Design Documents: [designs](designs/) 58 - Plugin: [plugins][plugin-section] 59 60 ## Motivation 61 62 Building Kubernetes tools and APIs involves making a lot of decisions and writing a lot of boilerplate. 63 64 In order to facilitate easily building Kubernetes APIs and tools using the canonical approach, this framework 65 provides a collection of Kubernetes development tools to minimize toil. 66 67 Kubebuilder attempts to facilitate the following developer workflow for building APIs 68 69 1. Create a new project directory 70 2. Create one or more resource APIs as CRDs and then add fields to the resources 71 3. Implement reconcile loops in controllers and watch additional resources 72 4. Test by running against a cluster (self-installs CRDs and starts controllers automatically) 73 5. Update bootstrapped integration tests to test new fields and business logic 74 6. Build and publish a container from the provided Dockerfile 75 76 ## Scope 77 78 Building APIs using CRDs, Controllers and Admission Webhooks. 79 80 ## Philosophy 81 82 See [DESIGN.md](DESIGN.md) for the guiding principles of the various Kubebuilder projects. 83 84 TL;DR: 85 86 Provide clean library abstractions with clear and well exampled godocs. 87 88 - Prefer using go *interfaces* and *libraries* over relying on *code generation* 89 - Prefer using *code generation* over *1 time init* of stubs 90 - Prefer *1 time init* of stubs over forked and modified boilerplate 91 - Never fork and modify boilerplate 92 93 ## Techniques 94 95 - Provide higher level libraries on top of low level client libraries 96 - Protect developers from breaking changes in low level libraries 97 - Start minimal and provide progressive discovery of functionality 98 - Provide sane defaults and allow users to override when they exist 99 - Provide code generators to maintain common boilerplate that can't be addressed by interfaces 100 - Driven off of `//+` comments 101 - Provide bootstrapping commands to initialize new packages 102 103 ## Versioning and Releasing 104 105 See [VERSIONING.md](VERSIONING.md). 106 107 ## Troubleshooting 108 109 - ### Bugs and Feature Requests: 110 If you have what looks like a bug, or you would like to make a feature request, please use the [Github issue tracking system.](https://github.com/kubernetes-sigs/kubebuilder/issues) 111 Before you file an issue, please search existing issues to see if your issue is already covered. 112 113 - ### Slack 114 For realtime discussion, you can join the [#kubebuilder](https://slack.k8s.io/#kubebuilder) slack channel. Slack requires registration, but the Kubernetes team is open invitation to anyone to register here. Feel free to come and ask any questions. 115 116 ## Contributing 117 118 Contributions are greatly appreciated. The maintainers actively manage the issues list, and try to highlight issues suitable for newcomers. 119 The project follows the typical GitHub pull request model. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. 120 Before starting any work, please either comment on an existing issue, or file a new one. 121 122 ## Supportability 123 124 Currently, Kubebuilder officially supports OSX and Linux platforms. 125 So, if you are using a Windows OS you may find issues. Contributions towards 126 supporting Windows are welcome. 127 128 ### Apple Silicon 129 130 Apple Silicon (`darwin/arm64`) support begins with the `go/v4` plugin. 131 132 ## Community Meetings 133 134 The following meetings happen biweekly: 135 136 - Kubebuilder Meeting 137 138 You are more than welcome to attend. For further info join to [kubebuilder@googlegroups.com](https://groups.google.com/g/kubebuilder). 139 Every month, our team meets on the first Thursday at 11:00 PT (Pacific Time) to discuss our progress and plan for the upcoming weeks. 140 141 [operator-sdk]: https://github.com/operator-framework/operator-sdk 142 [plugin-section]: https://book.kubebuilder.io/plugins/plugins.html 143 [controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime 144 [your-own-plugins]: https://book.kubebuilder.io/plugins/creating-plugins.html 145 [controller-tools]: https://github.com/kubernetes-sigs/controller-tools