From 1d30faf1a25170bc637009d5a70a7c159028b5fe Mon Sep 17 00:00:00 2001 From: epolon Date: Wed, 26 Aug 2020 16:34:34 +0300 Subject: [PATCH 01/11] mid work --- text/0000-eks-dev-preview.md | 76 ++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 text/0000-eks-dev-preview.md diff --git a/text/0000-eks-dev-preview.md b/text/0000-eks-dev-preview.md new file mode 100644 index 000000000..148fcb6e4 --- /dev/null +++ b/text/0000-eks-dev-preview.md @@ -0,0 +1,76 @@ +--- +feature name: (fill me in with a unique identifier, my-awesome-feature) +start date: (fill me in with today's date, YYYY-MM-DD) +rfc pr: (leave this empty) +related issue: (tracking issue number) +--- + +# Summary + +When we introduce breaking changes to `experimental` libraries that require resource replacements, +or in general are considered highly intrusive, we should provide a clear migration path. + +This RFC proposes a protocol for introducing such changes. + +> **More than an actual RFC, this should be treated as somewhat of a thought experiment that will eventually evolve to an actual mechanism.** + +> For the sake of discussion, this RFC will specifically refer to the `aws-eks` module as an example. + +# Motivation + +The EKS module is currently in `experimental` state, as we push to `developer-preview`, we need to introduce networking changes that +require cluster replacement. We'd like for users to be able to use the current module without interruption, and choose to replace their cluster at their own pace. + +# Design Summary + +The main idea is to spin off to a new module that introduces all the breaking changes at once. The old module will be effectively locked, and won't receive any updates apart from **p0** bug fixes. + +Its essentially the same as rolling out a new major version, but since all +modules are versioned together, we do this by changing the module name, and not the version. + +Since the final module we mark as `stable` should be called `aws-eks`, we rename the current module to `aws-eks-experimental`, and move forward with the new one as `aws-eks`. + +This also means that we need to somehow detect current users of `aws-eks`. Otherwise, user's won't know they need to change their dependency. This can be done with a feature flag. + +# README + +When such a change is introduced to the module, we will add the following notice to its README. + +> This library has been deprecated in favor of the `aws-eks` module. This module will not receive updates apart from critical bug fixes. Note that transitioning to `aws-eks` might incur changes that require cluster replacement. + +The new module, which is now `aws-eks`, will include the following notice in its README. + +> If you are transitioning to this module from `aws-eks-experimental`, you might incur changes that require cluster replacements. + +# Implementation Plan + +1. Rename current module to `aws-eks-experimental`. +2. Create a staging branch `eks-dev-preview` which contains `aws-eks` as a copy of `aws-eks-experimental`. +3. Implement necessary changes onto the `eks-dev-preview` branch. +4. Merge `eks-dev-preview` to master. + +# Rationale and Alternatives + +- Instead of renaming the current module, we can rename the new module. So we will have `aws-eks-dev-preview`. This would prevent the need for the detection of old module usages in the new module code. The problem here is that eventually we would need to rename it, and the `aws-eks` module will be taken, so we would need to rename that as well, winding up in the same situation, except we now broke the old module again, after we promised not to. + +# Adoption Strategy + +When users upgrade their version of `aws-eks`, they will now receive the new intrusive version. This version will detect that the user had previously been using the old `aws-eks` (which is now `aws-eks-experimental`) module, and display the following error: + +```console +The aws-eks module has undergone a name change, to use the previously named aws-eks module, please change your imports and dependencies to use aws-eks-experimental. If you'd like to use the new aws-eks module, add the following key to your cdk.json file: "@aws-cdk/aws-eks:migratedFromExperimental: true". +``` + +The user will then choose to either change imports to point to the `aws-eks-experimental` module, and continue working without interruption. Or, add the necessary feature flag to `cdk.json` and continue with the new module which will most likely replace the cluster. + +# Unresolved questions + +- How will this work with monocdk? + +# Future Possibilities + +Hopefully, this little exercise will turn into a well defined mechanism. If we take the current approach and expand it to follow: + +*"Each intrusive change will spin off to a new module"* + +And come up with some sort of naming pattern for old modules, this might work as a general approach. From 733bbd5c36dc19bf10c5a2e8abb7f0386fa60f1f Mon Sep 17 00:00:00 2001 From: epolon Date: Wed, 26 Aug 2020 16:40:15 +0300 Subject: [PATCH 02/11] rename --- ...review.md => 0244-intrusive-changes-migration-path.md} | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) rename text/{0000-eks-dev-preview.md => 0244-intrusive-changes-migration-path.md} (95%) diff --git a/text/0000-eks-dev-preview.md b/text/0244-intrusive-changes-migration-path.md similarity index 95% rename from text/0000-eks-dev-preview.md rename to text/0244-intrusive-changes-migration-path.md index 148fcb6e4..5e7feb423 100644 --- a/text/0000-eks-dev-preview.md +++ b/text/0244-intrusive-changes-migration-path.md @@ -1,8 +1,8 @@ --- -feature name: (fill me in with a unique identifier, my-awesome-feature) -start date: (fill me in with today's date, YYYY-MM-DD) -rfc pr: (leave this empty) -related issue: (tracking issue number) +feature name: Migration Path For Intrusive Changes +start date: 2020-08-26 +rfc pr: +related issue: https://github.com/aws/aws-cdk-rfcs/issues/244 --- # Summary From 8adf372677a8a00ccf475cccfda060beb5ea4aa3 Mon Sep 17 00:00:00 2001 From: epolon Date: Wed, 26 Aug 2020 16:42:24 +0300 Subject: [PATCH 03/11] added pr --- text/0244-intrusive-changes-migration-path.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0244-intrusive-changes-migration-path.md b/text/0244-intrusive-changes-migration-path.md index 5e7feb423..31dae0d75 100644 --- a/text/0244-intrusive-changes-migration-path.md +++ b/text/0244-intrusive-changes-migration-path.md @@ -1,7 +1,7 @@ --- feature name: Migration Path For Intrusive Changes start date: 2020-08-26 -rfc pr: +rfc pr: https://github.com/aws/aws-cdk-rfcs/pull/245 related issue: https://github.com/aws/aws-cdk-rfcs/issues/244 --- From 4c95a23da2b76257b5a923822d5d3121a14870af Mon Sep 17 00:00:00 2001 From: epolon Date: Wed, 26 Aug 2020 19:45:18 +0300 Subject: [PATCH 04/11] rename --- text/0244-intrusive-changes-migration-path.md | 76 ------------------- 1 file changed, 76 deletions(-) delete mode 100644 text/0244-intrusive-changes-migration-path.md diff --git a/text/0244-intrusive-changes-migration-path.md b/text/0244-intrusive-changes-migration-path.md deleted file mode 100644 index 31dae0d75..000000000 --- a/text/0244-intrusive-changes-migration-path.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -feature name: Migration Path For Intrusive Changes -start date: 2020-08-26 -rfc pr: https://github.com/aws/aws-cdk-rfcs/pull/245 -related issue: https://github.com/aws/aws-cdk-rfcs/issues/244 ---- - -# Summary - -When we introduce breaking changes to `experimental` libraries that require resource replacements, -or in general are considered highly intrusive, we should provide a clear migration path. - -This RFC proposes a protocol for introducing such changes. - -> **More than an actual RFC, this should be treated as somewhat of a thought experiment that will eventually evolve to an actual mechanism.** - -> For the sake of discussion, this RFC will specifically refer to the `aws-eks` module as an example. - -# Motivation - -The EKS module is currently in `experimental` state, as we push to `developer-preview`, we need to introduce networking changes that -require cluster replacement. We'd like for users to be able to use the current module without interruption, and choose to replace their cluster at their own pace. - -# Design Summary - -The main idea is to spin off to a new module that introduces all the breaking changes at once. The old module will be effectively locked, and won't receive any updates apart from **p0** bug fixes. - -Its essentially the same as rolling out a new major version, but since all -modules are versioned together, we do this by changing the module name, and not the version. - -Since the final module we mark as `stable` should be called `aws-eks`, we rename the current module to `aws-eks-experimental`, and move forward with the new one as `aws-eks`. - -This also means that we need to somehow detect current users of `aws-eks`. Otherwise, user's won't know they need to change their dependency. This can be done with a feature flag. - -# README - -When such a change is introduced to the module, we will add the following notice to its README. - -> This library has been deprecated in favor of the `aws-eks` module. This module will not receive updates apart from critical bug fixes. Note that transitioning to `aws-eks` might incur changes that require cluster replacement. - -The new module, which is now `aws-eks`, will include the following notice in its README. - -> If you are transitioning to this module from `aws-eks-experimental`, you might incur changes that require cluster replacements. - -# Implementation Plan - -1. Rename current module to `aws-eks-experimental`. -2. Create a staging branch `eks-dev-preview` which contains `aws-eks` as a copy of `aws-eks-experimental`. -3. Implement necessary changes onto the `eks-dev-preview` branch. -4. Merge `eks-dev-preview` to master. - -# Rationale and Alternatives - -- Instead of renaming the current module, we can rename the new module. So we will have `aws-eks-dev-preview`. This would prevent the need for the detection of old module usages in the new module code. The problem here is that eventually we would need to rename it, and the `aws-eks` module will be taken, so we would need to rename that as well, winding up in the same situation, except we now broke the old module again, after we promised not to. - -# Adoption Strategy - -When users upgrade their version of `aws-eks`, they will now receive the new intrusive version. This version will detect that the user had previously been using the old `aws-eks` (which is now `aws-eks-experimental`) module, and display the following error: - -```console -The aws-eks module has undergone a name change, to use the previously named aws-eks module, please change your imports and dependencies to use aws-eks-experimental. If you'd like to use the new aws-eks module, add the following key to your cdk.json file: "@aws-cdk/aws-eks:migratedFromExperimental: true". -``` - -The user will then choose to either change imports to point to the `aws-eks-experimental` module, and continue working without interruption. Or, add the necessary feature flag to `cdk.json` and continue with the new module which will most likely replace the cluster. - -# Unresolved questions - -- How will this work with monocdk? - -# Future Possibilities - -Hopefully, this little exercise will turn into a well defined mechanism. If we take the current approach and expand it to follow: - -*"Each intrusive change will spin off to a new module"* - -And come up with some sort of naming pattern for old modules, this might work as a general approach. From 6bdd3aa4fa4066bc4b12c6786eadaf4394d2e9e1 Mon Sep 17 00:00:00 2001 From: epolon Date: Wed, 26 Aug 2020 19:46:59 +0300 Subject: [PATCH 05/11] rename --- ...44-eks-developer-preview-migration-path.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 text/0244-eks-developer-preview-migration-path.md diff --git a/text/0244-eks-developer-preview-migration-path.md b/text/0244-eks-developer-preview-migration-path.md new file mode 100644 index 000000000..7c8eb170d --- /dev/null +++ b/text/0244-eks-developer-preview-migration-path.md @@ -0,0 +1,91 @@ +--- +feature name: Migration Path For EKS Developer Preview +start date: 2020-08-26 +rfc pr: https://github.com/aws/aws-cdk-rfcs/pull/245 +related issue: https://github.com/aws/aws-cdk-rfcs/issues/244 +--- + +# Summary + +This RFC proposes a migration path for existing users following the upcoming transition of the `aws-eks` module from *Experimental* to *Developer Preview*. + +# Motivation + +As part of transitioning the `aws-eks` module to *Developer Preview*, we need to introduce a few breaking changes that require users to replace their existing clusters. + +This poses a major interruption that might need extra planning from the user's side. Because of this, even though the module is currently `experimental`, we want users to be able to replace clusters at their own pace. To that end, we need to come up with some migration strategy. + +# Design Summary + +The main idea is to spin off to a new module that introduces all the breaking changes at once. The old module will be effectively locked, and won't receive any updates apart from **p0** bug fixes. +Its essentially the same as rolling out a new major version, but since all +modules are versioned together, we do this by changing the module name, and not the version. + +Since the final module we mark as `stable` should be called `aws-eks`, we rename the current module to `aws-eks-experimental`, and move forward with the new one as `aws-eks`. + +This means that upon upgrade, existing users of `aws-eks` will now receive the developer preview version, which will naively replace their clusters. To avoid that, we need the code to detect this situation and provide clear instructions to the user. + +# README + +In the old module, which is now `aws-eks-experimental`, we will add the following notice to the README. + +> This module has been deprecated in favor of the `aws-eks` module. This module will not receive updates apart from critical bug fixes. Note that transitioning to `aws-eks` might incur changes that require cluster replacement. + +In the new module, which is now `aws-eks`, we will add the following notice to the README. + +> If you are transitioning to this module from `aws-eks-experimental`, you might incur changes that require cluster replacements. + +# Implementation Plan + +1. Rename current module to `aws-eks-experimental` on the master branch. + + - This will be released with a BREAKING CHANGE notice and cause users to change their dependency. + +2. Create a staging branch `eks-dev-preview` which contains `aws-eks` as a copy of `aws-eks-experimental`. + + - This will be a long living branch we will branch out of to and merge to. + +3. Implement necessary changes onto the `eks-dev-preview` branch. + + - We branch out of the `aws-dev-preview` branch to separate feature branches so that we can review the changes. + +4. Merge `eks-dev-preview` to master. + + - This merge is the release of the developer preview module. + +# Rationale and Alternatives + +### Rename `eks.Cluster` + +Instead of spinning off to a new module, we can spin off to a new construct. + +That is, rename the current `eks.Cluster` to `eks.ExperimentalCluster` and implement everything we need in `eks.Cluster`. We have actually already done this once with `eks.LegacyCluster`. + +The benefit here is that users won't need to change dependencies. However, this change would also require a name change and duplication of any class that interacts with `eks.Cluster` since those classes may not work with both `eks.Cluster` and `eks.ExperimentalCluster`. + +This approach feels more fragile and doesn't provide much value since the user would still incur a breaking change. It would just be in the form of a class name change, instead of a module name change. + +### Rename new module + +Instead of renaming the current module, we can rename the new module to `aws-eks-dev-preview`. This would prevent the need for the detection of old module usages in the new module code. + +The problem here is that eventually we would need to rename `aws-eks-dev-preview` to `aws-eks`, which will be taken. So we would need to rename `aws-eks` as well, winding up in the same situation, except we now broke the old module again, after we promised not to. + +# Adoption Strategy + +When users upgrade their version of `aws-eks`, they will now receive the new intrusive version. This version will detect that the user had previously been using the old `aws-eks` (which is now `aws-eks-experimental`) module, and display the following error: + +```console +The aws-eks module has undergone a name change, to use the previously named aws-eks module, please change your imports and dependencies to use aws-eks-experimental. +If you'd like to use the new aws-eks module, add the following key to your cdk.json file: "@aws-cdk/aws-eks:dev-preview: true". +``` + +The user will then choose to either change imports to point to the `aws-eks-experimental` module, and continue working without interruption. Or, add the necessary feature flag to `cdk.json` and continue with the new module which will replace the cluster. + +# Future Possibilities + +Hopefully, this little exercise can turn into a well defined mechanism. If we take the current approach and expand it to follow: + +*"Each intrusive change will spin off to a new module"* + +And come up with some sort of naming pattern for old modules, this might work as a general approach. From 5443551d3d01c0131ae405095730a4811f21b760 Mon Sep 17 00:00:00 2001 From: epolon Date: Wed, 26 Aug 2020 21:31:51 +0300 Subject: [PATCH 06/11] lint --- ...44-eks-developer-preview-migration-path.md | 55 +++++++++++-------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/text/0244-eks-developer-preview-migration-path.md b/text/0244-eks-developer-preview-migration-path.md index 7c8eb170d..d40dc3cb7 100644 --- a/text/0244-eks-developer-preview-migration-path.md +++ b/text/0244-eks-developer-preview-migration-path.md @@ -11,25 +11,31 @@ This RFC proposes a migration path for existing users following the upcoming tra # Motivation -As part of transitioning the `aws-eks` module to *Developer Preview*, we need to introduce a few breaking changes that require users to replace their existing clusters. +As part of transitioning the `aws-eks` module to *Developer Preview*, we need to introduce a few breaking changes that require +users to replace their existing clusters. -This poses a major interruption that might need extra planning from the user's side. Because of this, even though the module is currently `experimental`, we want users to be able to replace clusters at their own pace. To that end, we need to come up with some migration strategy. +This poses a major interruption that might need extra planning from the user's side. Because of this, even though the module is +currently `experimental`, we want users to be able to replace clusters at their own pace. To that end, we need to come up with some migration +strategy. # Design Summary -The main idea is to spin off to a new module that introduces all the breaking changes at once. The old module will be effectively locked, and won't receive any updates apart from **p0** bug fixes. -Its essentially the same as rolling out a new major version, but since all -modules are versioned together, we do this by changing the module name, and not the version. +The main idea is to spin off to a new module that introduces all the breaking changes at once. The old module will be effectively +locked, and won't receive any updates apart from **p0** bug fixes. Its essentially the same as rolling out a new major version, +but since all modules are versioned together, we do this by changing the module name, and not the version. -Since the final module we mark as `stable` should be called `aws-eks`, we rename the current module to `aws-eks-experimental`, and move forward with the new one as `aws-eks`. +Since the final module we mark as `stable` should be called `aws-eks`, we rename the current module to `aws-eks-experimental`, +and move forward with the new one as `aws-eks`. -This means that upon upgrade, existing users of `aws-eks` will now receive the developer preview version, which will naively replace their clusters. To avoid that, we need the code to detect this situation and provide clear instructions to the user. +This means that upon upgrade, existing users of `aws-eks` will now receive the developer preview version, which will naively replace their clusters. +To avoid that, we need the code to detect this situation and provide clear instructions to the user. # README In the old module, which is now `aws-eks-experimental`, we will add the following notice to the README. -> This module has been deprecated in favor of the `aws-eks` module. This module will not receive updates apart from critical bug fixes. Note that transitioning to `aws-eks` might incur changes that require cluster replacement. +> This module has been deprecated in favor of the `aws-eks` module. This module will not receive updates apart from critical bug fixes. +> Note that transitioning to `aws-eks` might incur changes that require cluster replacement. In the new module, which is now `aws-eks`, we will add the following notice to the README. @@ -55,37 +61,42 @@ In the new module, which is now `aws-eks`, we will add the following notice to t # Rationale and Alternatives -### Rename `eks.Cluster` +## Rename `eks.Cluster` Instead of spinning off to a new module, we can spin off to a new construct. -That is, rename the current `eks.Cluster` to `eks.ExperimentalCluster` and implement everything we need in `eks.Cluster`. We have actually already done this once with `eks.LegacyCluster`. +That is, rename the current `eks.Cluster` to `eks.ExperimentalCluster` and implement everything we need in `eks.Cluster`. +We have actually already done this once with `eks.LegacyCluster`. -The benefit here is that users won't need to change dependencies. However, this change would also require a name change and duplication of any class that interacts with `eks.Cluster` since those classes may not work with both `eks.Cluster` and `eks.ExperimentalCluster`. +The benefit here is that users won't need to change dependencies. However, this change would also require a name change and +duplication of any class that interacts with `eks.Cluster` since those classes may not work with both `eks.Cluster` and `eks.ExperimentalCluster`. -This approach feels more fragile and doesn't provide much value since the user would still incur a breaking change. It would just be in the form of a class name change, instead of a module name change. +This approach feels more fragile and doesn't provide much value since the user would still incur a breaking change. +It would just be in the form of a class name change, instead of a module name change. -### Rename new module +## Rename new module -Instead of renaming the current module, we can rename the new module to `aws-eks-dev-preview`. This would prevent the need for the detection of old module usages in the new module code. +Instead of renaming the current module, we can rename the new module to `aws-eks-dev-preview`. This would prevent the need for +the detection of old module usages in the new module code. -The problem here is that eventually we would need to rename `aws-eks-dev-preview` to `aws-eks`, which will be taken. So we would need to rename `aws-eks` as well, winding up in the same situation, except we now broke the old module again, after we promised not to. +The problem here is that eventually we would need to rename `aws-eks-dev-preview` to `aws-eks`, which will be taken. So we would +need to rename `aws-eks` as well, winding up in the same situation, except we now broke the old module again, after we promised not to. # Adoption Strategy -When users upgrade their version of `aws-eks`, they will now receive the new intrusive version. This version will detect that the user had previously been using the old `aws-eks` (which is now `aws-eks-experimental`) module, and display the following error: +When users upgrade their version of `aws-eks`, they will now receive the new intrusive version. This version will detect that the user +had previously been using the old `aws-eks` (which is now `aws-eks-experimental`) module, and display the following error: ```console The aws-eks module has undergone a name change, to use the previously named aws-eks module, please change your imports and dependencies to use aws-eks-experimental. If you'd like to use the new aws-eks module, add the following key to your cdk.json file: "@aws-cdk/aws-eks:dev-preview: true". ``` -The user will then choose to either change imports to point to the `aws-eks-experimental` module, and continue working without interruption. Or, add the necessary feature flag to `cdk.json` and continue with the new module which will replace the cluster. +The user will then choose to either change imports to point to the `aws-eks-experimental` module, and continue working without interruption. +Or, add the necessary feature flag to `cdk.json` and continue with the new module which will replace the cluster. # Future Possibilities -Hopefully, this little exercise can turn into a well defined mechanism. If we take the current approach and expand it to follow: - -*"Each intrusive change will spin off to a new module"* - -And come up with some sort of naming pattern for old modules, this might work as a general approach. +Hopefully, this little exercise can turn into a well defined mechanism. +If we take the current approach and expand it to follow *"Each intrusive change will spin off to a new module"* And come up with +some sort of naming pattern for old modules, this might work as a general approach. From a61d33a8691fc71682be852ea192d9295b87e495 Mon Sep 17 00:00:00 2001 From: epolon Date: Thu, 27 Aug 2020 16:06:12 +0300 Subject: [PATCH 07/11] shift direction --- lint.sh | 2 +- ...44-eks-developer-preview-migration-path.md | 97 +++++++++++++------ 2 files changed, 67 insertions(+), 32 deletions(-) diff --git a/lint.sh b/lint.sh index 610e7b02a..af0e8f176 100755 --- a/lint.sh +++ b/lint.sh @@ -5,5 +5,5 @@ set -euo pipefail linters=$PWD/tools/linters npm install --prefix $linters -find . -type f -name '*.md' -not -path '*/node_modules/*' -not -path '*/.github/*' |\ +find . -type f -name '*.md' -not -path '*/node_modules/*' -not -path '*.history/*' -not -path '*/.github/*' |\ xargs -I'{}' $linters/node_modules/.bin/markdownlint -c $linters/markdownlint.json $@ '{}' diff --git a/text/0244-eks-developer-preview-migration-path.md b/text/0244-eks-developer-preview-migration-path.md index d40dc3cb7..f0bdbb25d 100644 --- a/text/0244-eks-developer-preview-migration-path.md +++ b/text/0244-eks-developer-preview-migration-path.md @@ -7,7 +7,8 @@ related issue: https://github.com/aws/aws-cdk-rfcs/issues/244 # Summary -This RFC proposes a migration path for existing users following the upcoming transition of the `aws-eks` module from *Experimental* to *Developer Preview*. +This RFC proposes a migration path for existing users following the upcoming transition of the `aws-eks` module +from *Experimental* to *Developer Preview*. # Motivation @@ -15,49 +16,68 @@ As part of transitioning the `aws-eks` module to *Developer Preview*, we need to users to replace their existing clusters. This poses a major interruption that might need extra planning from the user's side. Because of this, even though the module is -currently `experimental`, we want users to be able to replace clusters at their own pace. To that end, we need to come up with some migration -strategy. +currently `experimental`, we want users to be able to replace clusters at their own pace. To that end, we need to come up +with some migration strategy. # Design Summary -The main idea is to spin off to a new module that introduces all the breaking changes at once. The old module will be effectively -locked, and won't receive any updates apart from **p0** bug fixes. Its essentially the same as rolling out a new major version, -but since all modules are versioned together, we do this by changing the module name, and not the version. +The main idea is to spin off to a new module. The old module will still be active, but will not receive updates that +require cluster replacement. The new module will be called `aws-eks-next`, to resemble the common practice of +using an `@next` tag to indicate pre-releases. -Since the final module we mark as `stable` should be called `aws-eks`, we rename the current module to `aws-eks-experimental`, -and move forward with the new one as `aws-eks`. +This will allow existing user to remain unaffected, while giving us a chance to incrementally introduce and validate these intrusive changes. +When we feel comfortable with the stability and feature set of `aws-eks-next`, we promote it to `aws-eks` and rename the +old module to `aws-eks-experimental`. -This means that upon upgrade, existing users of `aws-eks` will now receive the developer preview version, which will naively replace their clusters. -To avoid that, we need the code to detect this situation and provide clear instructions to the user. +After the promotion takes place, users will automatically receive the version that will replace their clusters, even though +they didn't opt-in for it. To prevent that, we will put the usage of the new module behind a feature flag that users will +have to explicitly enable. # README -In the old module, which is now `aws-eks-experimental`, we will add the following notice to the README. +There are two relevant points in time that we need to address. -> This module has been deprecated in favor of the `aws-eks` module. This module will not receive updates apart from critical bug fixes. -> Note that transitioning to `aws-eks` might incur changes that require cluster replacement. +## Pre Promotion -In the new module, which is now `aws-eks`, we will add the following notice to the README. +*Both `aws-eks` and `aws-eks-next` exist.* -> If you are transitioning to this module from `aws-eks-experimental`, you might incur changes that require cluster replacements. +README for `aws-eks` will include the following notice: -# Implementation Plan +> This module will eventually be replaced by the [`aws-eks-next`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next) module. +> This change will require you to replace your existing clusters. +> Since we know this kind of operation is highly intrusive, we will still be supporting the current module under the `aws-eks-experimental` name. +> This way, you can choose to migrate at your own pace, and plan out the cluster replacement as needed. + +README for `aws-eks-next` will include the following notice: -1. Rename current module to `aws-eks-experimental` on the master branch. +> This module is a pre-release for the next version of the EKS Construct Library. +> +> ![#f03c15](https://via.placeholder.com/15/f03c15/000000?text=+) **Note: Use with caution. +> Migrating to this module from `aws-eks` will require you to replace your clusters, and may require additional +> cluster replacements in the future. Once this module is promoted to a release, changes that require cluster replacement will no longer be introduced.** - - This will be released with a BREAKING CHANGE notice and cause users to change their dependency. +## Post Promotion -2. Create a staging branch `eks-dev-preview` which contains `aws-eks` as a copy of `aws-eks-experimental`. +*`aws-eks` is now the new version, and `aws-eks-experimental` is the old one.* - - This will be a long living branch we will branch out of to and merge to. +README for `aws-eks-experimental` will include the following notice: -3. Implement necessary changes onto the `eks-dev-preview` branch. +> This module is now deprecated in favor of [`aws-eks`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next). +> +> Note that migrating to [`aws-eks`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next) will require you to replace your existing clusters. - - We branch out of the `aws-dev-preview` branch to separate feature branches so that we can review the changes. +README for `aws-eks` will include the following notice: -4. Merge `eks-dev-preview` to master. +> **Note: Migrating to this module from [`aws-eks-experimental`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-experimental) +> will require you to replace your existing clusters. - - This merge is the release of the developer preview module. +# Implementation Plan + +1. Duplicate the current `aws-eks` module into an `aws-eks-next` module and push to master. +2. Implement the feature flag protection for using the new module. +3. Incrementally implement the required changes for cluster replacement onto the `aws-eks-next` module. +In addition, continuously port changes from `aws-eks` into `aws-eks-next` and release `aws-eks-next` in the normal CDK release. +4. Rename and deprecate `aws-eks` to `aws-eks-experimental` and rename `aws-eks-next` to `aws-eks`. # Rationale and Alternatives @@ -70,22 +90,32 @@ We have actually already done this once with `eks.LegacyCluster`. The benefit here is that users won't need to change dependencies. However, this change would also require a name change and duplication of any class that interacts with `eks.Cluster` since those classes may not work with both `eks.Cluster` and `eks.ExperimentalCluster`. +It might also require changes to transitive types that don't directly depend on the the cluster. This approach feels more fragile and doesn't provide much value since the user would still incur a breaking change. It would just be in the form of a class name change, instead of a module name change. -## Rename new module +## Rename old module + +Instead of renaming the new module, we can create a staging branch that will both rename the existing module to `aws-eks-experimental`, and implement +all changes into a new duplicated `aws-eks` module. When we are done, we merge the staging branch and release `aws-eks` +as the new version, and `aws-eks-experimental` as the old version. -Instead of renaming the current module, we can rename the new module to `aws-eks-dev-preview`. This would prevent the need for -the detection of old module usages in the new module code. +This has the benefit of avoiding the rename at the end of the process. However, this doesn't have any affect on the user. +As far as the user is concerned, a rename of the existing `aws-eks` module will happen exactly once, when the developer +preview is published, regardless of which approach. -The problem here is that eventually we would need to rename `aws-eks-dev-preview` to `aws-eks`, which will be taken. So we would -need to rename `aws-eks` as well, winding up in the same situation, except we now broke the old module again, after we promised not to. +The problem with this approach tough is the fact it accumulates many unpublished changes and releases them all at once. +While we won't be advocating for users to use the `aws-eks-next` module, it still gives us the option to use it ourselves exactly like customers would. # Adoption Strategy -When users upgrade their version of `aws-eks`, they will now receive the new intrusive version. This version will detect that the user -had previously been using the old `aws-eks` (which is now `aws-eks-experimental`) module, and display the following error: +During the development of the `aws-eks-next` module, users are not expected to switch over to it. If some users choose to anyway, we will make our intentions and plan +for this module very clear, as already mentioned in the [README](#README) section. + +Once development is finalized, and we promote `aws-eks-next` to `aws-eks`, the expected user experience is as such. + +Since the current `aws-eks` module is guarded with a feature flag, upon upgrade, **ALL** users will receive the following message: ```console The aws-eks module has undergone a name change, to use the previously named aws-eks module, please change your imports and dependencies to use aws-eks-experimental. @@ -95,6 +125,11 @@ If you'd like to use the new aws-eks module, add the following key to your cdk.j The user will then choose to either change imports to point to the `aws-eks-experimental` module, and continue working without interruption. Or, add the necessary feature flag to `cdk.json` and continue with the new module which will replace the cluster. +# Unresolved questions + +- The current approach creates a strange quick where post promotion, we are left we a deprecated library called `aws-eks-experimental`. +This library isn't actually experimental, in the sense that it won't actually break since we stop touching it. Can we come up with a different name? Perhaps `aws-eks-heritage`? (`legacy` is taken :\) + # Future Possibilities Hopefully, this little exercise can turn into a well defined mechanism. From 1d8c216654c73c79132e2881a68b9ad075ef4cb4 Mon Sep 17 00:00:00 2001 From: epolon Date: Thu, 27 Aug 2020 16:07:28 +0300 Subject: [PATCH 08/11] revert lint changes --- lint.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lint.sh b/lint.sh index af0e8f176..610e7b02a 100755 --- a/lint.sh +++ b/lint.sh @@ -5,5 +5,5 @@ set -euo pipefail linters=$PWD/tools/linters npm install --prefix $linters -find . -type f -name '*.md' -not -path '*/node_modules/*' -not -path '*.history/*' -not -path '*/.github/*' |\ +find . -type f -name '*.md' -not -path '*/node_modules/*' -not -path '*/.github/*' |\ xargs -I'{}' $linters/node_modules/.bin/markdownlint -c $linters/markdownlint.json $@ '{}' From 0601893ce978fcfd861c4a34f7cb1c6ab6ed336a Mon Sep 17 00:00:00 2001 From: epolon Date: Thu, 27 Aug 2020 16:11:13 +0300 Subject: [PATCH 09/11] lint --- text/0244-eks-developer-preview-migration-path.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/text/0244-eks-developer-preview-migration-path.md b/text/0244-eks-developer-preview-migration-path.md index f0bdbb25d..3c11b9aae 100644 --- a/text/0244-eks-developer-preview-migration-path.md +++ b/text/0244-eks-developer-preview-migration-path.md @@ -64,7 +64,8 @@ README for `aws-eks-experimental` will include the following notice: > This module is now deprecated in favor of [`aws-eks`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next). > -> Note that migrating to [`aws-eks`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next) will require you to replace your existing clusters. +> Note that migrating to [`aws-eks`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next) will +> require you to replace your existing clusters. README for `aws-eks` will include the following notice: @@ -110,8 +111,8 @@ While we won't be advocating for users to use the `aws-eks-next` module, it stil # Adoption Strategy -During the development of the `aws-eks-next` module, users are not expected to switch over to it. If some users choose to anyway, we will make our intentions and plan -for this module very clear, as already mentioned in the [README](#README) section. +During the development of the `aws-eks-next` module, users are not expected to switch over to it. If some users choose to anyway, +we will make our intentions and plan for this module very clear, as already mentioned in the [README](#README) section. Once development is finalized, and we promote `aws-eks-next` to `aws-eks`, the expected user experience is as such. @@ -128,7 +129,8 @@ Or, add the necessary feature flag to `cdk.json` and continue with the new modul # Unresolved questions - The current approach creates a strange quick where post promotion, we are left we a deprecated library called `aws-eks-experimental`. -This library isn't actually experimental, in the sense that it won't actually break since we stop touching it. Can we come up with a different name? Perhaps `aws-eks-heritage`? (`legacy` is taken :\) +This library isn't actually experimental, in the sense that it won't actually break since we stop touching it. Can we come up +with a different name? Perhaps `aws-eks-heritage`? (`legacy` is taken :\) # Future Possibilities From 5442938c70a9fddb216aaf9828f549eabdbefdf3 Mon Sep 17 00:00:00 2001 From: epolon Date: Thu, 27 Aug 2020 16:20:31 +0300 Subject: [PATCH 10/11] rephrasing --- text/0244-eks-developer-preview-migration-path.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0244-eks-developer-preview-migration-path.md b/text/0244-eks-developer-preview-migration-path.md index 3c11b9aae..79f4da1cb 100644 --- a/text/0244-eks-developer-preview-migration-path.md +++ b/text/0244-eks-developer-preview-migration-path.md @@ -45,7 +45,7 @@ README for `aws-eks` will include the following notice: > This module will eventually be replaced by the [`aws-eks-next`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next) module. > This change will require you to replace your existing clusters. -> Since we know this kind of operation is highly intrusive, we will still be supporting the current module under the `aws-eks-experimental` name. +> Since we know this kind of operation is highly intrusive, when the replacement happens, we will still be supporting the current module under the `aws-eks-experimental` name. > This way, you can choose to migrate at your own pace, and plan out the cluster replacement as needed. README for `aws-eks-next` will include the following notice: From 1a0b2e56873a21589f2d251238f84eb72f832ab3 Mon Sep 17 00:00:00 2001 From: epolon Date: Thu, 27 Aug 2020 16:30:30 +0300 Subject: [PATCH 11/11] remove fluff --- text/0244-eks-developer-preview-migration-path.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/0244-eks-developer-preview-migration-path.md b/text/0244-eks-developer-preview-migration-path.md index 79f4da1cb..6052d4932 100644 --- a/text/0244-eks-developer-preview-migration-path.md +++ b/text/0244-eks-developer-preview-migration-path.md @@ -46,7 +46,6 @@ README for `aws-eks` will include the following notice: > This module will eventually be replaced by the [`aws-eks-next`](https://github.com/aws/aws-cdk/tree/master/packages/%40aws-cdk/aws-eks-next) module. > This change will require you to replace your existing clusters. > Since we know this kind of operation is highly intrusive, when the replacement happens, we will still be supporting the current module under the `aws-eks-experimental` name. -> This way, you can choose to migrate at your own pace, and plan out the cluster replacement as needed. README for `aws-eks-next` will include the following notice: