Kubeclient

A Ruby client for Kubernetes REST api. The client supports GET, POST, PUT, DELETE on all the entities available in kubernetes in both the core and group apis. The client currently supports Kubernetes REST api version v1. To learn more about groups and versions in kubernetes refer to k8s docs

Installation

Add this line to your application's Gemfile:

gem 'kubeclient'

And then execute:

bundle

Or install it yourself as:

gem install kubeclient

Usage

Initialize the client:

client = Kubeclient::Client.new('http://localhost:8080/api/', "v1")

Or without specifying version (it will be set by default to "v1")

client = Kubeclient::Client.new('http://localhost:8080/api/')

For A Group Api:

client = Kubeclient::Client.new('http://localhost:8080/apis/batch', 'v1')

Another option is to initialize the client with URI object:

uri = URI::HTTP.build(host: "somehostname", port: 8080)
client = Kubeclient::Client.new(uri)

SSL

It is also possible to use https and configure ssl with:

ssl_options = {
  client_cert: OpenSSL::X509::Certificate.new(File.read('/path/to/client.crt')),
  client_key:  OpenSSL::PKey::RSA.new(File.read('/path/to/client.key')),
  ca_file:     '/path/to/ca.crt',
  verify_ssl:  OpenSSL::SSL::VERIFY_PEER
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', "v1", ssl_options: ssl_options
)

As an alternative to the ca_file it's possible to use the cert_store:

cert_store = OpenSSL::X509::Store.new
cert_store.add_cert(OpenSSL::X509::Certificate.new(ca_cert_data))
ssl_options = {
  cert_store: cert_store,
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', "v1", ssl_options: ssl_options
)

For testing and development purpose you can disable the ssl check with:

ssl_options = { verify_ssl: OpenSSL::SSL::VERIFY_NONE }
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', 'v1', ssl_options: ssl_options
)

Authentication

If you are using basic authentication or bearer tokens as described here then you can specify one of the following:

auth_options = {
  username: 'username',
  password: 'password'
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', 'v1', auth_options: auth_options
)

auth_options = {
  bearer_token: 'MDExMWJkMjItOWY1Ny00OGM5LWJlNDEtMjBiMzgxODkxYzYz'
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', 'v1', auth_options: auth_options
)

auth_options = {
  bearer_token_file: '/path/to/token_file'
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', 'v1', auth_options: auth_options
)

If you are running your app using kubeclient inside a Kubernetes cluster, then you can have a bearer token file mounted inside your pod by using a Service Account. This will mount a bearer token secret a/ /var/run/secrets/kubernetes.io/serviceaccount/token (see here for more details). For example:

auth_options = {
  bearer_token_file: '/var/run/secrets/kubernetes.io/serviceaccount/token'
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', 'v1', auth_options: auth_options
)

You can find information about tokens in this guide and in this reference.

Non-blocking IO

You can also use kubeclient with non-blocking sockets such as Celluloid::IO, see here for details. For example:

require 'celluloid/io'
socket_options = {
  socket_class: Celluloid::IO::TCPSocket,
  ssl_socket_class: Celluloid::IO::SSLSocket
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', 'v1', socket_options: socket_options
)

This affects only .watch_* sockets, not one-off actions like .get_*, .delete_* etc.

Proxies

You can also use kubeclient with an http proxy server such as tinyproxy. It can be entered as a string or a URI object. For example:

proxy_uri = URI::HTTP.build(host: "myproxyhost", port: 8443)
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', http_proxy_uri: proxy_uri
)

Timeouts

Watching never times out.

One-off actions like .get_*, .delete_* have a configurable timeout:

timeouts = {
  open: 10,  # unit is seconds
  read: nil  # nil means never time out
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api/', timeouts: timeouts
)

Default timeouts match Net::HTTP and RestClient, which unfortunately depends on ruby version:

open was infinite up to ruby 2.2, 60 seconds in 2.3+.
read is 60 seconds.

If you want ruby-independent behavior, always specify :open.

Discovery

Discovery from the kube-apiserver is done lazily on method calls so it would not change behavior.

It can also be done explicitly:

client = Kubeclient::Client.new('http://localhost:8080/api', 'v1')
client.discover

It is possible to check the status of discovery

unless client.discovered
  client.discover
end

Kubeclient::Config

If you've been using kubectl and have a .kube/config file, you can auto-populate a config object using Kubeclient::Config:

config = Kubeclient::Config.read('/path/to/.kube/config')

...and then pass that object to Kubeclient::Client:

Kubeclient::Client.new(
  config.context.api_endpoint,
    config.context.api_version,
    {
      ssl_options: config.context.ssl_options,
      auth_options: config.context.auth_options
    }
)

You can also load your JSONified config in from an ENV variable (e.g. KUBE_CONFIG) like so:

Kubeclient::Config.new(JSON.parse(ENV['KUBE_CONFIG']), nil)

###Supported kubernetes versions

For 1.1 only the core api v1 is supported, all api groups are supported in later versions.

Examples:

Get all instances of a specific entity type

Such as: get_pods, get_secrets, get_services, get_nodes, get_replication_controllers, get_resource_quotas, get_limit_ranges, get_persistent_volumes, get_persistent_volume_claims, get_component_statuses, get_service_accounts

pods = client.get_pods

Get all entities of a specific type in a namespace:

services = client.get_services(namespace: 'development')

You can get entities which have specific labels by specifying a parameter named label_selector (named labelSelector in Kubernetes server):

pods = client.get_pods(label_selector: 'name=redis-master')

You can specify multiple labels (that option will return entities which have both labels:

pods = client.get_pods(label_selector: 'name=redis-master,app=redis')

Get a specific instance of an entity (by name)

Such as: get_service "service name" , get_pod "pod name" , get_replication_controller "rc name", get_secret "secret name", get_resource_quota "resource quota name", get_limit_range "limit range name" , get_persistent_volume "persistent volume name" , get_persistent_volume_claim "persistent volume claim name", get_component_status "component name", get_service_account "service account name"

The GET request should include the namespace name, except for nodes and namespaces entities.

node = client.get_node "127.0.0.1"

service = client.get_service "guestbook", 'development'

Note - Kubernetes doesn't work with the uid, but rather with the 'name' property. Querying with uid causes 404.

Getting raw responses

By passing as: :raw, the response from the client is given as a string, which is the raw JSON body from openshift:

pods = client.get_pods as: :raw
node = client.get_node "127.0.0.1", as: :raw

Delete an entity (by name)

For example: delete_pod "pod name" , delete_replication_controller "rc name", delete_node "node name", delete_secret "secret name"

Input parameter - name (string) specifying service name, pod name, replication controller name.

client.delete_service("redis-service")

If you want to cascade delete, for example a deployment, you can use the delete_options parameter.

deployment_name = 'redis-deployment'
namespace = 'default'
delete_options = Kubeclient::Resource.new(
    apiVersion: 'meta/v1',
    gracePeriodSeconds: 0,
    kind: 'DeleteOptions',
    propagationPolicy: 'Foreground' # Orphan, Foreground, or Background
)
client.delete_deployment(deployment_name, namespace, delete_options: delete_options)

Create an entity

For example: create_pod pod_object, create_replication_controller rc_obj, create_secret secret_object, create_resource_quota resource_quota_object, create_limit_range limit_range_object, create_persistent_volume persistent_volume_object, create_persistent_volume_claim persistent_volume_claim_object, create_service_account service_account_object

Input parameter - object of type Service, Pod, ReplicationController.

The below example is for v1

service = Kubeclient::Resource.new
service.metadata = {}
service.metadata.name = "redis-master"
service.metadata.namespace = 'staging'
service.spec = {}
service.spec.ports = [{
  'port' => 6379,
  'targetPort' => 'redis-server'
}]
service.spec.selector = {}
service.spec.selector.name = "redis"
service.spec.selector.role = "master"
service.metadata.labels = {}
service.metadata.labels.app = 'redis'
service.metadata.labels.role = 'slave'
client.create_service(service)

Update an entity

For example: update_pod, update_service, update_replication_controller, update_secret, update_resource_quota, update_limit_range, update_persistent_volume, update_persistent_volume_claim, update_service_account

Input parameter - object of type Pod, Service, ReplicationController etc.

The below example is for v1

client.update_service(service1)

Patch an entity (by name)

For example: patch_pod, patch_service, patch_secret, patch_resource_quota, patch_persistent_volume

Input parameters - name (string) specifying the entity name, patch (hash) to be applied to the resource, optional: namespace name (string)

The PATCH request should include the namespace name, except for nodes and namespaces entities.

The below example is for v1

client.patch_pod("docker-registry", {metadata: {annotations: {key: 'value'}}}, "default")

Get all entities of all types : all_entities

Returns a hash with the following keys (node, secret, service, pod, replication_controller, namespace, resource_quota, limit_range, endpoint, event, persistent_volume, persistent_volume_claim, component_status and service_account). Each key points to an EntityList of same type. This method is a convenience method instead of calling each entity's get method separately.

client.all_entities

Receive entity updates

It is possible to receive live update notices watching the relevant entities:

watcher = client.watch_pods
watcher.each do |notice|
  # process notice data
end

It is possible to interrupt the watcher from another thread with:

watcher.finish

Watch events for a particular object

You can use the field_selector option as part of the watch methods.

watcher = client.watch_events(namespace: 'development', field_selector: 'involvedObject.name=redis-master')
watcher.each do |notice|
  # process notice date
end

Get a proxy URL

You can get a complete URL for connecting a kubernetes entity via the proxy.

client.proxy_url('service', 'srvname', 'srvportname', 'ns')
# => "https://localhost.localdomain:8443/api/v1/proxy/namespaces/ns/services/srvname:srvportname"

Note the third parameter, port, is a port name for services and an integer for pods:

client.proxy_url('pod', 'podname', 5001, 'ns')
# => "https://localhost.localdomain:8443/api/v1/namespaces/ns/pods/podname:5001/proxy"

Get the logs of a pod

You can get the logs of a running pod, specifying the name of the pod and the namespace where the pod is running:

client.get_pod_log('pod-name', 'default')
# => "Running...\nRunning...\nRunning...\n"

If that pod has more than one container, you must specify the container:

client.get_pod_log('pod-name', 'default', container: 'ruby')
# => "..."

If a container in a pod terminates, a new container is started, and you want to retrieve the logs of the dead container, you can pass in the :previous option:

client.get_pod_log('pod-name', 'default', previous: true)
# => "..."

You can also watch the logs of a pod to get a stream of data:

watcher = client.watch_pod_log('pod-name', 'default', container: 'ruby')
watcher.each do |line|
  puts line
end

Process a template

Returns a processed template containing a list of objects to create. Input parameter - template (hash) Besides its metadata, the template should include a list of objects to be processed and a list of parameters to be substituted. Note that for a required parameter that does not provide a generated value, you must supply a value.

Note: This functionality is not supported by K8s at this moment. See the following issue

client.process_template template

Upgrading

past version 2.0

Replace KubeException with Kubeclient::HttpException

past version 1.2.0

Replace Specific Entity class references:

Kubeclient::Service

with the generic

Kubeclient::Resource.new

Where ever possible.

Contributing

Fork it ( https://github.com/[my-github-username]/kubeclient/fork )
Create your feature branch (git checkout -b my-new-feature)
Test your changes with rake test rubocop, add new tests if needed.
If you added a new functionality, add it to README
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Tests

This client is tested with Minitest and also uses VCR recordings in some tests. Please run all tests before submitting a Pull Request, and add new tests for new functionality.

Running tests:

rake test

iamwilhelm/kubeclient

Kubeclient

Installation

Usage

SSL

Authentication

Non-blocking IO

Proxies

Timeouts

Discovery

Kubeclient::Config

Examples:

Get all instances of a specific entity type

Get a specific instance of an entity (by name)

Getting raw responses

Delete an entity (by name)

Create an entity

Update an entity

Patch an entity (by name)

Get all entities of all types : all_entities

Receive entity updates

Watch events for a particular object

Get a proxy URL

Get the logs of a pod

Process a template

Note: This functionality is not supported by K8s at this moment. See the following issue

Upgrading

past version 2.0

past version 1.2.0

Contributing

Tests