k8s-client 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e41fdd25707bd063607b40f12a7f5ce09030fea59d54c35934c9cae0392df1e5
-  data.tar.gz: 6fe3f509d0a9f0e47a1c42498e1aa329d18205c5d5b09d6dde15716a3e3d72f4
+  metadata.gz: 780d34c7890954d2e54e0b158f94a8d90e9b5bdaaab11e65cf2db86e695f640a
+  data.tar.gz: 40f4843ff19e0b403f906e2f17f9ff7859c5f47413f0354e7ae1758fc5d24377
 SHA512:
-  metadata.gz: dc80198faad81e54d58e2f5c70db0baf05c5096a236b937b2d10883d91dbe3447674f64e64cf7ef7f92bb0dd14de1cf2be1407cd8c62a2cbfdd9598968a68eef
-  data.tar.gz: a4da4e0d39328b33d44c672851f4dbcf7fb970a1907c1fa7150b75a035f6a2ff40b651c3cff8365d4dc495d2ad5c2c49e52d6b7240c6b0820ca5a6e002a582ed
+  metadata.gz: 8a5014cf50bd530964fd31c686587288c76bd86aff746bdd5c09b73ec265a82baf4e46d10d297150d48e8984f7d7bc3f0eee25c33511611b7d71e73397675cc0
+  data.tar.gz: fda08120279153fd294f8b7a820acdd052f61d6a96d589733800e90ef3673863e3fe5ef600ae5b46f421c4a32b2994681840da356424c0da5aea650faf96dedf

data/README.md

@@ -1,8 +1,18 @@
 # K8s::Client
 
 [![Build Status](https://travis-ci.com/kontena/k8s-client.svg?branch=master)](https://travis-ci.com/kontena/k8s-client)
+[![Gem Version](https://badge.fury.io/rb/k8s-client.svg)](https://badge.fury.io/rb/k8s-client)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/kontena/k8s-client/master)
 
-Ruby client library for the Kubernetes (1.10) API
+
+Ruby client library for the Kubernetes (1.11) API
+
+## Highlights
+
+* Clean API for dynamic Kubernetes API Groups / Resources
+* Fast API requests using HTTP connection keepalive
+* Fast API discovery and resource listings using pipelined HTTP requests
+* Typed errors with useful debugging information
 
 ## Installation
 
@@ -20,9 +30,156 @@ Or install it yourself as:
 
     $ gem install k8s-client
 
+And then load the code using:
+
+```ruby
+require 'k8s-client'
+```
+
 ## Usage
 
-WIP: See [`bin/k8s-client`](bin/k8s-client) for example code.
+### Overview
+The top-level `K8s::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 are `RecursiveOpenStruct` instances providing 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 `K8s::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 `K8s::Error::API` subclasses represent different HTTP response codes, such as `K8s::Error::NotFound` or `K8s::Error::Conflict`.
+
+See [`bin/k8s-client`](bin/k8s-client) for example code.
+
+### Creating a client
+
+#### Unauthenticated client
+
+```ruby
+client = K8s.client('https://localhost:6443', ssl_verify_peer: false)
+```
+
+The keyword options are [Excon](https://github.com/excon/excon/) options.
+
+#### Client from kubeconfig
+
+```ruby
+client = K8s::Client.config(K8s::Config.load_file('~/.kube/config'))
+```
+
+#### In-cluster client from pod envs/secrets
+
+```ruby
+client = K8s::Client.in_cluster_config
+```
+
+### Logging
+
+#### Quiet
+
+To supress any warning messages:
+
+```ruby
+K8s::Logging.quiet!
+K8s::Transport.quiet!
+```
+
+The `K8s::Transport` is quiet by default, but other components may log warnings in the future.
+
+#### Debugging
+
+Log all API requests
+
+```ruby
+K8s::Logging.debug!
+K8s::Transport.verbose!
+```
+
+```
+I, [2018-08-09T14:19:50.404739 #1]  INFO -- K8s::Transport: Using config with server=https://167.99.39.233:6443
+I, [2018-08-09T14:19:50.629521 #1]  INFO -- K8s::Transport<https://167.99.39.233:6443>: GET /version => HTTP 200: <K8s::API::Version> in 0.224s
+I, [2018-08-09T14:19:50.681367 #1]  INFO -- K8s::Transport<https://167.99.39.233:6443>: GET /api/v1 => HTTP 200: <K8s::API::MetaV1::APIResourceList> in 0.046s
+I, [2018-08-09T14:19:51.018740 #1]  INFO -- K8s::Transport<https://167.99.39.233:6443>: GET /api/v1/pods => HTTP 200: <K8s::API::MetaV1::List> in 0.316s
+```
+
+Using `K8s::Transport.debug!` will also log request/response bodies. The `EXCON_DEBUG=true` env will log all request/response attributes, including headers.
+
+### 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:
+
+```ruby
+client.apis(prefetch_resources: true)
+```
+
+This will fetch the API resource lists for all API groups in a single pipelined request.
+
+### Listing resources
+
+```ruby
+client.api('v1').resource('pods', namespace: 'default').list(labelSelector: {'role' => 'test'}).each do |pod|
+  puts "namespace=#{pod.metadata.namespace} pod: #{pod.metadata.name} node=#{pod.spec.nodeName}"
+end
+```
+
+### Updating resources
+
+```ruby
+node = client.api('v1').resource('nodes').get('test-node')
+
+node[:spec][:unschedulable] = true
+
+client.api('v1').resource('nodes').update_resource(node)
+```
+
+### Deleting resources
+
+```ruby
+pod = client.api('v1').resource('pods', namespace: 'default').delete('test-pod')
+```
+
+```ruby
+pods = client.api('v1').resource('pods', namespace: 'default').delete_collection(labelSelector: {'role' => 'test'})
+```
+
+### Creating resources
+
+#### Programmatically defined resources
+```ruby
+service = K8s::Resource.new(
+  apiVersion: 'v1',
+  kind: 'Service',
+  metadata: {
+    namespace: 'default',
+    name: 'test',
+  },
+  spec: {
+    type: 'ClusterIP',
+    ports: [
+      { port: 80 },
+    ],
+    selector: {'app' => 'test'},
+  },
+)
+
+logger.info "Create service=#{service.metadata.name} in namespace=#{service.metadata.namespace}"
+
+service = client.api('v1').resource('services').create_resource(service)
+```
+
+#### From file(s)
+
+```ruby
+resources = K8s::Resource.from_files('./test.yaml')
+
+for resource in resources
+  resource = client.create_resource(resource)
+end
+```
+
+### Patching resources
+
+```ruby
+client.api('apps/v1').resource('deployments', namespace: 'default').merge_patch('test', {
+    spec: { replicas: 3 },
+})
+```
 
 ## Contributing
 

data/lib/k8s/client/version.rb

@@ -1,5 +1,5 @@
 module K8s
   class Client
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/k8s/error.rb

@@ -42,6 +42,7 @@ module K8s
     define_status_error 422, :Invalid
     define_status_error 429, :Timeout
     define_status_error 500, :InternalError
+    define_status_error 503, :ServiceUnavailable
     define_status_error 504, :ServerTimeout
   end
 end

data/lib/k8s/transport.rb

@@ -167,6 +167,8 @@ module K8s
           status = K8s::API::MetaV1::Status.new(response_data)
 
           raise error_class.new(method, path, response.status, response.reason_phrase, status)
+        elsif response_data
+          raise error_class.new(method, path, response.status, "#{response.reason_phrase}: #{response_data}")
         else
           raise error_class.new(method, path, response.status, response.reason_phrase)
         end
@@ -196,9 +198,10 @@ module K8s
     end
 
     # @param options [Array<Hash>]
-    # @param skip_missing [Boolean] return nil for 404
+    # @param skip_missing [Boolean] return nil for HTTP 404 responses
+    # @param retry_errors [Boolean] retry with non-pipelined request for HTTP 503 responses
     # @return [Array<response_class, Hash, nil>]
-    def requests(*options, response_class: nil, skip_missing: false)
+    def requests(*options, response_class: nil, skip_missing: false, retry_errors: true)
       return [] if options.empty? # excon chokes
 
       start = Time.now
@@ -218,6 +221,15 @@ module K8s
           else
             raise
           end
+        rescue K8s::Error::ServiceUnavailable => exc
+          if retry_errors
+            logger.warn { "Retry #{format_request(request_options)} => HTTP #{exc.code} #{exc.reason} in #{'%.3f' % t}s" }
+
+            # only retry the failed request, not the entire pipeline
+            request(response_class: response_class, **request_options)
+          else
+            raise
+          end
         end
       }
     rescue K8s::Error => exc

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: k8s-client
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kontena, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-08 00:00:00.000000000 Z
+date: 2018-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon