Skip to content

Commit 066210f

Browse files
📖 (docs): Add missing information to quick start and supplement links (#5053)
(docs): Add missing information to quick start and supplement links
1 parent b9e983d commit 066210f

File tree

1 file changed

+73
-9
lines changed

1 file changed

+73
-9
lines changed

‎docs/book/src/quick-start.md‎

Lines changed: 73 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This Quick Start guide will cover:
99

1010
## Prerequisites
1111

12-
- [go](https://go.dev/dl/) version v1.23.0+
12+
- [go](https://go.dev/dl/) version v1.24.5+
1313
- [docker](https://docs.docker.com/install/) version 17.03+.
1414
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) version v1.11.3+.
1515
- Access to a Kubernetes v1.11.3+ cluster.
@@ -144,10 +144,20 @@ type Guestbook struct {
144144
</p>
145145
</details>
146146

147+
148+
<aside class="note">
149+
<h1> `+kubebuilder` markers </h1>
150+
151+
`+kubebuilder` are [markers][markers] processed by [controller-gen][controller-gen]
152+
to generate CRDs and RBAC. Kubebuilder also provides [scaffolding markers][scaffolding-markers]
153+
to inject code into existing files and simplify common tasks. See `cmd/main.go` for examples.
154+
155+
</aside>
156+
147157
## Test It Out
148158

149159
You'll need a Kubernetes cluster to run against. You can use
150-
[KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or
160+
[KinD][kind] to get a local cluster for testing, or
151161
run against a remote cluster.
152162

153163
<aside class="note">
@@ -202,14 +212,15 @@ make deploy IMG=<some-registry>/<project-name>:tag
202212
This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment.
203213
Make sure you have the proper permission to the registry if the above commands don't work.
204214

205-
Consider incorporating Kind into your workflow for a faster, more efficient local development and CI experience.
206-
Note that, if you're using a Kind cluster, there's no need to push your image to a remote container registry.
207-
You can directly load your local image into your specified Kind cluster:
215+
Consider incorporating [Kind][kind] into your workflow for a faster, more efficient local development and CI experience.
216+
Note that, if you're using a [Kind][kind] cluster, there's no need to push your image to a remote container registry.
217+
You can directly load your local image into your specified [Kind][kind] cluster:
208218

209219
```bash
210220
kind load docker-image <your-image-name>:tag --name <your-kind-cluster-name>
211221
```
212222

223+
It is highly recommended to use [Kind][kind] for development purposes and CI.
213224
To know more, see: [Using Kind For Development Purposes and CI](./reference/kind.md)
214225

215226
<h1>RBAC errors</h1>
@@ -234,19 +245,72 @@ Undeploy the controller to the cluster:
234245
```bash
235246
make undeploy
236247
```
248+
## Using Plugins
249+
250+
Kubebuilder design is based on [Plugins][plugins] and you can use
251+
[available plugins][available-plugins] to add optional features to your project.
252+
253+
### Creating an API and Controller with code to manage an image
254+
255+
For example, you can scaffold an API and controller that
256+
manages container images by using the [deploy-image plugin][deploy-image-v1-alpha]:
257+
258+
```bash
259+
kubebuilder create api --group webapp --version v1alpha1 --kind Busybox --image=busybox:1.36.1 --plugins="deploy-image/v1-alpha"
260+
```
261+
262+
This command generates:
263+
264+
- The API definition in `api/v1alpha1/busybox_types.go`.
265+
- The controller logic in `internal/controllers/busybox_controller.go`.
266+
- A test scaffold in `internal/controllers/busybox_controller_test.go`, which uses [EnvTest][envtest] for integration-style testing.
267+
268+
<aside class="note">
269+
<h1> References and Examples </h1>
270+
271+
You can use the code of [DeployImage Plugin][deploy-image-v1-alpha] as a reference to create your project.
272+
They follow Kubernetes conventions and recommended good practices.
273+
274+
</aside>
275+
276+
### Keeping your project up to date with ecosystem changes
277+
278+
Kubebuilder provides the [AutoUpdate Plugin][autoupdate-v1-alpha]
279+
to help keep your project aligned with the latest ecosystem changes.
280+
When a new release is available, the plugin opens an **Issue** with a
281+
Pull Request compare link. You can then review the updates and, if helpful,
282+
use [GitHub AI models][ai-gh-models] to understand what changes are needed to keep your project current.
283+
284+
```bash
285+
kubebuilder edit --plugins="autoupdate/v1-alpha"
286+
```
287+
288+
This command scaffolds a GitHub workflow file at `.github/workflows/autoupdate.yml`.
237289

238290
## Next Step
239291

240-
- Now, take a look at the [Architecture Concept Diagram][architecture-concept-diagram] for a clearer overview.
241-
- Next, proceed with the [Getting Started Guide][getting-started], which should take no more than 30 minutes and will
242-
provide a solid foundation. Afterward, dive into the [CronJob Tutorial][cronjob-tutorial] to deepen your
292+
- Proceed with the [Getting Started Guide][getting-started], which should take no more than 30 minutes and will
293+
provide a solid foundation.
294+
- Afterward, dive into the [CronJob Tutorial][cronjob-tutorial] to deepen your
243295
understanding by developing a demo project.
296+
- Ensure that you understand the APIs and Groups concepts [Groups and Versions and Kinds, oh my!][gkv-doc]
297+
before designing your own API and project.
244298

245299
[pre-rbc-gke]: https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#iam-rolebinding-bootstrap
246300
[cronjob-tutorial]: https://book.kubebuilder.io/cronjob-tutorial/cronjob-tutorial.html
247301
[GOPATH-golang-docs]: https://go.dev/doc/code.html#GOPATH
248302
[go-modules-blogpost]: https://blog.go.dev/using-go-modules
249-
[envtest]: https://book.kubebuilder.io/reference/testing/envtest.html
250303
[architecture-concept-diagram]: architecture.md
251304
[kustomize]: https://github.com/kubernetes-sigs/kustomize
252305
[getting-started]: getting-started.md
306+
[plugins]: plugins/plugins.md
307+
[available-plugins]: plugins/available-plugins.md
308+
[envtest]: ./reference/envtest.md
309+
[autoupdate-v1-alpha]: plugins/available/autoupdate-v1-alpha.md
310+
[deploy-image-v1-alpha]: plugins/available/deploy-image-plugin-v1-alpha.md
311+
[gkv-doc]: cronjob-tutorial/gvks.md
312+
[kind]: https://sigs.k8s.io/kind
313+
[markers]: reference/markers.md
314+
[controller-gen]: https://sigs.k8s.io/controller-tools/cmd/controller-gen
315+
[scaffolding-markers]: reference/markers/scaffold.md
316+
[ai-gh-models]: https://docs.github.com/en/github-models/about-github-models

0 commit comments

Comments
 (0)