k8s-client 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f007ab73089515a1766b43c947c33c8c3e8dfd902b19ce47aa6e5b3a87892536
-  data.tar.gz: 4d3b616e388ae5334966588ea93828f3efb6dac602d4a0f25906063d4360fc82
+  metadata.gz: 629b1fd35aba3aa4999fb320033c537e239768a3ea2a9163b19a2ba69f00466d
+  data.tar.gz: 35c3043b726d29a0fb038433b4764fdd8de9b2665b1db8c6a7649c6403f9e98d
 SHA512:
-  metadata.gz: e13b44376050184651c88518d752062657bb2c1ac820af787090d603411c0ae6a86ae0e9b069dc79ed1a9de3ab07dfbc5e93ae5e6c847b65c16aa1dacf30ae45
-  data.tar.gz: 6344b7a1809baabb31ecd747711171928ae2a0102183732c46029285f773282e82c314e6fb22cbacecaaa281aa331a2eafb3807cb2951ff0ff628a4c024778f2
+  metadata.gz: cac2f739ee3dcfe3885fe4070c4497e22cc86d227a449c18c773390299e5e416458971a2d424abbcae52b163f4077fc8d85138865c1f1857ca3a83f27dae9e84
+  data.tar.gz: a2bd611f565e0f6e3e9f54d201f89bc2a5eef307b9d3ce7327c267139fd29744a7f721d655f6b67b9aa4126db0c97830b1e2a8330f5abde8009f3ac954c6e7f4

data/README.md

@@ -63,6 +63,21 @@ The keyword options are [Excon](https://github.com/excon/excon/) options.
 client = K8s::Client.config(K8s::Config.load_file('~/.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
 
 ```ruby

data/lib/k8s-client.rb

@@ -1,14 +1,17 @@
-require 'k8s/api/metav1'
-require 'k8s/api/version'
+# Kubernetes client library
+module K8s
+  require 'k8s/api/metav1'
+  require 'k8s/api/version'
 
-require 'k8s/config'
-require 'k8s/logging'
+  require 'k8s/config'
+  require 'k8s/logging'
 
-require 'k8s/api_client'
-require "k8s/client"
-require "k8s/error"
-require 'k8s/resource'
-require 'k8s/resource_client'
-require 'k8s/stack'
-require 'k8s/transport'
-require 'k8s/util'
+  require 'k8s/api_client'
+  require "k8s/client"
+  require "k8s/error"
+  require 'k8s/resource'
+  require 'k8s/resource_client'
+  require 'k8s/stack'
+  require 'k8s/transport'
+  require 'k8s/util'
+end

data/lib/k8s/api.rb

@@ -2,11 +2,14 @@ require 'dry-types'
 require 'dry-struct'
 
 module K8s
+  # Kube API definitions
   module API
+    # Common Dry::Types used in the API
     module Types
       include Dry::Types.module
     end
 
+    # Common API struct type, handling JSON transforms with symbol keys
     class Struct < Dry::Struct
       # input from JSON with string keys
       transform_keys(&:to_sym)

data/lib/k8s/api/metav1.rb

@@ -2,6 +2,9 @@ require 'k8s/api'
 
 module K8s
   module API
+    # API types common to all apigroups/versions
+    #
+    # @see https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1
     module MetaV1
       # @see https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#TypeMeta
       class Resource < Struct

data/lib/k8s/api/metav1/api_group.rb

@@ -1,6 +1,8 @@
 module K8s
   module API
     module MetaV1
+      # structured list of available APIGroup versions
+      # groupVersion provided for convenience
       class APIGroupVersion < Struct
         attribute :groupVersion, Types::Strict::String
         attribute :version, Types::Strict::String

data/lib/k8s/api/metav1/status.rb

@@ -3,13 +3,14 @@ module K8s
     module MetaV1
       # @see https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Status
       class Status < Resource
-
+        # structured cause
         class Cause < Struct
           attribute :reason, Types::Strict::String.optional.default(nil)
           attribute :message, Types::Strict::String.optional.default(nil) # human-readable
           attribute :field, Types::Strict::String.optional.default(nil) # human-readable
         end
 
+        # structured details
         class Details < Struct
           attribute :name, Types::Strict::String.optional.default(nil)
           attribute :group, Types::Strict::String.optional.default(nil)

data/lib/k8s/api/version.rb

@@ -1,5 +1,6 @@
 module K8s
   module API
+    # GET /version
     class Version < Struct
       attribute :buildDate, Types::Strict::String # TODO: parse datetime?
       attribute :compiler, Types::Strict::String

data/lib/k8s/api_client.rb

@@ -1,5 +1,10 @@
 module K8s
+  # Per-APIGroup/version client.
+  #
+  # Offers access to {ResourceClient} instances for the APIResource types defined in this apigroup/version
   class APIClient
+    # @param api_version [String] either core version (v1) or apigroup/apiversion (apps/v1)
+    # @return [String]
     def self.path(api_version)
       if api_version.include? '/'
         File.join('/apis', api_version)
@@ -21,6 +26,8 @@ module K8s
       @api_version
     end
 
+    # @param path [Array<String>] join path from parts
+    # @return [String]
     def path(*path)
       @transport.path(self.class.path(@api_version), *path)
     end
@@ -99,7 +106,7 @@ module K8s
     # Returns flattened array with mixed resource kinds.
     #
     # @param resources [Array<K8s::ResourceClient>] default is all listable resources for api
-    # @param **options @see [K8s::ResourceClient#list]
+    # @param options @see [K8s::ResourceClient#list]
     # @return [Array<K8s::Resource>]
     def list_resources(resources = nil, **options)
       resources ||= self.resources.select{|resource| resource.list? }

data/lib/k8s/client.rb

@@ -2,13 +2,20 @@ require 'openssl'
 require 'base64'
 
 module K8s
+  # @param server [String] http/s URL
+  # @param options [Hash] @see Transport.new
   # @return [K8s::Client]
   def self.client(server, **options)
     Client.new(Transport.new(server, **options))
   end
 
+  # Top-level client wrapper.
+  # Uses a {Transport} instance to talk to the kube API.
+  # Offers access to {APIClient} and {ResourceClient} instances.
   class Client
     # @param config [Phraos::Kube::Config]
+    # @param namespace [String] @see #initialize
+    # @param options [Hash] @see Transport.config
     # @return [K8s::Client]
     def self.config(config, namespace: nil, **options)
       new(Transport.config(config, **options),
@@ -22,6 +29,7 @@ module K8s
     end
 
     # @param transport [K8s::Transport]
+    # @param namespace [String] default namespace for all operations
     def initialize(transport, namespace: nil)
       @transport = transport
       @namespace = namespace
@@ -93,7 +101,7 @@ module K8s
     # Returns flattened array with mixed resource kinds.
     #
     # @param resources [Array<K8s::ResourceClient>] default is all listable resources for api
-    # @param **options @see [K8s::ResourceClient#list]
+    # @param options @see K8s::ResourceClient#list
     # @return [Array<K8s::Resource>]
     def list_resources(resources = nil, **options)
       resources ||= self.resources.select{|resource| resource.list? }

data/lib/k8s/client/version.rb

@@ -1,5 +1,6 @@
 module K8s
   class Client
-    VERSION = "0.3.3"
+    # Updated on releases using semver.
+    VERSION = "0.3.4"
   end
 end

data/lib/k8s/config.rb

@@ -3,9 +3,11 @@ require 'dry-types'
 require 'yaml'
 
 module K8s
+  # Common struct type for kubeconfigs:
+  #
+  # * converts string keys to symbols
+  # * normalizes foo-bar to foo_bar
   class ConfigStruct < Dry::Struct
-    # convert string keys to symbols
-    # normalize foo-bar to foo_bar
     transform_keys do |key|
       case key
       when String
@@ -18,10 +20,13 @@ module K8s
 
   # @see https://godoc.org/k8s.io/client-go/tools/clientcmd/api/v1#Config
   class Config < ConfigStruct
+
+    # Common dry-types for config
     class Types
       include Dry::Types.module
     end
 
+    # structured cluster
     class Cluster < ConfigStruct
       attribute :server, Types::String
       attribute :insecure_skip_tls_verify, Types::Bool.optional.default(nil)
@@ -29,11 +34,14 @@ module K8s
       attribute :certificate_authority_data, Types::String.optional.default(nil)
       attribute :extensions, Types::Strict::Array.optional.default(nil)
     end
+
+    # structured cluster with name
     class NamedCluster < ConfigStruct
       attribute :name, Types::String
       attribute :cluster, Cluster
     end
 
+    # structured user
     class User < ConfigStruct
       attribute :client_certificate, Types::String.optional.default(nil)
       attribute :client_certificate_data, Types::String.optional.default(nil)
@@ -50,17 +58,24 @@ module K8s
       attribute :exec, Types::Strict::Hash.optional.default(nil)
       attribute :extensions, Types::Strict::Array.optional.default(nil)
     end
+
+    # structured user with name
     class NamedUser < ConfigStruct
       attribute :name, Types::String
       attribute :user, User
     end
 
+    # structured context
+    #
+    # Referrs to other named User/cluster objects within the same config.
     class Context < ConfigStruct
       attribute :cluster, Types::Strict::String
       attribute :user, Types::Strict::String
       attribute :namespace, Types::Strict::String.optional.default(nil)
       attribute :extensions, Types::Strict::Array.optional.default(nil)
     end
+
+    # named context
     class NamedContext < ConfigStruct
       attribute :name, Types::String
       attribute :context, Context
@@ -68,7 +83,7 @@ module K8s
 
     attribute :kind, Types::Strict::String.optional.default(nil)
     attribute :apiVersion, Types::Strict::String.optional.default(nil)
-    attribute :preferences, Types::Strict::Hash.optional
+    attribute :preferences, Types::Strict::Hash.optional.default(nil)
     attribute :clusters, Types::Strict::Array.of(NamedCluster)
     attribute :users, Types::Strict::Array.of(NamedUser)
     attribute :contexts, Types::Strict::Array.of(NamedContext)

data/lib/k8s/error.rb

@@ -1,7 +1,10 @@
 require 'forwardable'
 
 module K8s
+  # Top-level class for all errors raised by this gem.
   class Error < StandardError
+
+    # Kube API error, related to a HTTP response with a non-2xx code
     class API < Error
       extend Forwardable
 
@@ -27,8 +30,14 @@ module K8s
       end
     end
 
+    # specific API error subtypes for HTTP status codes
+    # Hash{Integer => Class<API>}
     HTTP_STATUS_ERRORS = {}
 
+    # define a new API error type on the module for the given HTTP status code
+    #
+    # @param code [Integer] HTTP status code
+    # @param name [Symbol] API error class name
     def self.define_status_error(code, name)
       HTTP_STATUS_ERRORS[code] = self.const_set(name, Class.new(API))
     end
@@ -45,6 +54,8 @@ module K8s
     define_status_error 503, :ServiceUnavailable
     define_status_error 504, :ServerTimeout
 
+    # Attempt to create a ResourceClient for an unknown resource type.
+    # The client cannot construct the correct API URL without having the APIResource definition.
     class UndefinedResource < Error
 
     end

data/lib/k8s/logging.rb

@@ -1,24 +1,44 @@
 require 'logger'
 
 module K8s
+  # Logging utilities
+  #
+  # This provides a per-class Logger that uses the class name as a logging prefix.
+  # Instances can optionally also use logger! to define a per-instance Logger using a custom prefix.
   module Logging
+    # Default log target
     LOG_TARGET = STDERR
+
+    # Default log level: show warnings.
+    #
+    # Use K8s::Logging.quiet! to supress warnings.
+    # Note that the K8s::Transport defaults to quiet!
     LOG_LEVEL = Logger::WARN
 
+    # methods defined on both the global K8s::Logging module, as well as class methods on each class including K8s::Logging
     module ModuleMethods
       # global log_level shared across all including classes
+      # @return Logger::*
       def log_level
         @log_level
       end
+
+      # @param level Logger::*
       def log_level=(level)
         @log_level = level
       end
+
+      # Set log_level to Logger::DEBUG
       def debug!
         self.log_level = Logger::DEBUG
       end
+
+      # Set log_level to Logger::INFO
       def verbose!
         self.log_level = Logger::INFO
       end
+
+      # Set log_level to Logger::ERROR, surpressing any warnings logged by default
       def quiet!
         self.log_level = Logger::ERROR
       end
@@ -26,7 +46,9 @@ module K8s
 
     extend ModuleMethods # global @log_level
 
+    # methods defined on each class including K8s::Logging
     module ClassMethods
+      # @return [Logger]
       def logger(target: LOG_TARGET, level: nil)
         @logger ||= Logger.new(target).tap do |logger|
           logger.progname = self.name
@@ -35,12 +57,17 @@ module K8s
       end
     end
 
+    # extend class/intance methods for per-class logger
     def self.included(base)
       base.extend(ModuleMethods) # per-class @log_level
       base.extend(ClassMethods)
     end
 
-    # Use per-instance logger
+    # Use per-instance logger instead of the default per-class logger
+    #
+    # Sets the instance variable returned by #logger
+    #
+    # @return [Logger]
     def logger!(progname: self.class.name, target: LOG_TARGET, level: nil, debug: false)
       @logger = Logger.new(target).tap do |logger|
         level = Logger::DEBUG if debug

data/lib/k8s/resource.rb

@@ -19,7 +19,7 @@ module K8s
       new(YAML.load_file(filename))
     end
 
-    # @param filename [String] file path
+    # @param path [String] file path
     # @return [Array<K8s::Resource>]
     def self.from_files(path)
       stat = File.stat(path)
@@ -32,7 +32,7 @@ module K8s
       end
     end
 
-    # @param attrs [Hash]
+    # @param hash [Hash]
     def initialize(hash, recurse_over_arrays: true, **options)
       super(hash,
         recurse_over_arrays: recurse_over_arrays,

data/lib/k8s/resource_client.rb

@@ -1,5 +1,10 @@
 module K8s
+  # Per-APIResource type client.
+  #
+  # Used to get/list/update/patch/delete specific types of resources, optionally in some specific namespace.
   class ResourceClient
+
+    # Common helpers used in both class/instance methods
     module Utils
       # @param selector [nil, String, Hash{String => String}]
       # @return [nil, String]

data/lib/k8s/stack.rb

@@ -5,8 +5,14 @@ module K8s
   class Stack
     include Logging
 
+    # Label used to identify resources belonging to this stack
     LABEL = 'k8s.kontena.io/stack'
+
+    # Annotation used to identify resource versions
     CHECKSUM_ANNOTATION = 'k8s.kontena.io/stack-checksum'
+
+    # List of apiVersion:kind combinations to skip for stack prune
+    # These would lead to stack prune misbehaving if not skipped.
     PRUNE_IGNORE = [
       'v1:ComponentStatus', # apiserver ignores GET /v1/componentstatuses?labelSelector=... and returns all resources
       'v1:Endpoints', # inherits stack label from service, but not checksum annotation
@@ -48,6 +54,11 @@ module K8s
       logger! progname: name, debug: debug
     end
 
+    # Random "checksum" used to identify different stack resource versions using an annotation.
+    #
+    # NOTE: This is not actually a checksum.
+    #
+    # @return [String]
     def checksum
       @checksum ||= SecureRandom.hex(16)
     end

data/lib/k8s/transport.rb

@@ -2,23 +2,28 @@ require 'excon'
 require 'json'
 
 module K8s
+  # Excon-based HTTP transport handling request/response body JSON encoding
   class Transport
     include Logging
 
     quiet! # do not log warnings by default
 
+    # Excon middlewares for requests
     EXCON_MIDDLEWARES = [
       # XXX: necessary? redirected requests omit authz headers?
       Excon::Middleware::RedirectFollower,
     ] + Excon.defaults[:middlewares]
 
+    # Default request headers
     REQUEST_HEADERS = {
       'Accept' => 'application/json',
     }
 
     # Construct transport from kubeconfig
     #
-    # @param config [Phraos::Kube::Config]
+    # @param config [K8s::Config]
+    # @param server [String] override cluster.server from config
+    # @param overrides @see #initialize
     # @return [K8s::Transport]
     def self.config(config, server: nil, **overrides)
       options = {}
@@ -58,6 +63,12 @@ module K8s
         options[:client_key_data] = Base64.decode64(key_data)
       end
 
+      if token = config.user.token
+        logger.debug "Using config with .user.token=..."
+
+        options[:auth_token] = token
+      end
+
       logger.info "Using config with server=#{server}"
 
       new(server, **options, **overrides)
@@ -80,6 +91,8 @@ module K8s
     attr_reader :server, :options
 
     # @param server [String] URL with protocol://host:port - any /path is ignored
+    # @param auth_token [String] optional Authorization: Bearer token
+    # @param options [Hash] @see Excon.new
     def initialize(server, auth_token: nil, **options)
       @server = server
       @auth_token = auth_token
@@ -98,11 +111,15 @@ module K8s
       )
     end
 
+    # @param path [Array<String>] join path parts together to build the full URL
     # @return [String]
     def path(*path)
       File.join('/', *path)
     end
 
+    # @param request_object [Object] include request body using to_json
+    # @param content_type [String] request body content-type
+    # @param options [Hash] @see Excon#request
     # @return [Hash]
     def request_options(request_object: nil, content_type: 'application/json', **options)
       options[:headers] ||= {}
@@ -119,6 +136,7 @@ module K8s
       options
     end
 
+    # @param options [Hash] as passed to Excon#request
     def format_request(options)
       method = options[:method]
       path = options[:path]
@@ -134,6 +152,9 @@ module K8s
       [method, path, body].compact.join " "
     end
 
+    # @param response [Hash] as returned by Excon#request
+    # @param request_options [Hash] as passed to Excon#request
+    # @param response_class [Class] decode response body using #from_json
     # @raise [K8s::Error]
     # @raise [Excon::Error] TODO: wrap
     # @return [response_class, Hash]
@@ -177,6 +198,8 @@ module K8s
       end
     end
 
+    # @param response_class [Class] decode response body using #from_json
+    # @param options [Hash] @see Excon#request
     def request(response_class: nil, **options)
       excon_options = request_options(**options)
 
@@ -199,9 +222,10 @@ module K8s
       return obj
     end
 
-    # @param options [Array<Hash>]
+    # @param options [Array<Hash>] @see #request
     # @param skip_missing [Boolean] return nil for HTTP 404 responses
     # @param retry_errors [Boolean] retry with non-pipelined request for HTTP 503 responses
+    # @param common_options [Hash] @see #request, merged with the per-request options
     # @return [Array<response_class, Hash, nil>]
     def requests(*options, skip_missing: false, retry_errors: true, **common_options)
       return [] if options.empty? # excon chokes
@@ -244,7 +268,8 @@ module K8s
       return objects
     end
 
-    # @param *path [String]
+    # @param path [Array<String>] @see #path
+    # @param options [Hash] @see #request
     def get(*path, **options)
       request(
         method: 'GET',
@@ -253,7 +278,8 @@ module K8s
       )
     end
 
-    # @param *paths [String]
+    # @param paths [Array<String>]
+    # @param options [Hash] @see #request
     def gets(*paths, **options)
       requests(*paths.map{|path| {
           method: 'GET',

data/lib/k8s/util.rb

@@ -1,4 +1,5 @@
 module K8s
+  # Miscellaneous helpers
   module Util
     # Yield with all non-nil args, returning matching array with corresponding return values or nils.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: k8s-client
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Kontena, Inc.