-
Notifications
You must be signed in to change notification settings - Fork 1.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
📖 docs: Improve PROJECT file documentation #3287
Changes from 14 commits
46f08d8
f732a7d
2671eda
58b7d2e
a717d79
d7b5b8a
e8e6b95
a6d0a86
d6cd6ab
50d866c
57cb911
1dd6424
a2f3d7f
d40250a
e6c08d0
317e70d
ca98c6e
8574126
875c378
4ba3df1
e9e23ce
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,7 +2,74 @@ | |
|
||
## Overview | ||
|
||
The Project Config represents the configuration of a Kubebuilder project. All projects that are scaffolded with the CLI will generate the `PROJECT` file in the projects' root directory. | ||
The Project Config represents the configuration of a KubeBuilder project. All projects that are scaffolded with the CLI (KB version 3.0 and higher) will generate the `PROJECT` file in the projects' root directory. Therefore, it will store all plugins and input data used to generate the project and APIs to better enable plugins to make useful decisions when scaffolding. | ||
|
||
## Example | ||
|
||
Following is an example of a PROJECT config file which is the result of a project generated with two APIs using the [Deploy Image Plugin][deploy-image-plugin]. | ||
|
||
```yaml | ||
# Code generated by tool. DO NOT EDIT. | ||
# This file is used to track the info used to scaffold your project | ||
# and allow the plugins properly work. | ||
# More info: https://book.kubebuilder.io/reference/project-config.html | ||
domain: testproject.org | ||
layout: | ||
- go.kubebuilder.io/v4 | ||
plugins: | ||
deploy-image.go.kubebuilder.io/v1-alpha: | ||
resources: | ||
- domain: testproject.org | ||
group: example.com | ||
kind: Memcached | ||
options: | ||
containerCommand: memcached,-m=64,-o,modern,-v | ||
containerPort: "11211" | ||
image: memcached:1.4.36-alpine | ||
runAsUser: "1001" | ||
version: v1alpha1 | ||
- domain: testproject.org | ||
group: example.com | ||
kind: Busybox | ||
options: | ||
image: busybox:1.28 | ||
version: v1alpha1 | ||
projectName: project-v4-with-deploy-image | ||
repo: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image | ||
resources: | ||
- api: | ||
crdVersion: v1 | ||
namespaced: true | ||
controller: true | ||
domain: testproject.org | ||
group: example.com | ||
kind: Memcached | ||
path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1 | ||
version: v1alpha1 | ||
webhooks: | ||
validation: true | ||
webhookVersion: v1 | ||
- api: | ||
crdVersion: v1 | ||
namespaced: true | ||
controller: true | ||
domain: testproject.org | ||
group: example.com | ||
kind: Busybox | ||
path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1 | ||
version: v1alpha1 | ||
version: "3" | ||
``` | ||
## Why do we need to store the plugins and data used? | ||
|
||
Kubebuilder allows users to scaffold the project with external plugins and the PROJECT file can track the information required for the same, for example: | ||
ashutosh887 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- we can check if a plugin can or cannot be scaffolded on top of an existing plugin (ie) plugin compatibility while chaining multiple of them together. | ||
ashutosh887 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- what operations can or cannot be done for ex. can multiple APIs be scaffolded for the current configuration or not. | ||
ashutosh887 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- what data can or not be used in the CLI operations for ex. does an API exist in the project before scaffolding webhooks for the same. | ||
ashutosh887 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Note that KubeBuilder is not only a CLI tool but can also be used as a library to allow users to create their plugins/tools, provide helpers and customizations on top of their existing projects - an example of which is [Operator-SDK](https://sdk.operatorframework.io/). SDK leverages KubeBuilder to create plugins to allow users to work with other languages and provide helpers for their users to integrate their projects with the [Operator Framework solutions/OLM](https://olm.operatorframework.io/). You can check the [plugin's documentation](https://book.kubebuilder.io/plugins/creating-plugins.html#why-use-the-kubebuilder-style) to know more about creating custom plugins. | ||
ashutosh887 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Additionally, another motivation for the PROJECT file is to help us to create a feature that allows users to easily upgrade their projects by providing helpers that automatically re-scaffold the project. By having all the required metadata regarding the APIs, their configurations and versions in the PROJECT file, we could automate the process of re-scaffolding while migrating between plugin versions. More info on this, can be found [here] (https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/helper_to_upgrade_projects_by_rescaffolding.md) | ||
ashutosh887 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Versioning | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could we ensure that we have here the info shared in the following email of this thread? https://groups.google.com/g/kubebuilder/c/5c4_Xc3Fjx0/m/TERhvqaPBQAJ Also, could we use alias for the docs so that is easier for we keep it maintained? The links should be at the bottom of the doc I added some suggestions above ^ There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Sure I've done the changes as you've recommended There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hi @ashutosh887 it still not done, see the following suggestions:
Could you please ensure that all links are with alias and the alias are at the bottom? |
||
|
||
|
@@ -68,4 +135,5 @@ Now let's check its layout fields definition: | |
|
||
[project]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/testdata/project-v3/PROJECT | ||
[versioning]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/VERSIONING.md#Versioning | ||
[core-types]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/options.go | ||
[core-types]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/options.go | ||
[deploy-image-plugin]: ../plugins/deploy-image-plugin-v1-alpha.md | ||
ashutosh887 marked this conversation as resolved.
Show resolved
Hide resolved
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Seems like we need to close the code block above by
```
?Because the sample layout looks incorrect:
https://deploy-preview-3287--kubebuilder.netlify.app/reference/project-config.html?highlight=project#project-config
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure done that