Shopify krane: Kubernetes Deploys with kubectl and Verification

Why krane Wraps kubectl for Namespace Deployments

Shopify krane addresses a specific gap around `kubectl apply`. The README calls kubectl a useful deployment mechanism, but notes that it leaves operators asking what changed and whether the change worked. Those questions matter in CI/CD, where a deployment job needs a clear pass or fail result for each release attempt.

The intended users are teams shipping Kubernetes manifests to a namespace, particularly automation systems that cannot treat a successful API request as proof that new workloads are usable. At Shopify, the project is used within the open-source Shipit deployment application, which gives krane a concrete setting for its command-line interface and deployment result reporting.

krane is not a replacement for kubectl. Its deploy operation uses kubectl under the hood and adds a deployment workflow around it. The additional scope includes watching requested changes, reporting debug information for failures, creating some resources before dependent workloads, running bare pods at the beginning of a deployment, and rendering dynamic template values before deployment.

That distinction matters when choosing the tool. If the requirement is an interactive resource inspection or an arbitrary kubectl command, krane is the wrong layer. If the requirement is a namespace-scoped release operation with rollout verification and a CI result, its added workflow is directly relevant.

krane's Deploy Pipeline and Namespace Ownership Model

The core deploy operation targets an application namespace and a Kubernetes context. Resource manifests are selected through filenames or STDIN, then applied through the kubectl-based deployment process. krane watches the requested changes and attempts to determine whether the workloads deploy correctly, rather than stopping at submission.

A notable design choice is predeployment. The README identifies resources such as `ConfigMap` and `PersistentVolumeClaim` as candidates for predeployment. This ordering matters when a `Deployment` consumes configuration or storage created in the same release. A simple unordered apply can submit both objects without ensuring the consumer starts after the resource it needs exists.

Namespace pruning is the most consequential behavior. By default, krane prunes resources in the target namespace that carry the `kubectl.kubernetes.io/last-applied-configuration` annotation and are absent from the current template set. This treats the deployment directory as an ownership boundary, but only for resources carrying that annotation. The `--no-prune` option disables it, while `--selector` limits pruning to matching labels.

Shared namespaces therefore require deliberate labels. With `--selector`, every resource template must carry a matching label. The `--selector-as-filter` option changes deployment filtering so that a release can target only matching resources and does not fail merely because some templates in the file do not match. These modes solve different problems: one limits what may be pruned, while the other limits what may be deployed. They should not be treated as interchangeable.

Installing krane and Running the First Namespace Deploy

The documented prerequisites are Ruby 2.7 or later and a Kubernetes cluster running Kubernetes v1.24.0 or higher. The README also requires kubectl v1.28.0 or later in `$PATH`, plus a kubeconfig configured for the target cluster. It separately identifies `$GOOGLE_APPLICATION_CREDENTIALS` as necessary when the kubeconfig user uses GCP authentication.

Install the gem with the documented command:

gem install krane

The first real operation has the following documented form. Replace the namespace and context placeholders with values from the target environment:

krane deploy <app's namespace> <kube context>

By default, krane reads `~/.kube/config` when `$KUBECONFIG` is omitted. When set, `$KUBECONFIG` may point to one or more valid files, separated by colons on Linux and Mac or semicolons on Windows. The resulting status should distinguish a successful deployment from a change that failed rollout verification.

For an initial use, select a non-protected namespace unless the organization has deliberately configured the protected namespace list. The README documents `default`, `kube-system`, and `kube-public` as protected namespaces for the `protected-namespaces` option. It also warns against deploying `Secret` resources without reviewing the risk because sensitive information may appear in logs.

Deployment Controls for Timeouts, Labels, and Result Checks

krane exposes deployment controls through command-line options, with `krane help` identified by the README as the authoritative list. This matters because the option set includes operational behavior that cannot be inferred from the basic deploy syntax alone.

`--global-timeout=duration` applies a timeout to each resource deployment, producing a timeout error when a resource takes longer than the configured duration. `--no-verify-result` skips verification that workloads correctly deployed, which removes one of the tool's central checks and should be treated as an explicit exception rather than a routine setting.

`--filenames` or `-f` accepts directories, filenames, or `-` for STDIN. `--verbose-log-prefix` adds context and namespace information to log prefixes. `--protected-namespaces` defines namespaces that fail validation, while `--no-prune` leaves removed resources behind.

The pruning controls need particular scrutiny in shared clusters. Restricting pruning with `--selector` requires matching labels on all templates. Filtering deployment with `--selector-as-filter` can deploy a subset without requiring every resource in a YAML file to match. These features are useful when krane manages only part of a namespace, but they also place responsibility on operators to make ownership labels consistent and complete.

The warning around `Secret` resources applies to this entire result-oriented design. krane needs enough information to explain deployment failures, but the README explicitly says it cannot guarantee that sensitive information will never be logged.

Rendering, Deploy-Time Tasks, and krane's Supporting Commands

The repository includes commands for work that usually surrounds a namespace deployment. `krane render` is intended for deployments that need dynamic values rendered in templates before kubectl applies the resulting resources.

`krane run` runs tasks through bare pods and is intended for operations such as Rails migrations. The README's deployment section specifically describes running tasks at the beginning of a deploy. This sequencing is useful when a database schema change must precede application rollout.

`krane restart` provides a separate mechanism for restarting deployments. Its exact syntax and implementation details should be evaluated from its own help output before it is incorporated into a release process.

For Kubernetes secrets, krane supports creation from encrypted EJSON, allowing an encrypted representation to be committed to a repository. This addresses secret distribution, but it introduces an EJSON-specific workflow. The general `Secret` logging warning remains relevant.

The project also documents deployment of custom resources, indicating that krane is not limited to built-in workload kinds.

Compatibility, Maintenance Signals, and the MIT License

The repository was not archived, and its last push was on 2026-09-29. The latest listed release is v3.4.1 from 2024-01-29. These dates show recent repository activity alongside an older published release, but the release list alone does not establish how changes on `main` reach gem users.

The documented compatibility floor is Kubernetes v1.24.0, while the installation section requires kubectl v1.28.0 or later. The compatibility table marks Kubernetes 1.29 through 1.34 as currently tested. Krane says it supports official upstream-supported Kubernetes and Ruby versions in its compatibility matrix, while noting that older releases may still work.

Ruby 2.7+ is the stated prerequisite. Organizations should also account for the external dependencies implied by the documented workflow: kubectl, kubeconfig access, a reachable cluster, and EJSON when encrypted secrets are used.

Krane is released under the MIT License. That permits use and modification under the license's conditions, but the repository excerpt does not provide the full license text, dependency license inventory, or operational obligations for a particular deployment. License compatibility should be checked against the complete `LICENSE.txt` and the dependencies selected by `krane.gemspec`.

Where krane Is the Wrong Deployment Layer

krane is a poor fit when the operation is not a namespace release. Its model assumes a target namespace, a set of resource templates, rollout verification, and a pruning rule based on the current template set. Arbitrary cluster administration, ad hoc inspection, and workflows that depend on kubectl plugins are better handled directly through kubectl.

It can also be unsafe to adopt without clear resource ownership. Default pruning removes annotated namespace resources absent from the current deployment input. In a shared namespace, accidentally supplying an incomplete template set could remove resources that the release process does not represent. Label-scoped pruning reduces that exposure, but only when labels are consistently applied.

`--no-verify-result` weakens the feature that distinguishes krane from a thin kubectl wrapper. Deployments with workloads whose readiness cannot be established through the result checks may therefore need investigation before teams rely on the process as a release gate.

For secret-bearing releases, there is another boundary. EJSON support helps with encrypted repository data, but the documentation explicitly warns that deployed secrets may still be logged. Environments with strict secret-log controls need to review that warning against their own policies before adoption.

Editorial conclusion

krane fits teams that deploy templates to a Kubernetes namespace and need rollout verification or predeployment tasks. It is less suitable for operators who only want direct kubectl semantics or cannot accept namespace pruning as the default. Before adoption, verify Ruby and kubectl requirements, Kubernetes support, kubeconfig authentication, resource ownership, and whether secrets can remain outside command output. For a first deployment, start with a non-protected namespace and review the exact resources selected for pruning.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Shopify/krane on GitHub