kube-client
kube-client
Crystal client library for the Kubernetes (1.11+) API
Installation
-
Add the dependency to your
shard.yml
:dependencies: kube-client: github: spoved/kube-client.cr
-
Run
shards install
Usage
require "kube-client/v1.20"
client = Kube::Client.autoconfig
Overview
The top-level Kube::Client
provides access to separate APIClient
instances for each Kubernetes API Group (v1
, apps/v1
, etc.), which in turns provides access to separate ResourceClient
instances for each API resource type (nodes
, pods
, deployments
, etc.).
Individual resources are returned as K8S::Resource
instances, which provide attribute access (resource.metadata.name
). The resource instances are returned by methods such as client.api("v1").resource("nodes").get("foo")
, and passed as arguments for client.api("v1").resource("nodes").create_resource(res)
. Resources can also be loaded from disk using Kube::Resource.from_files(path)
, and passed to the top-level methods such as client.create_resource(res)
, which lookup the correct API/Resource client from the resource apiVersion
and kind
.
The different Kube::Error::API
subclasses represent different HTTP response codes, such as Kube::Error::NotFound
or Kube::Error::Conflict
.
Creating a client
Unauthenticated client
client = Kube.client("https://localhost:6443", ssl_verify_peer: false)
The keyword options are Kube::Transport::Options options.
Client from kubeconfig
client = Kube::Client.config(
Kube::Config.load_file(
File.expand_path "~/.kube/config"
)
)
Supported kubeconfig options
Not all kubeconfig options are supported, only the following kubeconfig options work:
current-context
context.cluster
context.user
cluster.server
cluster.insecure_skip_tls_verify
cluster.certificate_authority
cluster.certificate_authority_data
user.client_certificate
+user.client_key
user.client_certificate_data
+user.client_key_data
user.token
With overrides
client = Kube::Client.config(Kube::Config.load_file("~/.kube/config"),
server: "http://localhost:8001",
)
In-cluster client from pod envs/secrets
client = Kube::Client.in_cluster_config
Prefetching API resources
Operations like mapping a resource kind
to an API resource URL require knowledge of the API resource lists for the API group. Mapping resources for multiple API groups would require fetching the API resource lists for each API group in turn, leading to additional request latency. This can be optimized using resource prefetching:
client.apis(prefetch_resources: true)
This will fetch the API resource lists for all API groups in a single pipelined request.
Listing resources
client.api("v1").resource("pods", namespace: "default").list(label_selector: {"role" => "test"}).each do |pod|
pod = pod.as(K8S::Api::Core::V1::Pod)
puts "namespace=#{pod.metadata!.namespace} pod: #{pod.metadata!.name} node=#{pod.spec.try &.node_name}"
end
Updating resources
node = client.api("v1").resource("nodes").get("test-node")
node.as(K8S::Api::Core::V1::Node).spec.not_nil!.unschedulable = true
client.api("v1").resource("nodes").update_resource(node)
Deleting resources
pod = client.api("v1").resource("pods", namespace: "default").delete("test-pod")
pods = client.api("v1").resource("pods", namespace: "default").delete_collection(label_selector: {"role" => "test"})
Creating resources
Programmatically defined resources
pod = K8S::Api::Core::V1::Pod.new(
metadata: ::K8S::ObjectMeta.new(
name: name.nil? ? random_string(10) : name,
namespace: "default",
labels: {
"app" => "kube-client-test",
},
),
spec: K8S::Api::Core::V1::PodSpec.new(
containers: [
K8S::Api::Core::V1::Container.new(
name: "test",
image: "test",
),
],
)
)
logger.info "Create pod=#{pod.metadata!.name} in namespace=#{pod.metadata!.namespace}"
pod = client.api("v1").resource("pods").create_resource(pod)
From file(s)
Currently, only single resource files are supported.
resource = K8S::Resource.from_file("./test.yaml")
resource = client.create_resource(resource)
Patching resources
client.api("apps/v1").resource("deployments", namespace: "default").merge_patch("test", {
spec: { replicas: 3 },
})
Watching resources
Watching resources is currently not supported.
Contributing
- Fork it (https://github.com/spoved/kube-client.cr/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am "Add some feature"
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- Holden Omans - creator and maintainer
- k8s-client - Ruby client this was heavily sourced from