📖 add migration guide from v2 to v3

kubernetes-sigs · Oct 9, 2020 · 98a35d3 · 98a35d3
1 parent a2ca4a5
commit 98a35d3
Show file tree

Hide file tree

Showing 4 changed files with 260 additions and 3 deletions.
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -47,10 +47,13 @@
 
   - [Kubebuilder v1 vs v2](./migration/v1vsv2.md)
 
-      - [Migration Guide](./migration/guide.md)
-
+      - [Migration Guide](./migration/migration_guide_v1tov2.md)
+
+  - [Kubebuilder v2 vs v3](./migration/v2vsv3.md)
+
+      - [Migration Guide](./migration/migration_guide_v2tov3.md)
+
   - [Single Group to Multi-Group](./migration/multi-group.md)
-
 ---
 
 - [Reference](./reference/reference.md)

diff --git a/docs/book/src/migration/guide.md → ...k/src/migration/migration_guide_v1tov2.md b/docs/book/src/migration/guide.md → ...k/src/migration/migration_guide_v1tov2.md
diff --git a/docs/book/src/migration/migration_guide_v2tov3.md b/docs/book/src/migration/migration_guide_v2tov3.md
@@ -0,0 +1,239 @@
+# Migration from v2 to v3
+
+Make sure you understand the [differences between Kubebuilder v1 and v2](./v2vsv3.md)
+before continuing
+
+Please ensure you have followed the [installation guide](/quick-start.md#installation)
+to install the required components.
+
+## Steps to migrate to v3 project layout
+
+<aside class="note warning">
+<h1>Note</h1>
+
+The following steps will be based on the [QuickStart][QuickStart] steps. 
+
+</aside>
+
+- Add the `projectName`
+
+The project name is the name of the project directory in lowercase:
+
+```
+...
+projectName: example
+...
+```
+
+- Add the `layout`
+
+The default plugin layout which is equivalent to the previous versions is `go.kubebuilder.io/v2`: 
+
+```
+...
+layout: go.kubebuilder.io/v2
+...
+```
+
+- Add the `version`
+
+The `version` field represents the version of Project layouts. So, you ought to update this to `3-alpha`:
+
+```
+...
+version: 3-alpha`
+...
+```
+
+The final result of your project file would like:
+
+```sh
+domain: my.domain
+layout: go.kubebuilder.io/v2
+projectName: example
+repo: example
+resources:
+- group: webapp
+  kind: Guestbook
+  version: v1
+version: 3-alpha
+```
+
+### Verification
+
+Finally, we can run `make` and `make docker-build` to ensure things are working
+fine.
+
+## Migrating your projects to use v3+ plugins
+
+<aside class="note warning">
+
+<h1>Note</h1>
+
+v3+ plugins still in alpha version and are not scaffolded by default. You are able to use then and try it out and get all improvements made so far by initializing projects with the arg `--plugins=go.kubebuilder.io/v3-alpha`: 
+
+```sh 
+kubebuilder init --domain my.domain --plugins=go.kubebuilder.io/v3-alpha
+```
+
+</aside>
+
+<aside class="note warning">
+
+<h1>Note</h1>
+
+Currently, the plugin `v3-alpha` has NO breaking changes. However, until it get the stable state it might address some breaking changes to address some wished requirements related to k8s API deprecations of `CustomResourceDefinition` and `ValidatingWebhookConfiguration` `v1beta1` version as to upgrade the `cert-manager`. More info:
+
+- [cert-manager related configuration should be migrated to cert-manager.io/v1 #1666
+](https://github.com/kubernetes-sigs/kubebuilder/issues/1666)
+- [Set preserveUnknownFields to false in the CRD conversion webhook patch #933](https://github.com/kubernetes-sigs/kubebuilder/issues/933)
+- [Migrate existing KB project to v1 CRDs and Webhooks with minimal user effort #1065
+](https://github.com/kubernetes-sigs/kubebuilder/issues/1065)
+
+</aside>
+
+### Prerequisites
+
+Following the above steps to migrate your project to
+v3 project layout.
+
+### Update your PROJECT file
+
+Update the `layout` with the new plugin version ` go.kubebuilder.io/v3-alpha` and it would like to: 
+
+```sh
+ $ cat PROJECT 
+domain: my.domain
+layout: go.kubebuilder.io/v3-alpha
+projectName: example
+repo: example
+resources:
+- group: webapp
+  kind: Guestbook
+  version: v1
+version: 3-alpha
+
+```
+
+### V3+ plugins significant changes in the scalffold
+
+<aside class="note warning">
+
+<h1>Note</h1>
+
+The following changes are NOT breaking changes. In this way, these changes are optional but recommended in order to keep your project updated with the latest changes made so far. 
+
+</aside>
+
+#### Manager Rootless
+
+The projects built with v3+ plugin now define a specific `user ID` and `securityContext` policy for not allow to escalate root privileges from the manager container. 
+
+- Update your Dockerfile to define an ID for the user used:
+
+Replace:
+
+```
+USER nonroot:nonroot
+``` 
+
+With:
+
+```
+USER 65532:65532
+```
+
+- Update your `manager.yaml` manifests in the `config/manager/` directory by adding:
+
+```yaml
+...
+spec:
+      securityContext:
+        runAsUser: 65532
+...
+``` 
+
+```yaml
+...
+name: manager
+securityContext:
+  allowPrivilegeEscalation: false
+
+```
+
+The final result would like:
+
+```yaml 
+...
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: controller-manager
+  namespace: system
+  labels:
+    control-plane: controller-manager
+spec:
+  selector:
+    matchLabels:
+      control-plane: controller-manager
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        control-plane: controller-manager
+    spec:
+      securityContext:
+        runAsUser: 65532
+      containers:
+      - command:
+        - /manager
+        args:
+        - --enable-leader-election
+        image: controller:latest
+        name: manager
+        securityContext:
+          allowPrivilegeEscalation: false
+        resources:
+          limits:
+            cpu: 100m
+            memory: 30Mi
+          requests:
+            cpu: 100m
+            memory: 20Mi
+      terminationGracePeriodSeconds: 10
+```
+
+#### Roles (RBAC) bug fixes
+
+Now, the roles are scaffolding by adding a finalizer permissions. More info: https://github.com/kubernetes-sigs/kubebuilder/issues/1654 Feel free to add them to your projects. Following an example:
+
+```
+...
+- apiGroups:
+  - webapp.my.domain
+  resources:
+  - guestbooks/finalizers
+  verbs:
+  - update
+...
+``` 
+
+Also, the following `configmaps/status` permission is no longer scaffolded since they are invalid. Feel free to remove it from your `role.yaml` file in `config/rbac/` directory:
+
+```yaml
+...
+  resources:
+  - configmaps/status
+  verbs:
+  - get
+  - update
+  - patch
+```
+
+### Verification
+
+Finally, we can run `make` and `make docker-build` to ensure things are working
+fine.
+
+[QuickStart]: /docs/book/src/quick-start.md
+[envtest]: https://book.kubebuilder.io/reference/testing/envtest.html
diff --git a/docs/book/src/migration/v2vsv3.md b/docs/book/src/migration/v2vsv3.md
@@ -0,0 +1,15 @@
+# Kubebuilder v2 vs v3
+
+This document cover all breaking changes when migrating from v2 to v3.
+
+The details of all changes (breaking or otherwise) can be found in [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder/releases) release notes.
+
+## Kubebuilder
+
+- V1 projects was deprecated and is no longer supported.
+- The deprecated args related to go modules such as `--dep` and `depArgs` were removed
+- The plugin design was introduced to the project. For more info see the [Extensible CLI and Scaffolding Plugins][plugins-phase1-design-doc] doc.    
+
+[plugins-phase1-design-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md
+
+