-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add readme to go/v3 scaffold templates
Signed-off-by: Bryce Palmer <bpalmer@redhat.com>
- Loading branch information
1 parent
92e29e8
commit a2a6005
Showing
13 changed files
with
825 additions
and
4 deletions.
There are no files selected for viewing
This file contains 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
This file contains 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 |
---|---|---|
@@ -1,5 +1,18 @@ | ||
# Available Plugins | ||
# Available plugins | ||
|
||
This section details how to use the currently available plugins in Kubebuilder. | ||
This section describes the plugins supported and shipped in with the Kubebuilder project. | ||
|
||
- [Declarative V1](declarative-v1.md) | ||
- [Declarative V1](declarative-v1.md) | ||
- [Kustomize V1](kustomize-v1.md) | ||
|
||
<aside class="note"> | ||
|
||
<h1>But you can create your own plugins, see:</h1> | ||
|
||
- [Creating your own plugins][create-plugins]. | ||
- [Plugins Phase 2][plugins-phase-2] - will allow users to use these external options as helpers to perform the scaffolds with the tool. | ||
|
||
</aside> | ||
|
||
[create-plugins]: creating-plugins.md | ||
[plugins-phase-2]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-2.md |
This file contains 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
This file contains 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 |
---|---|---|
@@ -0,0 +1,51 @@ | ||
# go/v2 plugin | ||
|
||
The `go/v2` plugin has the purpose to scaffold Golang projects to help users to build projects with [controllers][controller-runtime] and keep the backwards compatibility with the default scaffold made using Kubebuilder CLI `2.x.z` releases. | ||
|
||
<node> | ||
|
||
You can check samples using this plugin by looking at the `project-v2-<options>` directories under the [testdata][testdata] projects on the root directory of the Kubebuilder project. | ||
|
||
</node> | ||
|
||
## When should I use this plugin | ||
|
||
Only if you are looking to scaffold a project with the legacy layout. Otherwise, it is recommended you to use the default Golang version plugin. | ||
|
||
<aside class="note warning"> | ||
|
||
<h1> Note </h1> | ||
|
||
Be aware that this plugin version does not provide a scaffold compatible with the latest versions of the dependencies used in order to keep its backwards compatibility. | ||
|
||
</aside> | ||
|
||
## How to use it ? | ||
|
||
To initialize a Golang project using the legacy layout and with this plugin run, e.g.: | ||
|
||
```sh | ||
kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project --plugins=go/v2 | ||
``` | ||
<aside class="note"> | ||
|
||
<h1> Note </h1> | ||
|
||
By creating a project with this plugin, the PROJECT file scaffold will be using the previous schema (_project version 2_). So that Kubebuilder CLI knows what plugin version was used and will call its subcommands such as `create api` and `create webhooks`. Note that further Golang plugins versions use the new Project file schema, which tracks the information about what plugins and versions have been used so far. | ||
|
||
</aside> | ||
|
||
## Subcommands supported by the plugin | ||
|
||
- Init - `kubebuilder init [OPTIONS]` | ||
- Edit - `kubebuilder edit [OPTIONS]` | ||
- Create API - `kubebuilder create api [OPTIONS]` | ||
- Create Webhook - `kubebuilder create webhook [OPTIONS]` | ||
|
||
## Further resources | ||
|
||
- Check the code implementation of the [go/v2 plugin][v2-plugin]. | ||
|
||
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime | ||
[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata | ||
[v2-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/golang/v2 |
This file contains 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 |
---|---|---|
@@ -0,0 +1,57 @@ | ||
# go/v3 | ||
|
||
Kubebuilder tool will scaffold the go/v3 plugin by default. This plugin is a composition of the plugins ` kustomize.common.kubebuilder.io/v1` and `base.go.kubebuilder.io/v3`. By using you can scaffold the default project which is a helper to construct sets of [controllers][controller-runtime]. | ||
|
||
It basically scaffolds all the boilerplate code required to create and design controllers. Note that by following the [quickstart][quickstart] you will be using this plugin. | ||
|
||
<aside class="note"> | ||
|
||
<h1>Examples</h1> | ||
|
||
Samples are provided under the [testdata][testdata] directory of the Kubebuilder project. You can check samples using this plugin by looking at the `project-v3-<options>` projects under the [testdata][testdata] directory on the root directory of the Kubebuilder project. | ||
|
||
</aside> | ||
|
||
## When to use it | ||
|
||
- If you are looking to scaffold Golang projects to develop projects using [controllers][controller-runtime] | ||
|
||
## How to use it ? | ||
|
||
As `go/v3` is the default plugin there is no need to explicitly mention to Kubebuilder to use this plugin. | ||
|
||
To create a new project with the `go/v3` plugin the following command can be used: | ||
|
||
```sh | ||
kubebuilder init --domain tutorial.kubebuilder.io --repo tutorial.kubebuilder.io/project | ||
``` | ||
All the other subcommands supported by the go/v3 plugin can be executed similarly. | ||
|
||
<aside class="note"> | ||
|
||
<h1>Note</h1> | ||
|
||
Also, if you need you can explicitly inform the plugin via the option provided `--plugins=go/v3`. | ||
|
||
</aside> | ||
|
||
## Subcommands supported by the plugin | ||
|
||
- Init - `kubebuilder init [OPTIONS]` | ||
- Edit - `kubebuilder edit [OPTIONS]` | ||
- Create API - `kubebuilder create api [OPTIONS]` | ||
- Create Webhook - `kubebuilder create webhook [OPTIONS]` | ||
|
||
## Further resources | ||
|
||
- To check how plugins are composited by looking at this definition in the [main.go][plugins-main]. | ||
- Check the code implementation of the [base Golang plugin `base.go.kubebuilder.io/v3`][v3-plugin]. | ||
- Check the code implementation of the [Kustomize/v1 plugin][kustomize-plugin]. | ||
- Check [controller-runtime][controller-runtime] to know more about controllers. | ||
|
||
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime | ||
[quickstart]: ../quick-start.md | ||
[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata | ||
[plugins-main]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/cmd/main.go | ||
[v3-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/golang/v3 | ||
[kustomize-plugin]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize/v1 |
This file contains 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 |
---|---|---|
@@ -0,0 +1,98 @@ | ||
# Kustomize Plugin | ||
|
||
The kustomize plugin allows you to scaffold all kustomize manifests used to work with the language plugins such as `go/v2` and `go/v3`. | ||
By using the kustomize plugin, you can create your own language plugins and ensure that you will have the same configurations | ||
and features provided by it. | ||
|
||
Note that projects such as [Operator-sdk][sdk] consume the Kubebuilder project as a lib and provide options to work with other languages | ||
like Ansible and Helm. The kustomize plugin allows them to easily keep a maintained configuration and ensure that all languages have | ||
the same configuration. It is also helpful if you are looking to provide nice plugins which will perform changes on top of | ||
what is scaffolded by default. With this approach we do not need to keep manually updating this configuration in all possible language plugins | ||
which uses the same and we are also | ||
able to create "helper" plugins which can work with many projects and languages. | ||
|
||
<aside class="note"> | ||
<h1>Examples</h1> | ||
|
||
You can check the kustomize content by looking at the `config/` directory. Samples are provided under the [testdata][testdata] | ||
directory of the Kubebuilder project. | ||
|
||
</aside> | ||
|
||
|
||
## When to use it | ||
|
||
- If you are looking to scaffold the kustomize configuration manifests for your own language plugin | ||
|
||
## How to use it | ||
|
||
If you are looking to define that your language plugin should use kustomize use the [Bundle Plugin][bundle] | ||
to specify that your language plugin is a composition with your plugin responsable for scaffold | ||
all that is laguage specific and kustomize for its configuration, see: | ||
|
||
```go | ||
// Bundle plugin which built the golang projects scaffold by Kubebuilder go/v3 | ||
// The follow code is creating a new plugin with its name and version via composition | ||
// You can define that one plugin is composite by 1 or Many others plugins | ||
gov3Bundle, _ := plugin.NewBundle(golang.DefaultNameQualifier, plugin.Version{Number: 3}, | ||
kustomizecommonv1.Plugin{}, // scaffold the config/ directory and all kustomize files | ||
golangv3.Plugin{}, // Scaffold the Golang files and all that specific for the language e.g. go.mod, apis, controllers | ||
) | ||
``` | ||
|
||
Also, with Kubebuilder, you can use kustomize alone via: | ||
|
||
```sh | ||
kubebuilder init --plugins=kustomize/v1 | ||
$ ls -la | ||
total 24 | ||
drwxr-xr-x 6 camilamacedo86 staff 192 31 Mar 09:56 . | ||
drwxr-xr-x 11 camilamacedo86 staff 352 29 Mar 21:23 .. | ||
-rw------- 1 camilamacedo86 staff 129 26 Mar 12:01 .dockerignore | ||
-rw------- 1 camilamacedo86 staff 367 26 Mar 12:01 .gitignore | ||
-rw------- 1 camilamacedo86 staff 94 31 Mar 09:56 PROJECT | ||
drwx------ 6 camilamacedo86 staff 192 31 Mar 09:56 config | ||
``` | ||
|
||
Or combined with the base language plugins: | ||
|
||
```sh | ||
# Provides the same scaffold of go/v3 plugin which is a composition (kubebuilder init --plugins=go/v3) | ||
kubebuilder init --plugins=kustomize/v1,base.go.kubebuilder.io/v3 --domain example.org --repo example.org/guestbook-operator | ||
``` | ||
|
||
## Subcommands | ||
|
||
The kustomize plugin implements the following subcommands: | ||
|
||
* init (`$ kubebuilder init [OPTIONS]`) | ||
* create api (`$ kubebuilder create api [OPTIONS]`) | ||
* create webhook (`$ kubebuilder create api [OPTIONS]`) | ||
|
||
<aside class="note"> | ||
<h1>Create API and Webhook</h1> | ||
|
||
Its implementation for the subcommand create api will scaffold the kustomize manifests | ||
which are specific for each API, see [here][kustomize-create-api]. The same applies | ||
to its implementation for create webhook. | ||
|
||
</aside> | ||
|
||
## Affected files | ||
|
||
The following scaffolds will be created or updated by this plugin: | ||
|
||
* `config/*` | ||
|
||
## Further resources | ||
|
||
* Check the kustomize [plugin implementation](https://github.com/kubernetes-sigs/kubebuilder/tree/master/pkg/plugins/common/kustomize) | ||
* Check the [kustomize documentation][kustomize-docs] | ||
* Check the [kustomize repository][kustomize-github] | ||
|
||
[sdk]:https://github.com/operator-framework/operator-sdk | ||
[testdata]: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/ | ||
[bundle]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugin/bundle.go | ||
[kustomize-create-api]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/common/kustomize/v1/scaffolds/api.go#L72-L84 | ||
[kustomize-docs]: https://kustomize.io/ | ||
[kustomize-github]: https://github.com/kubernetes-sigs/kustomize |
This file contains 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
129 changes: 129 additions & 0 deletions
129
pkg/plugins/golang/v3/scaffolds/internal/templates/readme.go
This file contains 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 |
---|---|---|
@@ -0,0 +1,129 @@ | ||
/* | ||
Copyright 2022 The Kubernetes Authors. | ||
Licensed under the Apache License, Version 2.0 (the "License"); | ||
you may not use this file except in compliance with the License. | ||
You may obtain a copy of the License at | ||
http://www.apache.org/licenses/LICENSE-2.0 | ||
Unless required by applicable law or agreed to in writing, software | ||
distributed under the License is distributed on an "AS IS" BASIS, | ||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
See the License for the specific language governing permissions and | ||
limitations under the License. | ||
*/ | ||
|
||
package templates | ||
|
||
import ( | ||
"fmt" | ||
"strings" | ||
|
||
"sigs.k8s.io/kubebuilder/v3/pkg/machinery" | ||
) | ||
|
||
var _ machinery.Template = &Readme{} | ||
|
||
// Readme scaffolds a README.md file | ||
type Readme struct { | ||
machinery.TemplateMixin | ||
machinery.BoilerplateMixin | ||
machinery.ProjectNameMixin | ||
|
||
License string | ||
} | ||
|
||
// SetTemplateDefaults implements file.Template | ||
func (f *Readme) SetTemplateDefaults() error { | ||
if f.Path == "" { | ||
f.Path = "README.md" | ||
} | ||
|
||
f.License = strings.Replace( | ||
strings.Replace(string(f.Boilerplate), "/*", "", 1), | ||
"*/", "", 1) | ||
|
||
f.TemplateBody = fmt.Sprintf(readmeFileTemplate, | ||
codeFence("sh", "kubectl apply -f config/samples/"), | ||
codeFence("sh", "make docker-build docker-push IMG=<some-registry>/{{ .ProjectName }}:tag"), | ||
codeFence("sh", "make deploy IMG=<some-registry>/{{ .ProjectName }}:tag"), | ||
codeFence("sh", "make uninstall"), | ||
codeFence("sh", "make undeploy"), | ||
codeFence("sh", "make install"), | ||
codeFence("sh", "make run"), | ||
codeFence("sh", "make manifests")) | ||
|
||
return nil | ||
} | ||
|
||
//nolint:lll | ||
const readmeFileTemplate = `# {{ .ProjectName }} | ||
// TODO(user): Add simple overview of use/purpose | ||
## Description | ||
// TODO(user): An in-depth paragraph about your project and overview of use | ||
## Getting Started | ||
You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. | ||
**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster ` + "`kubectl cluster-info`" + ` shows). | ||
### Running on the cluster | ||
1. Install Instances of Custom Resources: | ||
%s | ||
2. Build and push your image to the location specified by ` + "`IMG`" + `: | ||
%s | ||
3. Deploy the controller to the cluster with the image specified by ` + "`IMG`" + `: | ||
%s | ||
### Uninstall CRDs | ||
To delete the CRDs from the cluster: | ||
%s | ||
### Undeploy controller | ||
UnDeploy the controller to the cluster: | ||
%s | ||
## Contributing | ||
// TODO(user): Add detailed information on how you would like others to contribute to this project | ||
### How it works | ||
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) | ||
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) | ||
which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster | ||
### Test It Out | ||
1. Install the CRDs into the cluster: | ||
%s | ||
2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): | ||
%s | ||
**NOTE:** You can also run this in one step by running: ` + "`make install run`" + ` | ||
### Modifying the API definitions | ||
If you are editing the API definitions, generate the manifests such as CRs or CRDs using: | ||
%s | ||
**NOTE:** Run ` + "`make --help`" + ` for more information on all potential ` + "`make`" + ` targets | ||
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) | ||
## License | ||
{{ .License }} | ||
` | ||
|
||
func codeFence(syntax string, code string) string { | ||
return "```" + syntax + "\n" + code + "\n" + "```" | ||
} |
Oops, something went wrong.