Skip to content

Commit b7bc77b

Browse files
doc: add migration guide for helm new layout - Not visible in website (#3342)
**Description of the change:** - Add doc with the steps required that need is followed by the users migrate their project for the new layout. IMPORTANT: It is not visible on the website. The follow-up PR #3326 will make it visible. **Motivation for the change:** SDK is in a process to be integrated with KB which means that its project layouts will be aligned. More info : [Integrating Kubebuilder and Operator SDK](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/integrating-kubebuilder-and-osdk.md). As part of this process, we are creating the Helm plugin. See PR #3295. Also, we are updating the steps in the doc in the PR #3326 and here we are adding a new doc which will help users to migrate their projects.
1 parent c459922 commit b7bc77b

File tree

1 file changed

+59
-0
lines changed

1 file changed

+59
-0
lines changed
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
2+
This guide walks through an example of migrating a simple nginx-operator which was built by following the [legacy quick-start][quickstart] to the new layout.
3+
4+
## Overview
5+
6+
The motivations for the new layout are related to bringing more flexibility to users and
7+
part of the process to [Integrating Kubebuilder and Operator SDK][integration-doc].
8+
9+
### What was changed
10+
11+
The `deploy` directory was replaced with the `config` directory including a new layout of Kubernetes manifests files
12+
- CRD's manifests in `deploy/crds/` are now in `config/crd/bases`
13+
- CR's manifests in `deploy/crds/` are now in `config/samples`
14+
- Controller manifest `deploy/operator.yaml` was replaced for `config/manager/manager.yaml`
15+
- RBCA's manifests in `deploy` are in `config/rbac/`
16+
17+
The `build/Dockerfile` directory was replaced by the `Dockerfile` in the root directory
18+
19+
### What is new
20+
21+
- Now users are able to use [kustomize][kustomize] in the configurations files
22+
- PROJECT file in the root directory has all information about the project
23+
- Users are able to customize commands for your own projects via the Makefile which is added on the root directory
24+
25+
## How to migrate
26+
27+
The easy migration path is to create a new project from the scratch and let the tool scaffold the files properly and then,
28+
just replace with your customizations and implementations. Following an example.
29+
30+
### Creating a new project
31+
32+
Let's create the same project but with the Helm plugin:
33+
34+
```sh
35+
$ mkdir nginx-operator
36+
$ cd nginx-operator
37+
$ operator-sdk init --plugins=helm.operator-sdk.io/v1 --domain=com --group=example --version=v1alpha1 --kind=Nginx
38+
```
39+
40+
**Note** Ensure that you use the same values for the flags to recreate the same Helm Chart and API's. If you have
41+
more than one chart or API's you can add them via `operator-sdk create api` command. For further information check the [quick-start][quickstart-new].
42+
43+
### Replacing the content
44+
45+
- Update the CR manifests in `config/samples` with the values of the CR's in your old project which are in `deploy/crds/`
46+
- Check if you have customizations options in the `watch.yaml` file of your previous project and then, update the new `watch.yaml` file with the same ones
47+
- Ensure that all roles configured in the `/deploy/roles.yaml` will be applied in the new project in the file `config/rbac/role.yaml`
48+
- If you have customizations in your `helm-charts` then, apply them in the new `helm-charts`. Note that this directory was not changed at all.
49+
50+
### Checking the changes
51+
52+
Now, follow the steps in the section [Build and run the operator][build-run-quick] to verify your project is running.
53+
54+
<!-- todo: update the following link to /docs/helm/legacy/quickstart when the PR #3326 get merged -->
55+
[quickstart]: /docs/helm/quickstart
56+
[quickstart-new]: /docs/helm/quickstart
57+
[integration-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/integrating-kubebuilder-and-osdk.md
58+
[build-run-quick]: /docs/helm/quickstart#build-and-run-the-operator
59+
[kustomize]: https://github.com/kubernetes-sigs/kustomize

0 commit comments

Comments
 (0)