Skip to content

Latest commit

 

History

History
185 lines (136 loc) · 7.75 KB

1.0-Upgrade.md

File metadata and controls

185 lines (136 loc) · 7.75 KB
Raw

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

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:

def run(deployments, selector:)

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

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:

def run(stream, only_filenames = [])

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

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:

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:

$ 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