diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 43d5cc0c93d..3c2268fdb39 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -109,6 +109,8 @@ - [Extending the CLI](./plugins/extending-cli.md) - [Creating your own plugins](./plugins/creating-plugins.md) - [Available Plugins](./plugins/available-plugins.md) + - [go/v3 plugin](./plugins/go-v3-plugin.md) + - [go/v2 plugin](./plugins/go-v2-plugin.md) - [Declarative V1](./plugins/declarative-v1.md) - [Plugins Versioning](./plugins/plugins-versioning.md) diff --git a/docs/book/src/plugins/available-plugins.md b/docs/book/src/plugins/available-plugins.md index 1f6a614c18a..5c3970b7104 100644 --- a/docs/book/src/plugins/available-plugins.md +++ b/docs/book/src/plugins/available-plugins.md @@ -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) \ No newline at end of file + - [Declarative V1](declarative-v1.md) + - [Kustomize V1](kustomize-v1.md) + + + +[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 diff --git a/docs/book/src/plugins/declarative-v1.md b/docs/book/src/plugins/declarative-v1.md index fab14a8dc68..34f224c635b 100644 --- a/docs/book/src/plugins/declarative-v1.md +++ b/docs/book/src/plugins/declarative-v1.md @@ -48,7 +48,7 @@ The following scaffolds will be created or updated by this plugin: * `channels/stable` * `Dockerfile` -## Further ressources +## Further resources * Read more about the [declarative pattern][kubebuilder-declarative-pattern] * Watch the KubeCon 2018 Video [Managing Addons with Operators][kubecon-video] diff --git a/docs/book/src/plugins/go-v2-plugin.md b/docs/book/src/plugins/go-v2-plugin.md new file mode 100644 index 00000000000..5bf9dd9a1b9 --- /dev/null +++ b/docs/book/src/plugins/go-v2-plugin.md @@ -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. + + + +You can check samples using this plugin by looking at the `project-v2-` directories under the [testdata][testdata] projects on the root directory of the Kubebuilder project. + + + +## 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. + + + +## 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 +``` + + +## 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 \ No newline at end of file diff --git a/docs/book/src/plugins/go-v3-plugin.md b/docs/book/src/plugins/go-v3-plugin.md new file mode 100644 index 00000000000..f9b7228fea8 --- /dev/null +++ b/docs/book/src/plugins/go-v3-plugin.md @@ -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. + + + +## 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. + + + +## 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 \ No newline at end of file diff --git a/docs/book/src/plugins/kustomize-v1.md b/docs/book/src/plugins/kustomize-v1.md new file mode 100644 index 00000000000..708662975d9 --- /dev/null +++ b/docs/book/src/plugins/kustomize-v1.md @@ -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. + + + + +## 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]`) + + + +## 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 \ No newline at end of file diff --git a/pkg/plugins/golang/v3/scaffolds/init.go b/pkg/plugins/golang/v3/scaffolds/init.go index 31970ed15c0..d30d56dc65c 100644 --- a/pkg/plugins/golang/v3/scaffolds/init.go +++ b/pkg/plugins/golang/v3/scaffolds/init.go @@ -112,5 +112,6 @@ func (s *initScaffolder) Scaffold() error { }, &templates.Dockerfile{}, &templates.DockerIgnore{}, + &templates.Readme{}, ) } diff --git a/pkg/plugins/golang/v3/scaffolds/internal/templates/readme.go b/pkg/plugins/golang/v3/scaffolds/internal/templates/readme.go new file mode 100644 index 00000000000..48c415bb518 --- /dev/null +++ b/pkg/plugins/golang/v3/scaffolds/internal/templates/readme.go @@ -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=/{{ .ProjectName }}:tag"), + codeFence("sh", "make deploy IMG=/{{ .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" + "```" +} diff --git a/testdata/project-v3-addon/README.md b/testdata/project-v3-addon/README.md new file mode 100644 index 00000000000..3f240ba80b4 --- /dev/null +++ b/testdata/project-v3-addon/README.md @@ -0,0 +1,94 @@ +# project-v3-addon +// 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: + +```sh +kubectl apply -f config/samples/ +``` + +2. Build and push your image to the location specified by `IMG`: + +```sh +make docker-build docker-push IMG=/project-v3-addon:tag +``` + +3. Deploy the controller to the cluster with the image specified by `IMG`: + +```sh +make deploy IMG=/project-v3-addon:tag +``` + +### Uninstall CRDs +To delete the CRDs from the cluster: + +```sh +make uninstall +``` + +### Undeploy controller +UnDeploy the controller to the cluster: + +```sh +make undeploy +``` + +## 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: + +```sh +make install +``` + +2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): + +```sh +make run +``` + +**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: + +```sh +make manifests +``` + +**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 + +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. + diff --git a/testdata/project-v3-config/README.md b/testdata/project-v3-config/README.md new file mode 100644 index 00000000000..253fcecbab2 --- /dev/null +++ b/testdata/project-v3-config/README.md @@ -0,0 +1,94 @@ +# project-v3-config +// 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: + +```sh +kubectl apply -f config/samples/ +``` + +2. Build and push your image to the location specified by `IMG`: + +```sh +make docker-build docker-push IMG=/project-v3-config:tag +``` + +3. Deploy the controller to the cluster with the image specified by `IMG`: + +```sh +make deploy IMG=/project-v3-config:tag +``` + +### Uninstall CRDs +To delete the CRDs from the cluster: + +```sh +make uninstall +``` + +### Undeploy controller +UnDeploy the controller to the cluster: + +```sh +make undeploy +``` + +## 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: + +```sh +make install +``` + +2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): + +```sh +make run +``` + +**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: + +```sh +make manifests +``` + +**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 + +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. + diff --git a/testdata/project-v3-multigroup/README.md b/testdata/project-v3-multigroup/README.md new file mode 100644 index 00000000000..8593cb58c9a --- /dev/null +++ b/testdata/project-v3-multigroup/README.md @@ -0,0 +1,94 @@ +# project-v3-multigroup +// 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: + +```sh +kubectl apply -f config/samples/ +``` + +2. Build and push your image to the location specified by `IMG`: + +```sh +make docker-build docker-push IMG=/project-v3-multigroup:tag +``` + +3. Deploy the controller to the cluster with the image specified by `IMG`: + +```sh +make deploy IMG=/project-v3-multigroup:tag +``` + +### Uninstall CRDs +To delete the CRDs from the cluster: + +```sh +make uninstall +``` + +### Undeploy controller +UnDeploy the controller to the cluster: + +```sh +make undeploy +``` + +## 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: + +```sh +make install +``` + +2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): + +```sh +make run +``` + +**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: + +```sh +make manifests +``` + +**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 + +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. + diff --git a/testdata/project-v3-v1beta1/README.md b/testdata/project-v3-v1beta1/README.md new file mode 100644 index 00000000000..160a76fb75c --- /dev/null +++ b/testdata/project-v3-v1beta1/README.md @@ -0,0 +1,94 @@ +# project-v3-v1beta1 +// 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: + +```sh +kubectl apply -f config/samples/ +``` + +2. Build and push your image to the location specified by `IMG`: + +```sh +make docker-build docker-push IMG=/project-v3-v1beta1:tag +``` + +3. Deploy the controller to the cluster with the image specified by `IMG`: + +```sh +make deploy IMG=/project-v3-v1beta1:tag +``` + +### Uninstall CRDs +To delete the CRDs from the cluster: + +```sh +make uninstall +``` + +### Undeploy controller +UnDeploy the controller to the cluster: + +```sh +make undeploy +``` + +## 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: + +```sh +make install +``` + +2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): + +```sh +make run +``` + +**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: + +```sh +make manifests +``` + +**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 + +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. + diff --git a/testdata/project-v3/README.md b/testdata/project-v3/README.md new file mode 100644 index 00000000000..478d112d4cf --- /dev/null +++ b/testdata/project-v3/README.md @@ -0,0 +1,94 @@ +# project-v3 +// 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: + +```sh +kubectl apply -f config/samples/ +``` + +2. Build and push your image to the location specified by `IMG`: + +```sh +make docker-build docker-push IMG=/project-v3:tag +``` + +3. Deploy the controller to the cluster with the image specified by `IMG`: + +```sh +make deploy IMG=/project-v3:tag +``` + +### Uninstall CRDs +To delete the CRDs from the cluster: + +```sh +make uninstall +``` + +### Undeploy controller +UnDeploy the controller to the cluster: + +```sh +make undeploy +``` + +## 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: + +```sh +make install +``` + +2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): + +```sh +make run +``` + +**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: + +```sh +make manifests +``` + +**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 + +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. +