doc: add migration guide #653

hasbro17 · 2018-10-22T18:34:09Z

[skip ci]

Description of the change:

Added a migration guide to migrate a Go operator project to use SDK v0.1.0 with the new controller-runtime changes.
Update the user-guide for adding 3rd party resources.
The v0.1.0-changes.md doc referenced in the migration guide will be added in a followup PR. But even without that the migration guide should be sufficient to understand the changes.

Motivation for the change:

Need a migration guide before making the v0.1.0 release.

/cc @shawn-hurley @joelanford @lilic @AlexNPavel @estroz

[skip ci]

estroz

Flow looks good. A few cosmetic changes are needed.

doc/migration/v0.1.0-migration-guide.md

estroz · 2018-10-22T18:49:31Z

doc/migration/v0.1.0-migration-guide.md

+
+### Scaffold api for custom types
+
+Create the api for your custom resource(CR) in the new project with `operator-sdk add api --api-version=<apiversion> --kind=<kind>`


Space before (CR)

doc/migration/v0.1.0-migration-guide.md

estroz · 2018-10-22T19:04:32Z

doc/user-guide.md

-You then need to tell the operators to use these functions to add the resources to its scheme. In operator-sdk you use [AddToSDKScheme][osdk_add_to_scheme] to add this.
-Example of you main.go:
-```go
+By default the operator's manager will register all custom resource types defined in your project under `pkg/apis` with its scheme.


{m -> M}anager

estroz · 2018-10-22T19:05:19Z

doc/user-guide.md

+To add a 3rd party resource to an operator, you must add it to the manager's scheme. By creating an `AddToScheme` method or reusing one you can easily add a resource to your scheme. An [example][deployments_register] shows that you define a function and then use the [runtime][runtime_package] package to create a `SchemeBuilder`.
+
+#### Register with the manager's scheme
+Call the `AddToScheme()` function for your 3rd party resource and pass it the manager's scheme via `mgr.GetScheme()`.


{m -> M}anager

estroz · 2018-10-22T19:07:54Z

doc/migration/v0.1.0-migration-guide.md

+
+However if there are any operator specific flags or settings defined in the old main file copy those over.
+
+If you have any 3rd party resource types registered with the sdk's scheme, then register those with the manager's scheme in the new project. See how to [register 3rd party resources][register-3rd-party-resources].


Upper-case 'sdk'

doc/migration/v0.1.0-migration-guide.md

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

[skip ci]

hasbro17 · 2018-10-22T21:21:44Z

Fixed some typos and formatting issues.

doc/migration/v0.1.0-migration-guide.md

AlexNPavel · 2018-10-22T21:48:58Z

doc/migration/v0.1.0-migration-guide.md

+
+[v0.1.0-changes-doc]: ./v0.1.0-changes.md
+[v0.0.7-memcached-operator]: https://github.com/operator-framework/operator-sdk-samples/tree/aa15bd278eec0959595e0a0a7282a26055d7f9d6/memcached-operator
+[v0.1.0-memcached-operator]: https://github.com/operator-framework/operator-sdk-samples/tree/master/memcached-operator


This should probably be locked to a specific commit so this doc stays consistent as we update the SDK over time

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

lilic

Initial feedback, but didn't get a chance to try it yet.

lilic · 2018-10-23T12:46:14Z

doc/migration/v0.1.0-migration-guide.md

@@ -0,0 +1,268 @@
+# Migration Guide from v0.0.x to v0.1.0
+
+This document describes how to migrate an operator project built using Operator SDK `v0.0.x` to the project structure required by `v0.1.0`. For an overview of the major changes in the `v0.1.0` project layout and APIs see the [v0.1.0 changes doc][v0.1.0-changes-doc].


The ./v0.1.0-changes.md doesn't seem to exist so let's add this when that is added.

doc/migration/v0.1.0-migration-guide.md

lilic · 2018-10-23T13:55:56Z

doc/migration/v0.1.0-migration-guide.md

+err = r.client.Get(context.TODO(), types.NamespacedName{Name: name, Namespace: namespace}, dep)
+```
+
+Lastly copy and intialize any other fields that you may have had in your `Handler` struct into the `Reconcile<Kind>` struct:


s/intialize/initialize

lilic · 2018-10-23T13:57:10Z

doc/migration/v0.1.0-migration-guide.md

+
+#### Multiple custom resources
+
+If your operator is watching more than 1 CR type then you can do one of the following depending on you application:


Suggested change

If your operator is watching more than 1 CR type then you can do one of the following depending on you application:

If your operator is watching more than 1 CR type then you can do one of the following depending on your application:

shawn-hurley

LGTM just some thoughts but 👍 overall!

doc/migration/v0.1.0-migration-guide.md

joelanford · 2018-10-24T20:01:05Z

doc/migration/v0.1.0-migration-guide.md

+memcached-operator old-memcached-operator
+
+# Copy over .git from old project
+$ cp -rf memcached-operator/.git old-memcached-operator/.git 


This copies new to old, right? Don't you want this:

cp -rf old-memcached-operator/.git memcached-operator/.git

Yes it should be the other way around, good catch.

doc/migration/v0.1.0-migration-guide.md

joelanford

LGTM

hasbro17 · 2018-10-25T17:13:54Z

Going to follow this up with the v0.1.0 vs v0.0.x differences doc. That should be a bit smaller since we've gone over most of it in the migration guide.

doc: add migration guide

37b4f34

[skip ci]

hasbro17 mentioned this pull request Oct 22, 2018

Use the controller-runtime to replace the existing Watch and Handle APIs #382

Closed

hasbro17 requested review from AlexNPavel, estroz, joelanford, lilic and shawn-hurley October 22, 2018 19:18

estroz suggested changes Oct 22, 2018

View reviewed changes

openshift-ci-robot requested a review from estroz October 22, 2018 20:10

openshift-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Oct 22, 2018

estroz and others added 6 commits October 22, 2018 13:48

Update doc/migration/v0.1.0-migration-guide.md

afa1b24

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

Update doc/migration/v0.1.0-migration-guide.md

d39af22

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

Update doc/migration/v0.1.0-migration-guide.md

5a048c9

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

Update doc/migration/v0.1.0-migration-guide.md

0dd9e29

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

Update doc/migration/v0.1.0-migration-guide.md

1b44bda

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

Update doc/migration/v0.1.0-migration-guide.md

32a9b34

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

hasbro17 force-pushed the add-migration-guide branch from 21622d7 to ce43fd5 Compare October 22, 2018 21:20

doc: fix capitalization

ec57205

[skip ci]

hasbro17 force-pushed the add-migration-guide branch from ce43fd5 to ec57205 Compare October 22, 2018 21:20

AlexNPavel suggested changes Oct 22, 2018

View reviewed changes

AlexNPavel and others added 2 commits October 22, 2018 15:08

Update doc/migration/v0.1.0-migration-guide.md

de12e84

Co-Authored-By: hasbro17 <hasbro17@gmail.com>

doc/migration: pin example memcached-operator link to commit

1d4c5a2

lilic suggested changes Oct 23, 2018

View reviewed changes

shawn-hurley approved these changes Oct 23, 2018

View reviewed changes

doc/migration/v0.1.0-migration-guide.md Show resolved Hide resolved

doc/migration/v0.1.0-migration-guide.md Show resolved Hide resolved

doc/migration/v0.1.0-migration-guide.md Show resolved Hide resolved

hasbro17 mentioned this pull request Oct 23, 2018

We can't add a new api using operator-sdk 0.0.6 - must run command in project root dir: stat ./build/Dockerfile: no such file or directory #655

Closed

hasbro17 changed the title ~~doc: add migration guide~~ [WIP] doc: add migration guide Oct 23, 2018

openshift-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 23, 2018

doc/migration: format client comparisons as a table

bcace8c

hasbro17 changed the title ~~[WIP] doc: add migration guide~~ doc: add migration guide Oct 23, 2018

openshift-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 23, 2018

estroz approved these changes Oct 23, 2018

View reviewed changes

AlexNPavel approved these changes Oct 23, 2018

View reviewed changes

lilic approved these changes Oct 24, 2018

View reviewed changes

joelanford requested changes Oct 24, 2018

View reviewed changes

hasbro17 force-pushed the add-migration-guide branch 2 times, most recently from 871239f to 7d48f65 Compare October 25, 2018 00:16

joelanford approved these changes Oct 25, 2018

View reviewed changes

hasbro17 force-pushed the add-migration-guide branch 2 times, most recently from 8995a11 to 2738d46 Compare October 25, 2018 00:24

doc/migration: added section on periodic reconcile

281b24d

hasbro17 force-pushed the add-migration-guide branch from 2738d46 to 281b24d Compare October 25, 2018 00:32

hasbro17 merged commit 6d870c9 into operator-framework:master Oct 25, 2018

hasbro17 deleted the add-migration-guide branch October 25, 2018 17:12


		### Scaffold api for custom types

		Create the api for your custom resource(CR) in the new project with `operator-sdk add api --api-version=<apiversion> --kind=<kind>`


		However if there are any operator specific flags or settings defined in the old main file copy those over.

		If you have any 3rd party resource types registered with the sdk's scheme, then register those with the manager's scheme in the new project. See how to [register 3rd party resources][register-3rd-party-resources].

		@@ -0,0 +1,268 @@
		# Migration Guide from v0.0.x to v0.1.0

		This document describes how to migrate an operator project built using Operator SDK `v0.0.x` to the project structure required by `v0.1.0`. For an overview of the major changes in the `v0.1.0` project layout and APIs see the [v0.1.0 changes doc][v0.1.0-changes-doc].


		#### Multiple custom resources

		If your operator is watching more than 1 CR type then you can do one of the following depending on you application:

doc: add migration guide #653

doc: add migration guide #653

Uh oh!

Conversation

hasbro17 commented Oct 22, 2018

Uh oh!

estroz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hasbro17 commented Oct 22, 2018

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lilic left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shawn-hurley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

joelanford left a comment

Choose a reason for hiding this comment

Uh oh!

hasbro17 commented Oct 25, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants