Kruby Client

Ruby client for the kubernetes API.

Project Background

• Fork source: kubernetes-client/ruby.
• This project is forked from the original Kubernetes Ruby client codebase after official maintenance had effectively stalled.
• It is now maintained as a community-driven fork to keep pace with current Kubernetes API versions.
• This fork includes community-maintained modifications (packaging, compatibility fixes, CI/runtime requirements, and docs) in addition to OpenAPI-generated code.

Release Tracking

• User-visible changes are tracked in CHANGELOG.md.
• Release tags use the format v<version> (for example v1.36.1.1).
• Pushed release tags automatically publish a GitHub Release using the matching changelog section.

Generation Policy

• Like other official Kubernetes clients, this client is generated from Kubernetes OpenAPI specifications.
• Code generation is performed with OpenAPI Generator, and the generated client is versioned to the target Kubernetes OpenAPI release.

Compatibility Matrix

Kubernetes version	Kubernetes API (OpenAPI)	Client gem version
1.31	release-1.36	1.36.1.1
1.32	release-1.36	1.36.1.1
1.33	release-1.36	1.36.1.1
1.34	release-1.36	1.36.1.1
1.35	release-1.36	1.36.1.1
1.36	release-1.36	1.36.1.1

Requirements

• Ruby 3.3.0+

Installation

Add this gem to your Gemfile:

gem "kruby", "~> 1.36"

Usage

require 'kruby'
require 'pp'

kube_config = Kubernetes::KubeConfig.new("#{ENV['HOME']}/.kube/config")
config = Kubernetes::Configuration.new()

kube_config.configure(config)

client = Kubernetes::CoreV1Api.new(Kubernetes::ApiClient.new(config))

pp client.list_namespaced_pod('default')

For backward compatibility, require 'kubernetes' is also supported.

Guides and Examples

• The gem-facing README with curated API entry points lives in kubernetes/README.md.
• A categorized example index lives in examples/README.md.
• Generated endpoint and model references live under kubernetes/docs/.

Useful starting points:

• examples/simple/simple.rb for a minimal read-only client
• examples/dry-run/dry-run.rb for safe write validation
• examples/label-selector/label-selector.rb for efficient filtered list calls
• examples/logs/logs.rb for log retrieval and cleanup
• examples/multi-watch/multi-watch.rb for concurrent watch streams

Thread Safety

Kubernetes::Configuration.default and Kubernetes::ApiClient.default are shared singletons. In multi-threaded callers, prefer per-thread instances via Kubernetes::Configuration.new and Kubernetes.new_client_from_config instead of mutating the shared defaults.

Contribute

Please see CONTRIBUTING.md for instructions on how to contribute.

Before committing, enable the versioned git hooks:

scripts/hooks/install-git-hooks.sh

The pre-commit hook generates docs/handoff.md from the staged diff and stages it in the same commit.

Code of conduct

Participation in this repository is governed by the Code of Conduct.

Development

Update client

to update the client clone the gen repo and run this command at the root of the client repo:

${GEN_REPO_BASE}/openapi/ruby.sh kubernetes settings

For a full, repeatable upgrade workflow (including verification and troubleshooting), see:

• docs/kubernetes-version-upgrade.md

E2E testing

Kind-backed E2E runs currently support Kubernetes 1.31, 1.32, 1.33, 1.34, 1.35, and 1.36. The single-version default E2E Kind environment is 1.35, the matrix default runs 1.31 through 1.36, and the repository pins official kindest/node images for deterministic coverage. Use kind v0.32.0 or newer for Kubernetes 1.36 E2E runs.

Run a single Kubernetes version:

scripts/e2e/run-e2e --mode full --kubernetes-version 1.35
scripts/e2e/run-e2e --mode targeted --kubernetes-version 1.31 --targets 'core/v1/pods:create'

Run the supported Kubernetes matrix:

scripts/e2e/run-e2e-matrix --mode full
E2E_MAX_PARALLEL=1 scripts/e2e/run-e2e-matrix --mode full
scripts/e2e/run-e2e-matrix --mode targeted --versions 1.31,1.36 --targets 'core/v1/pods:create'

For troubleshooting and cleanup guidance, see:

• docs/e2e-kind-testing.md
• docs/test-suite.md

Test workflow

From kubernetes/, the most useful day-to-day commands are:

bundle exec rake spec:unit
bundle exec rake spec:integration
bundle exec rake spec:smoke
bundle exec rake "spec:changed[origin/master]"
bundle exec rake spec:e2e
bundle exec rake "e2e:changed[origin/master]"

Use spec:smoke for a fast sanity pass, spec:changed for focused local iteration, and spec before merging wider library changes.

License

This program follows the Apache License version 2.0 (http://www.apache.org/licenses/ ). See LICENSE file included with the distribution for details.