Add first version of the migration guide to Krane 1.0 #607

dirceu · 2019-10-28T23:25:45Z

What are you trying to accomplish with this PR?

Add a migration guide to help people migrate off of kubernetes-deploy and into krane.

This can still change before 1.0, but it might be easier to maintain this guide if we merge it and update as needed (e.g. we still need to send a PR to update flag names: #602 (comment)).

ghost

Just a few comments so far. Will look more closely again

1.0-Upgrade.md

ghost · 2019-11-11T21:08:10Z

1.0-Upgrade.md

+
+## New task: `krane global-deploy`
+
+`krane global-deploy` (accessible through the Ruby API as `Krane::GlobalDeployTask`) can deploy global (non-namespaced) resources such as `PersistentVolume`, `Namespace`, and `CustomResourceDefinition`. Its interface is very similar to `krane deploy`. Example usage:


Should mention that krane deploy does not support global resources? Maybe add the same comment in the krane deploy as well?

1.0-Upgrade.md

dturn

Thanks for taking this on!

1.0-Upgrade.md

dturn · 2019-11-11T22:36:51Z

1.0-Upgrade.md

+-v, --version | [none] | Replaced with `krane version`
+$ENVIRONMENT | [none] | Dropped in favour of `-f`
+$REVISION | --current-sha | The environment variable REVISION was dropped in favour of an explicit flag
+[none] | --render-erb | **Important:** the new CLI doesn't render ERB by default


We should make sure we're committed to opt-in vs totally removing it.

1.0-Upgrade.md

JennaBlack · 2019-11-12T13:46:25Z

Is there a difference between version 1.0 and version 1.0.0 (1 decimal vs 2) it seems to be used interchangeably throughout this doc but not really consistent

dirceu · 2019-11-12T13:49:42Z

There shouldn't be a difference, but in any case we should make it consistent. Good shout!

1.0-Upgrade.md

dturn · 2019-11-12T18:21:02Z

1.0-Upgrade.md

+
+## Public API changes
+
+The only breaking change in the public API is the renaming of the `KubernetesDeploy` namespace to `Krane`. Besides that, the API of the major public classes (`DeployTask`, `RenderTask`, `RunnerTask`, and `RestartTask`) didn't change at all between 0.30.0 and 1.0.0. If you're curious about this API, check the comment-based docs on these classes or the [rendered documentation at RubyGems.org](https://www.rubydoc.info/gems/kubernetes-deploy/1.0.0/KubernetesDeploy/DeployTask).


I don't think this is true, args and defaults changed. We did also change functionality by removing the ability to deploy global resources)

Did args really change between kubernetes-deploy 0.30.0 and krane 1.0.0? I mean, their names will change but the default values are already different now aren't they?

I think the goal of the guide it help someone move from KubernetesDeploy::XTask - > Krane::XTask as well as exe/kubernetes-x -> exe/krane x . An example of a default value change would be erb rendering.

That's an example of a flag default value change (covered in those flag mapping tables - although I guess we can be more explicit by having columns for old default value and new default value); the default value in the code is still false:

https://github.com/Shopify/kubernetes-deploy/blob/6c6f930cecf3fda21b6fb57cca4f7ab39455d0c9/lib/krane/deprecated_deploy_task.rb#L128-L130

My point is that people moving from KubernetesDeploy::DeployTask to Krane::DeployTask will not actually have to change much if they are on a recent version. For instance, global deploys were disabled by default in 0.30.0.

So it's true right now because we've intentionally forced ourselves into backwards compatibility. But, once we cut 1.0.0-pre.1 it wont be true. Are you thinking the release of 1.0.0-pre.1 will change the wording? Or the first PR to actually make a change will be responsible for updating this?

Or the first PR to actually make a change will be responsible for updating this?

That's what I'm thinking. I plan to have this merged and then rebase #619 and have that PR document particular changes. It might be easier to keep track of all the changes we're doing that way. Does that make sense?

How about: The only breaking change in the public API, so far, is . I don't want someone to read this today and see the 1.0 and thing ok cool. Not realizing this is a living doc.

Makes sense. Updated.

1.0-Upgrade.md

lei-lo

Thanks for writing this up! Most of my comments are of the English-is-hard type 😅

1.0-Upgrade.md

dturn

Small change, but looking good for the current state of the world.

1.0-Upgrade.md

lei-lo

🏗 1️⃣

1.0-Upgrade.md

jessie-JNing · 2019-11-13T20:51:09Z

Just a nit. It's a great migration guide, thanks @dirceu

dirceu force-pushed the add-migration-guide branch from 4e607a2 to c956b39 Compare November 11, 2019 19:22

dirceu changed the title ~~Add migration guide to Krane 1.0~~ Add first version of the migration guide to Krane 1.0 Nov 11, 2019

dirceu marked this pull request as ready for review November 11, 2019 19:28

dirceu requested a review from a team November 11, 2019 19:28

ghost reviewed Nov 11, 2019

View reviewed changes

dirceu requested a review from a team November 11, 2019 21:49

dturn reviewed Nov 11, 2019

View reviewed changes

dirceu force-pushed the add-migration-guide branch from 7bf84ae to 29fa030 Compare November 12, 2019 13:37

dturn reviewed Nov 12, 2019

View reviewed changes

dirceu added 6 commits November 13, 2019 08:47

Add migration guide to Krane 1.0

45f3d3f

Address PR feedback

fa2cd43

Address more PR feedback

f9861f1

Normalize version number

5eeb44e

PR feedback

896271e

Update latest kubernetes-deploy version

f842109

dirceu force-pushed the add-migration-guide branch from 5180093 to f842109 Compare November 13, 2019 13:47

lei-lo reviewed Nov 13, 2019

View reviewed changes

dirceu added 3 commits November 13, 2019 12:26

Wording

d066339

More PR feedback

5886047

Wording

252568f

dturn approved these changes Nov 13, 2019

View reviewed changes

1.0-Upgrade.md Show resolved Hide resolved

Fix global deploy example

112e43a

dirceu requested a review from lei-lo November 13, 2019 20:14

lei-lo approved these changes Nov 13, 2019

View reviewed changes

jessie-JNing reviewed Nov 13, 2019

View reviewed changes

1.0-Upgrade.md Outdated Show resolved Hide resolved

jessie-JNing approved these changes Nov 13, 2019

View reviewed changes

Remove confusing snippet

7794c07

dirceu merged commit a72b4fd into master Nov 14, 2019

dirceu deleted the add-migration-guide branch November 14, 2019 13:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add first version of the migration guide to Krane 1.0 #607

Add first version of the migration guide to Krane 1.0 #607

dirceu commented Oct 28, 2019 •

edited

Loading

ghost left a comment

ghost Nov 11, 2019

dturn left a comment

dturn Nov 11, 2019

JennaBlack commented Nov 12, 2019

dirceu commented Nov 12, 2019

dturn Nov 12, 2019

dirceu Nov 12, 2019

dturn Nov 12, 2019

dirceu Nov 13, 2019 •

edited

Loading

dturn Nov 13, 2019

dirceu Nov 13, 2019

dturn Nov 13, 2019

dirceu Nov 13, 2019

lei-lo left a comment

dturn left a comment

lei-lo left a comment

jessie-JNing commented Nov 13, 2019


		## New task: `krane global-deploy`

		`krane global-deploy` (accessible through the Ruby API as `Krane::GlobalDeployTask`) can deploy global (non-namespaced) resources such as `PersistentVolume`, `Namespace`, and `CustomResourceDefinition`. Its interface is very similar to `krane deploy`. Example usage:


		## Public API changes

		The only breaking change in the public API is the renaming of the `KubernetesDeploy` namespace to `Krane`. Besides that, the API of the major public classes (`DeployTask`, `RenderTask`, `RunnerTask`, and `RestartTask`) didn't change at all between 0.30.0 and 1.0.0. If you're curious about this API, check the comment-based docs on these classes or the [rendered documentation at RubyGems.org](https://www.rubydoc.info/gems/kubernetes-deploy/1.0.0/KubernetesDeploy/DeployTask).

Add first version of the migration guide to Krane 1.0 #607

Add first version of the migration guide to Krane 1.0 #607

Conversation

dirceu commented Oct 28, 2019 • edited Loading

ghost left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dturn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JennaBlack commented Nov 12, 2019

dirceu commented Nov 12, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dirceu Nov 13, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lei-lo left a comment

Choose a reason for hiding this comment

dturn left a comment

Choose a reason for hiding this comment

lei-lo left a comment

Choose a reason for hiding this comment

jessie-JNing commented Nov 13, 2019

dirceu commented Oct 28, 2019 •

edited

Loading

dirceu Nov 13, 2019 •

edited

Loading