Kubeclient

A Ruby client for Kubernetes REST api. The client supports GET, POST, PUT, DELETE on nodes, pods, services, replication controllers, namespaces and endpoints. The client currently supports Kubernetes REST api version v1beta3.

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/' , "v1beta3"

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

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

Another option is to initialize the client with URI object:

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

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/' , "v1beta3",
                                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/' , 'v1beta3',
                                ssl_options: ssl_options

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

auth_options = {
  user: 'username',
  password: 'password'
}
client = Kubeclient::Client.new 'https://localhost:8443/api/' , 'v1beta3',
                                auth_options: auth_options

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

auth_options = {
  bearer_token_file: '/path/to/token_file'
}
client = Kubeclient::Client.new 'https://localhost:8443/api/' , 'v1beta3',
                                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/' , 'v1beta3',
                                auth_options: auth_options

Examples:

Get all instances of a specific entity type

Such as: get_pods, get_services, get_nodes, get_replication_controllers

pods = client.get_pods

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"

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.

Delete an entity (by name)

For example: delete_pod "pod name" , delete_replication_controller "rc name", delete node "node name"

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

client.delete_service "redis-service"

Create an entity

For example: create_pod pod_object, create_replication_controller rc_obj

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

The below example is for v1beta3

service = Service.new
service.metadata.name = "redis-master"
service.spec.port = 6379
service.spec.containerPort  = "redis-server"
service.spec.selector = {}
service.spec.selector.name = "redis"
service.spec.selector.role = "master"
client.create_service service`

Update an entity

For example: update_pod, update_service, update_replication_controller

Input parameter - object of type Service, Pod, ReplicationController

The below example is for v1beta3

client.update_service service1

Get all entities of all types : all_entities

Returns a hash with 7 keys (node, service, pod, replication_controller, namespace, endpoint and event). 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

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. Please run all tests before submitting a Pull Request, and add new tests for new functionality.

Running tests:

rake test

geku / kubeclient