Kubeclient

Gem Version Build Status Code Climate Dependency Status

A Ruby client for Kubernetes REST api. The client supports GET, POST, PUT, DELETE on nodes, pods, secrets, services, replication controllers, namespaces, resource quotas, limit ranges, endpoints, persistent volumes and persistent volume claims. 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 = {
  username: 'username',
  password: 'password'
}
client = Kubeclient::Client.new 'https://localhost:8443/api/' , 'v1beta3',
                                auth_options: auth_options

or

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

or

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_secrets, get_services, get_nodes, get_replication_controllers, get_resource_quotas, get_limit_ranges, get_persistent_volumes, get_persistent_volume_claims

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", 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"

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", delete_secret "secret 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, 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

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, update_secret, update_resource_quota, update_limit_range, update_persistent_volume, update_persistent_volume_claim

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

The below example is for v1beta3

client.update_service service1

Get all entities of all types : all_entities

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

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"

Contributing

  1. Fork it ( https://github.com/[my-github-username]/kubeclient/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Test your changes with rake test rubocop, add new tests if needed.
  4. If you added a new functionality, add it to README
  5. Commit your changes (git commit -am 'Add some feature')
  6. Push to the branch (git push origin my-new-feature)
  7. 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