📖 docs: Improve PROJECT file documentation #3287
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 (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? | ||
|
|
||
| Following some examples of motivations to track the input used: | ||
| - check if a plugin can or cannot be scaffolded on top of an existing plugin (i.e.) plugin compatibility while chaining multiple of them together. | ||
| - what operations can or cannot be done such as verify if the layout allow API(s) for different groups to be scaffolded for the current configuration or not. | ||
| - verify what data can or not be used in the CLI operations such as to ensure that WebHooks can only be created for pre-existent API(s) | ||
|
|
||
| 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][operator-sdk]. 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, for example, the [Operator Framework solutions/OLM][olm]. You can check the [plugin's documentation][plugins-doc] to know more about creating custom plugins. | ||
|
|
||
| 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. For example, it can be used to automate the process of re-scaffolding while migrating between plugin versions. ([More info][doc-design-helper]). | ||
|
|
||
| ## Versioning | ||
|
There was a problem hiding this comment. 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. Sure I've done the changes as you've recommended There was a problem hiding this comment. 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,9 @@ 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 | ||
| [deploy-image-plugin]: ../plugins/deploy-image-plugin-v1-alpha.md | ||
| [olm]: https://olm.operatorframework.io/ | ||
| [plugins-doc]: ../plugins/creating-plugins.html#why-use-the-kubebuilder-style | ||
| [doc-design-helper]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/helper_to_upgrade_projects_by_rescaffolding.md | ||
| [operator-sdk]: https://sdk.operatorframework.io/ | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
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