# kubernetes-deploy 0.31.1 -> krane 1.0.0 migration guide

`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; alongside 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.
* `krane deploy` now considers all namespaced resources eligible for pruning, including
custom resources. See [blacklist](https://github.com/Shopify/krane/blob/master/lib/krane/cluster_resource_discovery.rb#L20) for exceptions.
* `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.
* `krane deploy` will not render erb templates. Use `krane render | krane deploy --stdin` to reproduce this functionality.
* If you attempt to install two gems that have conflicting executables, `gem install` will warn you but the most recently installed one will win.

## Public API changes

Besides the renaming of the `KubernetesDeploy` namespace to `Krane`, we made the public interfaces of the major public classes (`DeployTask`, `RenderTask`, `RunnerTask`, and `RestartTask`) match the CLI flag names more closely.

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).

#### `DeployTask#new`

Old name | New name | Comments
--- | --- | ---
template_paths | filenames |
max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)
template_dir | [none] | Removed in favour of `filenames`
allow_globals | [none] | Removed. Use `GlobalDeployTask` instead

#### `DeployTask#run`

Old name | New name | Comments
--- | --- | ---
allow_protected_ns | [none] | This is now an implicit argument derived from the usage of `protected_namespaces` instead

#### `RestartTask#new`

Old name | New name | Comments
--- | --- | ---
max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)

#### `RestartTask#run`

Method signature changed from this:

```ruby
def run(deployments, selector:)
```

... to this, to maintain the convention of using keyword arguments for all the public interfaces:

```ruby
def run(deployments:, selector:)
```

#### `RunnerTask#new`

Old name | New name | Comments
--- | --- | ---
max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)

#### `RunnerTask#run`

Old name | New name | Comments
--- | --- | ---
task_template | filename |
entrypoint | command |
args | arguments |


#### `RenderTask#new`

Old name | New name | Comments
--- | --- | ---
template_paths | filenames |
max_watch_seconds | global_timeout | This is now a duration that can be expressed in a more user-friendly language (e.g. `30s` or `1h`)
template_dir | [none] | Removed in favour of `filenames`

#### `RenderTask#run`

Old name | New name | Comments
--- | --- | ---
only_filenames | [none] | Removed in favour of `filenames` in `RenderTask#new`

Method signature changed from this:

```ruby
def run(stream, only_filenames = [])
```

... to this, to maintain the convention of using keyword arguments for all the public interfaces:

```ruby
def run(stream:)
```

## 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, --filenames | Makes all krane commands accept this argument, 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 | [none] | The environment variable REVISION was dropped because deploy no longer renders.
[none] | --stdin | Allow template filenames given from stdin stream

#### 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 | Defines 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, --filenames | Changed to be more aligned with `kubectl apply` and other krane tasks
$REVISION | --current-sha | The environment variable REVISION was dropped in favour of an explicit flag
[none] | --stdin | Allow template filenames given from stdin stream

## 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.1 and `krane` 1.0.0 side by side by doing:

```bash
gem install kubernetes-deploy -v 0.31.1
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
      labels:
        app: krane
    provisioner: kubernetes.io/no-provisioner
$ krane global-deploy my-k8s-context -f my-template.yml --selector app=krane
```