-
Notifications
You must be signed in to change notification settings - Fork 115
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
106 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
# kubernetes-deploy 0.30.0 -> krane 1.0 migration guide | ||
|
||
**THIS MIGRATION GUIDE IS A WORK IN PROGRESS. THINGS CAN STILL CHANGE BEFORE 1.0** | ||
|
||
The `kubernetes-deploy` became `krane` in its 1.0 version, and besides the name change we also introduced new features and [breaking changes](CHANGELOG.md). This guide will help you transition to version 1.0 as smoothly as possible. | ||
|
||
**TL;DR**: | ||
* The command-line interface was redesigned; besides the name change, there are breaking changes in several flags. | ||
* The only breaking change in the public API is the renaming of the `KubernetesDeploy` namespace to `Krane`. | ||
* 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.30.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 is the renaming of the `KubernetesDeploy` namespace to `Krane`. Besides that, the API of the major public classes (`DeployTask`, `RenderTask`, `RunTask`, 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). | ||
|
||
## 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 previous flags we supported and their new version (if applicable). | ||
|
||
#### 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 | ||
--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 | ||
[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 | ||
--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.30.0 and `krane` 1.0.0 side by side by doing: | ||
|
||
```bash | ||
gem install kubernetes-deploy -v 0.30.0 | ||
gem install 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 | ||
``` |