Skip to content
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.

Sign up for GitHub

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

Jump to bottom

📖 docs: Improve PROJECT file documentation #3287

Merged
merged 21 commits into from
Mar 19, 2023
Merged

📖 docs: Improve PROJECT file documentation #3287

Changes from 6 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
46f08d8
docs: improved PROJECT config
ashutosh887 Mar 12, 2023
f732a7d
docs: update PROJECT #overview
ashutosh887 Mar 13, 2023
2671eda
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 13, 2023
58b7d2e
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 13, 2023
a717d79
fix: change all links to alias
ashutosh887 Mar 13, 2023
d7b5b8a
fix: add relative alias
ashutosh887 Mar 13, 2023
e8e6b95
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 14, 2023
a6d0a86
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 14, 2023
d6cd6ab
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 14, 2023
50d866c
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 14, 2023
57cb911
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 14, 2023
1dd6424
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 16, 2023
a2f3d7f
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 16, 2023
d40250a
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 16, 2023
e6c08d0
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 19, 2023
317e70d
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 19, 2023
ca98c6e
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 19, 2023
8574126
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 19, 2023
875c378
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 19, 2023
4ba3df1
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 19, 2023
e9e23ce
Update docs/book/src/reference/project-config.md
ashutosh887 Mar 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
72 changes: 70 additions & 2 deletions docs/book/src/reference/project-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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.
ashutosh887 marked this conversation as resolved.
Show resolved Hide resolved

## Example

Following an example of an PROJECT file config file which is the result of an project generated with two APIs using the [Deploy Image Plugin][deploy-image-plugin].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At the bottom of the page we need to add the alias for this link it is here: https://book.kubebuilder.io/plugins/deploy-image-plugin-v1-alpha.html

So we need the relative path which will be something like
[deploy-image-plugin]: docs/plugins/deploy-image-plugin-v1-alpha.md

Please, check the other links in the docs to know how to do that

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added this

ashutosh887 marked this conversation as resolved.
Show resolved Hide resolved

```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?
Copy link
Contributor

@Kavinjsir Kavinjsir Mar 13, 2023 •
edited

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure done that


KubeBuilder allows and provides you opt-in to use plugins, indeed optional ones. Track the information required, for example:
- we can check if one plugin can or not be used/supported in the scaffold done
- what operations can or not be done
- what data can or not be used in the CLI operations
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 lib to allow others to create their plugins/tools and provide helpers and customizations on top of what is done for it, such as it is done by [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 vision](https://book.kubebuilder.io/plugins/creating-plugins.html#why-use-the-kubebuilder-style) to know more about.
ashutosh887 marked this conversation as resolved.
Show resolved Hide resolved

On top of that, another motivation for the PROJECT file would help us to create a feature to allow users easier upgrade their projects by providing allowing to automatically re-scaffold the project: Since we scaffold all data used to do the scaffold, we could automate the steps and have a command that would re-create the project in the latest version by re-doing all commands. [More info](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
Copy link
Member

Choose a reason for hiding this comment

The 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 ^

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure I've done the changes as you've recommended

Copy link
Member

Choose a reason for hiding this comment

The 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?


Expand Down Expand Up @@ -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