Add first version of the migration guide to Krane 1.0

1.0-Upgrade.md

@@ -0,0 +1,108 @@
+# kubernetes-deploy 0.31.0 -> krane 1.0.0 migration guide
+
+**THIS MIGRATION GUIDE IS A WORK IN PROGRESS. THINGS CAN STILL CHANGE BEFORE 1.0.0**
+
+`kubernetes-deploy` was renamed `krane` when version 1.0.0 was released. Version 1.0.0 introduced new features and [breaking changes](CHANGELOG.md). This guide will help you transition to version 1.0.0 as smoothly as possible.
+
+**TL;DR**:
+* The command-line interface was redesigned; besides the name change, there are breaking changes in several flags.
+* There are breaking changes in the public API (such as the renaming of the `KubernetesDeploy` namespace to `Krane`, and the change in default values for different arguments of the public interface).
+* StatsD metrics will now be generated with the `krane` prefix.
+* `kubernetes-deploy` (now `krane deploy`) / `DeployTask` can no longer deploy global (non-namespaced) resources. A new command called `krane global-deploy` and a related class called `GlobalDeployTask` were added to replace that feature.
+* If you attempt to install two gems that have conflicting executables, `gem install` will warn you but the most recently installed one will win. This means that you can run both `kubernetes-deploy` 0.31.0 and `krane` 1.0.0 side by side by doing:
+
+```bash
+gem install kubernetes-deploy
+gem install krane
+```
+
+## Public API changes
+
+The only breaking change in the public API between version 0.31.0 and 1.0.0 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.31.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).
+
+## Command-line interface changes
+
+Old command | New command
+--- | ---
+`kubernetes-deploy` | `krane deploy`
+`kubernetes-deploy -v` | `krane version`
+`kubernetes-render` | `krane render`
+`kubernetes-run` | `krane run`
+`kubernetes-restart` | `krane restart`
+`[kubernetes-deploy with global resources in templates]` | `krane global-deploy`
+
+### Flag changes
+
+The following tables provide a mapping of the flags previously supported in `kubernetes-deploy` and their new version in `krane` (if applicable).
+
+Important: you can't repeat flags. If you need to provide multiple arguments for a flag, use a space-separated list (e.g. `-f file1.yml file2.yml`) unless specified otherwise.
+
+#### krane deploy
+
+Old flag | New flag | Comments
+--- | --- | ---
+--bindings=BINDINGS | --bindings=BINDINGS |
+--skip-wait | --verify-result=true |
+--allow-protected-ns | --protected-namespaces=default,kube-system,kube-public | Added the ability to specify which namespaces are protected
+--no-prune | --prune=true |
+--template-dir | -f, --filename | Makes all our commands accept this arg, which is now required for the deploy task
+--verbose-log-prefix | --verbose-log-prefix |
+--max-watch-seconds=seconds | --global-timeout=300s | Changed flag name and default value to be a duration (expressed using strings like "300s" or "1h")
+--selector | --selector |
+-h, --help | -h, --help |
+-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
+
+#### krane restart
+
+Old flag | New flag | Comments
+--- | --- | ---
+--deployments=LIST | --deployments=LIST |
+--max-watch-seconds=seconds | --global-timeout=300s | Changed flag name and default value to be a duration (expressed using strings like "300s" or "1h")
+[none] | --verify-result=true | Define whether it should wait for results or exit immediately after validation
+
+#### krane run
+
+Old flag | New flag | Comments
+--- | --- | ---
+--skip-wait | --verify-result=true |
+--max-watch-seconds=seconds | --global-timeout=300s | Changed flag name and default value to be a duration (expressed using strings like "300s" or "1h")
+--entrypoint | --command | Changed flag name to make its purpose clearer
+--template | --template | Changed to be required
+[it is positional now] | --arguments | Optional flag, as `command` or the template might already specify the required arguments
+--env-vars=ENV_VARS | --env-vars=ENV_VARS |
+
+#### krane render
+
+Old flag | New flag | Comments
+--- | --- | ---
+--bindings=BINDINGS | --bindings=BINDINGS |
+--template-dir | -f, --filename | Changed to be more aligned with `kubectl apply` and our other tasks
+$REVISION | --current-sha | The environment variable REVISION was dropped in favour of an explicit flag
+
+## Running `kubernetes-deploy` and `krane` side by side
+
+If you attempt to install two gems that have conflicting executables (as is the case here), `gem install` will warn you but the most recently installed one will win. This means that you can run both `kubernetes-deploy` 0.31.0 and `krane` 1.0.0 side by side by doing:
+
+```bash
+gem install kubernetes-deploy -v 0.31.0
+gem install -f krane -v 1.0.0
+```
+
+This can help you incrementally port scripts that use the old CLI to the new one.
+
+## 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:
+
+```bash
+$ cat my-template.yml
+    apiVersion: storage.k8s.io/v1
+    kind: StorageClass
+    metadata:
+      name: testing-storage-class
+    provisioner: kubernetes.io/no-provisioner
+$ krane global-deploy my-k8s-context -f my-template.yml --selector app=krane
+```