kubeclient 4.2.2 → 4.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e11771dcb8f222f6c3a3bb4fb1c8b3db8cc745a9d2dbe8b2ff3edfe02382f3d
-  data.tar.gz: a5edd9efc28428fd2e5d232a1bdce0a1f5d0bd56fad06cff4d10e82e03bdc3f6
+  metadata.gz: 886ba443bde8e7b8a2403dc5cc300fa53f8ffdad30782f2c7c58911049d7d322
+  data.tar.gz: 340073ed06a0252095adb47a73ea972332e2615afdefe9fab5f357db61ceb2f4
 SHA512:
-  metadata.gz: 17cdfd31bf3df9292a2edf052071e99b30e62ee6ebfd05bce7b710623cc7c0ae57acb1c469787cee49bd472dc1661d687908acbb364cc8d36723f7ee4b07d273
-  data.tar.gz: f739a8fc768a688853e2f6e55232087bdfbdc31b26a86ca6ffe6ecc87996b72906a2d60d674c5aae3d5023d578b5cc9d20611a349f1cfc0d2ee1d2511e4f4c7c
+  metadata.gz: 129ca12cda43fdb8e7c2b7400f31b6086cbd06ba4c7874a4c88d07fdcfeb165b88acb620a9673a1a3a7d60f12571cef48e4167f1dd65c8c68d35022db2264320
+  data.tar.gz: 6184774412f3d0fa0d5a16e43520530cf279a8f8d23129f50d9973a91f58cb8bf1db4c55ddccecb710ab7577ab1737a3eba569096b8b257935ee9463e23c34c6

data/.rubocop.yml

@@ -14,12 +14,16 @@ Metrics/ParameterLists:
   CountKeywordArgs: false
 Metrics/CyclomaticComplexity:
   Max: 8
+Metrics/PerceivedComplexity:
+  Max: 8
 Metrics/ModuleLength:
   Enabled: false
 Style/MethodCallWithArgsParentheses:
   Enabled: true
   IgnoredMethods: [require, raise, include, attr_reader, refute, assert]
   Exclude: [Gemfile, Rakefile, kubeclient.gemspec, Gemfile.dev.rb]
+Metrics/BlockLength:
+  Exclude: [kubeclient.gemspec]
 Security/MarshalLoad:
   Exclude: [test/**/*]
 Style/FileName:

data/.travis.yml

@@ -1,13 +1,29 @@
 language: ruby
+sudo: false
+cache: bundler
+script: bundle exec rake $TASK
+
+os:
+  - linux
+  - osx
 rvm:
-  - "2.2"
+  - "2.2.0"
   - "2.3.0"
   - "2.4.0"
   - "2.5.0"
-  - "2.6.0-preview1"
-sudo: false
-cache: bundler
-script: bundle exec rake $TASK
+  - "2.6.0"
+  - "2.7.0"
 env:
  - TASK=test
- - TASK=rubocop
+matrix:
+  exclude:
+    - os: osx
+      rvm: "2.2.0"
+    - os: osx
+      rvm: "2.3.0"
+  # No point running Rubocop on different rubies, results will be same.
+  # The rubies it expects the code to target are controlled in .rubocop.yml.
+  include:
+    - os: linux
+      rvm: "2.5.0"
+      env: TASK=rubocop

data/CHANGELOG.md

@@ -4,6 +4,52 @@ Notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 Kubeclient release versioning follows [SemVer](https://semver.org/).
 
+## 4.7.0 — 2020-06-14
+
+### Fixed
+- Ruby 2.7 compatibility: bumped minimum recursive-open-struct to one that works on 2.7 (#439).
+- Ruby 2.7 warnings (#433, #438).
+- Improved watch documentation, including behavior planned to change in 5.0.0 (#436).
+
+### Added
+- Google Application Default Credentials: Added `userinfo.email` to requested scopes, which is necessary for RBAC policies (#441).
+
+## 4.6.0 — 2019-12-30
+
+### Fixed
+- AmazonEksCredentials was sometimes leaving base64 padding that IAM auth of the EKS cluster rejects.  Now padding is always stripped. (#424, #423)
+
+### Added
+- Allow calling `watch_foos` methods with a block, simpler to use and guarantees closing the connection. (#425)
+
+- Support `limitBytes` query parameter for `get_pod_log`. (#426)
+
+## 4.5.0 — 2019-09-27
+
+### Added
+- Support `:resourceVersion` parameter in `get_foos` methods (similar to existing support in `watch_foos` methods). (#420)
+
+- Relax dependency on `http` gem to allow both 3.x and 4.x. (#413)
+
+## 4.4.0 — 2019-05-03
+
+### Added
+- GCP configs with `user[auth-provider][name] == 'gcp'` will execute credential plugin (normally the `gcloud config config-helper` subcommand) when the config specifies it in `cmd-path`, `cmd-args` fields (similar to `exec` support).  This code path works without `googleauth` gem.  Otherwise, `GoogleApplicationDefaultCredentials` path will be tried as before. (#410)
+- `AmazonEksCredentials` helper for obtaining a token to authenticate against Amazon EKS. This is not currently integrated in `Config`, you will need to invoke it yourself.  You'll need some aws gems that Kubeclient _does not_ include. (#404, #406)
+
+### Changed
+- OpenID Connect tokens which cannot be validaded because we cannot identify the key they were signed with will be considered expired and refreshed as usual. (#407)
+
+## 4.3.0 — 2019-03-03
+
+### Changed
+- `GoogleApplicationDefaultCredentials` will now automatically be used by `Config` if the `user[auth-provider][name] == 'gcp'` in the provided context. Note that `user[exec]` is checked first in anticipation of this functionality being added to GCP sometime in the future. Kubeclient _does not_ include the required `googleauth` gem, so you will need to include it in your calling application. (#394)
+
+### Added
+- OpenID Connect credentials will automatically be used if the `user[auth-provider][name] == 'oidc'` in the provided context. Note that `user[exec]` is checked first. Kubeclient _does not_ include the required `openid_connect` gem, so you will need to include it in your calling application. (#396)
+
+- Support for `json_patch_#{entity}` and `merge_patch_#{entity}`. `patch_#{entity}` will continue to use strategic merge patch. (#390)
+
 ## 4.2.2 — 2019-01-09
 
 ### Added

data/README.md

@@ -166,29 +166,6 @@ namespace = File.read('/var/run/secrets/kubernetes.io/serviceaccount/namespace')
 ```
 You can find information about tokens in [this guide](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/#accessing-the-api-from-a-pod) and in [this reference](http://kubernetes.io/docs/admin/authentication/).
 
-#### Google's Application Default Credentials
-
-On Google Compute Engine, Google App Engine, or Google Cloud Functions, as well as `gcloud`-configured systems
-with [application default credentials](https://developers.google.com/identity/protocols/application-default-credentials),
-you can use the token provider to authorize `kubeclient`.
-
-This requires the [`googleauth` gem](https://github.com/google/google-auth-library-ruby) that is _not_ included in
-`kubeclient` dependencies so you should add it to your bundle.
-
-```ruby
-require 'googleauth'
-
-auth_options = {
-  bearer_token: Kubeclient::GoogleApplicationDefaultCredentials.token
-}
-client = Kubeclient::Client.new(
-  'https://localhost:8443/api/', 'v1', auth_options: auth_options
-)
-```
-
-Note that this token is good for one hour. If your code runs for longer than that, you should plan to
-acquire a new one.
-
 ### Non-blocking IO
 
 You can also use kubeclient with non-blocking sockets such as Celluloid::IO, see [here](https://github.com/httprb/http/wiki/Parallel-requests-with-Celluloid%3A%3AIO)
@@ -230,7 +207,7 @@ client = Kubeclient::Client.new(
 
 ### Timeouts
 
-Watching never times out.
+Watching configures the socket to never time out (however, sooner or later all watches terminate).
 
 One-off actions like `.get_*`, `.delete_*` have a configurable timeout:
 ```ruby
@@ -303,12 +280,121 @@ context = config.context('default/192-168-99-100:8443/system:admin')
 
 Kubeclient::Client.new(
   context.api_endpoint,
-  context.api_version,
+  'v1',
   ssl_options: context.ssl_options,
   auth_options: context.auth_options
 )
 ```
 
+
+#### Amazon EKS Credentials
+
+On Amazon EKS by default the authentication method is IAM.  When running kubectl a temporary token is generated by shelling out to
+the aws-iam-authenticator binary which is sent to authenticate the user.
+See [aws-iam-authenticator](https://github.com/kubernetes-sigs/aws-iam-authenticator).
+To replicate that functionality, the `Kubeclient::AmazonEksCredentials` class can accept a set of IAM credentials and
+contains a helper method to generate the authentication token for you.
+
+This requires a set of gems which are _not_ included in
+`kubeclient` dependencies (`aws-sigv4`) so you should add them to your bundle.
+You will also require either the `aws-sdk` v2 or `aws-sdk-core` v3 gems to generate the required `Aws:Credentials` object to pass to this method.
+
+To obtain a token:
+
+```ruby
+require 'aws-sdk-core'
+# Use keys
+credentials = Aws::Credentials.new(access_key, secret_key)
+# Or a profile
+credentials = Aws::SharedCredentials.new(profile_name: 'default').credentials
+
+auth_options = {
+  bearer_token: Kubeclient::AmazonEksCredentials.token(credentials, eks_cluster_name)
+}
+client = Kubeclient::Client.new(
+  eks_cluster_https_endpoint, 'v1', auth_options: auth_options
+)
+```
+
+Note that this returns a token good for one minute. If your code requires authorization for longer than that, you should plan to
+acquire a new one, see [How to manually renew](#how-to-manually-renew-expired-credentials) section.
+
+#### Google GCP credential plugin
+
+If kubeconfig file has `user: {auth-provider: {name: gcp, cmd-path: ..., cmd-args: ..., token-key: ...}}`, the command will be executed to obtain a token.
+(Normally this would be a `gcloud config config-helper` command.)
+
+Note that this returns an expiring token. If your code requires authorization for a long time, you should plan to acquire a new one, see [How to manually renew](#how-to-manually-renew-expired-credentials) section.
+
+#### Google's Application Default Credentials
+
+On Google Compute Engine, Google App Engine, or Google Cloud Functions, as well as `gcloud`-configured systems
+with [application default credentials](https://developers.google.com/identity/protocols/application-default-credentials),
+kubeclient can use `googleauth` gem to authorize.
+
+This requires the [`googleauth` gem](https://github.com/google/google-auth-library-ruby) that is _not_ included in
+`kubeclient` dependencies so you should add it to your bundle.
+
+If you use `Config.context(...).auth_options` and the kubeconfig file has `user: {auth-provider: {name: gcp}}`, but does not contain `cmd-path` key, kubeclient will automatically try this (raising LoadError if you don't have `googleauth` in your bundle).
+
+Or you can obtain a token manually:
+
+```ruby
+require 'googleauth'
+
+auth_options = {
+  bearer_token: Kubeclient::GoogleApplicationDefaultCredentials.token
+}
+client = Kubeclient::Client.new(
+  'https://localhost:8443/api/', 'v1', auth_options: auth_options
+)
+```
+
+Note that this returns a token good for one hour. If your code requires authorization for longer than that, you should plan to
+acquire a new one, see [How to manually renew](#how-to-manually-renew-expired-credentials) section.
+
+#### OIDC Auth Provider
+
+If the cluster you are using has OIDC authentication enabled you can use the `openid_connect` gem to obtain
+id-tokens if the one in your kubeconfig has expired.
+
+This requires the [`openid_connect` gem](https://github.com/nov/openid_connect) which is not included in
+the `kubeclient` dependencies so should be added to your own applications bundle.
+
+The OIDC Auth Provider will not perform the initial setup of your `$KUBECONFIG` file. You will need to use something
+like [`dexter`](https://github.com/gini/dexter) in order to configure the auth-provider in your `$KUBECONFIG` file.
+
+If you use `Config.context(...).auth_options` and the `$KUBECONFIG` file has user: `{auth-provider: {name: oidc}}`,
+kubeclient will automatically obtain a token (or use `id-token` if still valid)
+
+Tokens are typically short-lived (e.g. 1 hour) and the expiration time is determined by the OIDC Provider (e.g. Google).
+If your code requires authentication for longer than that you should obtain a new token periodically, see [How to manually renew](#how-to-manually-renew-expired-credentials) section.
+
+Note: id-tokens retrieved via this provider are not written back to the `$KUBECONFIG` file as they would be when
+using `kubectl`.
+
+#### How to manually renew expired credentials
+
+Kubeclient [does not yet](https://github.com/abonas/kubeclient/issues/393) help with this.
+
+The division of labor between `Config` and `Context` objects may change, for now please make no assumptions at which stage `exec:` and `auth-provider:` are handled and whether they're cached.
+The currently guaranteed way to renew is create a new `Config` object.
+
+The more painful part is that you'll then need to create new `Client` object(s) with the credentials from new config.
+So repeat all of this:
+```ruby
+config = Kubeclient::Config.read(ENV['KUBECONFIG'] || '/path/to/.kube/config')
+context = config.context
+ssl_options = context.ssl_options
+auth_options = context.auth_options
+
+client = Kubeclient::Client.new(
+    context.api_endpoint, 'v1',
+    ssl_options: ssl_options, auth_options: auth_options
+)
+# and additional Clients if needed...
+```
+
 #### Security: Don't use config from untrusted sources
 
 `Config.read` is catastrophically unsafe — it will execute arbitrary command lines specified by the config!
@@ -334,16 +420,45 @@ We try to support the last 3 minor versions, matching the [official support poli
 Kubernetes 1.2 and below have known issues and are unsupported.
 Kubernetes 1.3 presumed to still work although nobody is really testing on such old versions...
 
-## Examples:
+## Supported actions & examples:
+
+Summary of main CRUD actions:
+
+```
+get_foos(namespace: 'namespace', **opts)  # namespaced collection
+get_foos(**opts)                          # all namespaces or global collection
+
+get_foo('name', 'namespace', opts)  # namespaced
+get_foo('name', nil, opts)          # global
+
+watch_foos(namespace: ns, **opts)   # namespaced collection
+watch_foos(**opts)                  # all namespaces or global collection
+watch_foos(namespace: ns, name: 'name', **opts)   # namespaced single object
+watch_foos(name: 'name', **opts)                  # global single object
+
+delete_foo('name', 'namespace', opts)    # namespaced
+delete_foo('name', nil, opts)            # global
+
+create_foo(Kubeclient::Resource.new({metadata: {name: 'name', namespace: 'namespace', ...}, ...}))
+create_foo(Kubeclient::Resource.new({metadata: {name: 'name', ...}, ...}))  # global
+
+update_foo(Kubeclient::Resource.new({metadata: {name: 'name', namespace: 'namespace', ...}, ...}))
+update_foo(Kubeclient::Resource.new({metadata: {name: 'name', ...}, ...}))  # global
 
-#### Get all instances of a specific entity type
+patch_foo('name', patch, 'namespace')    # namespaced
+patch_foo('name', patch)                 # global
+```
+
+These grew to be quite inconsistent :confounded:, see https://github.com/abonas/kubeclient/issues/312 and https://github.com/abonas/kubeclient/issues/332 for improvement plans.
+
+### 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`
 
 ```ruby
 pods = client.get_pods
 ```
 
-Get all entities of a specific type in a namespace:<br>
+Get all entities of a specific type in a namespace:
 
 ```ruby
 services = client.get_services(namespace: 'development')
@@ -361,7 +476,22 @@ You can specify multiple labels (that option will return entities which have bot
 pods = client.get_pods(label_selector: 'name=redis-master,app=redis')
 ```
 
-Get all entities of a specific type in chunks:
+There is also [a limited ability to filter by *some* fields](https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/).  Which fields are supported is not documented, you can try and see if you get an error...
+```ruby
+client.get_pods(field_selector: 'spec.nodeName=master-0')
+```
+
+You can ask for entities at a specific version by specifying a parameter named `resource_version`:
+```ruby
+pods = client.get_pods(resource_version: '0')
+```
+but it's not guaranteed you'll get it.  See https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions to understand the semantics.
+
+With default (`as: :ros`) return format, the returned object acts like an array of the individual pods, but also supports a `.resourceVersion` method.
+
+With `:parsed` and `:parsed_symbolized` formats, the returned data structure matches kubernetes list structure: it's a hash containing  `metadata` and `items` keys, the latter containing the individual pods.
+
+#### Get all entities of a specific type in chunks
 
 ```ruby
 continue = nil
@@ -416,7 +546,87 @@ Other formats are:
  - `:parsed` for `JSON.parse`
  - `:parsed_symbolized` for `JSON.parse(..., symbolize_names: true)`
 
-#### Delete an entity (by name)
+### Watch — Receive entities updates
+
+See https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes for an overview.
+
+It is possible to receive live update notices watching the relevant entities:
+
+```ruby
+client.watch_pods do |notice|
+  # process notice data
+end
+```
+
+The notices have `.type` field which may be `'ADDED'`, `'MODIFIED'`, `'DELETED'`, or currently `'ERROR'`, and an `.object` field containing the object.  **UPCOMING CHANGE**: In next major version, we plan to raise exceptions instead of passing on ERROR into the block.
+
+For namespaced entities, the default watches across all namespaces, and you can specify `client.watch_secrets(namespace: 'foo')` to only watch in a single namespace.
+
+You can narrow down using `label_selector:` and `field_selector:` params, like with `get_pods` methods.
+
+You can also watch a single object by specifying `name:` e.g. `client.watch_nodes(name: 'gandalf')` (not namespaced so a name is enough) or `client.watch_pods(namespace: 'foo', name: 'bar')` (namespaced, need both params).
+Note the method name is still plural!  There is no `watch_pod`, only `watch_pods`.  The yielded "type" remains the same — watch notices, it's just they'll always refer to the same object.
+
+You can use `as:` param to control the format of the yielded notices.
+
+#### All watches come to an end!
+
+While nominally the watch block *looks* like an infinite loop, that's unrealistic.  Network connections eventually get severed, and kubernetes apiserver is known to terminate watches.
+
+Unfortunately, this sometimes raises an exception and sometimes the loop just exits.  **UPCOMING CHANGE**: In next major version, non-deliberate termination will always raise an exception; the block will only exit silenty if stopped deliberately.
+
+#### Deliberately stopping a watch
+
+You can use `break` or `return` inside the watch block.
+
+It is possible to interrupt the watcher from another thread with:
+
+```ruby
+watcher = client.watch_pods
+
+watcher.each do |notice|
+  # process notice data
+end
+# <- control will pass here after .finish is called
+
+### In another thread ###
+watcher.finish
+```
+
+#### Starting watch version
+
+You can specify version to start from, commonly used in "List+Watch" pattern:
+```
+list = client.get_pods
+collection_version = list.resourceVersion
+# or with other return formats:
+list = client.get_pods(as: :parsed)
+collection_version = list['metadata']['resourceVersion']
+
+# note spelling resource_version vs resourceVersion.
+client.watch_pods(resource_version: collection_version) do |notice|
+  # process notice data
+end
+```
+It's important to understand [the effects of unset/0/specific resource_version](https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-versions) as it modifies the behavior of the watch — in some modes you'll first see a burst of synthetic 'ADDED' notices for all existing objects.
+
+If you re-try a terminated watch again without specific resourceVersion, you might see previously seen notices again, and might miss some events.
+
+To attempt resuming a watch from same point, you can try using last resourceVersion observed during the watch.  Or do list+watch again.
+
+Whenever you ask for a specific version, you must be prepared for an 410 "Gone" error if the server no longer recognizes it.
+
+#### Watch events about a particular object
+Events are [entities in their own right](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#event-v1-core).
+You can use the `field_selector` option as part of the watch methods.
+
+```ruby
+client.watch_events(namespace: 'development', field_selector: 'involvedObject.name=redis-master') do |notice|
+  # process notice date
+end
+```
+
+### Delete an entity (by name)
 
 For example: `delete_pod "pod name"` , `delete_replication_controller "rc name"`, `delete_node "node name"`, `delete_secret "secret name"`
 
@@ -440,7 +650,7 @@ delete_options = Kubeclient::Resource.new(
 client.delete_deployment(deployment_name, namespace, delete_options: delete_options)
 ```
 
-#### Create an entity
+### 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`.
@@ -466,7 +676,7 @@ service.metadata.labels.role = 'slave'
 client.create_service(service)
 ```
 
-#### Update an entity
+### 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.
@@ -477,7 +687,7 @@ The below example is for v1
 updated = client.update_service(service1)
 ```
 
-#### Patch an entity (by name)
+### 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)
@@ -490,41 +700,19 @@ The below example is for v1
 patched = 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.
-
-```ruby
-client.all_entities
-```
-
-#### Receive entity updates
-It is possible to receive live update notices watching the relevant entities:
+`patch_#{entity}` is called using a [strategic merge patch](https://kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#notes-on-the-strategic-merge-patch). `json_patch_#{entity}` and `merge_patch_#{entity}` are also available that use JSON patch and JSON merge patch, respectively. These strategies are useful for resources that do not support strategic merge patch, such as Custom Resources. Consult the [Kubernetes docs](https://kubernetes.io/docs/tasks/run-application/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment) for more information about the different patch strategies.
 
-```ruby
-watcher = client.watch_pods
-watcher.each do |notice|
-  # process notice data
-end
-```
+### Get all entities of all types : all_entities
 
-It is possible to interrupt the watcher from another thread with:
+Makes requests for all entities of each discovered kind (in this client's API group).  This method is a convenience method instead of calling each entity's get method separately.
 
-```ruby
-watcher.finish
-```
-
-#### Watch events for a particular object
-You can use the `field_selector` option as part of the watch methods.
+Returns a hash with keys being the *singular* entity kind, in lowercase underscore style.  For example for core API group may return keys `"node'`, `"secret"`, `"service"`, `"pod"`, `"replication_controller"`, `"namespace"`, `"resource_quota"`, `"limit_range"`, `"endpoint"`, `"event"`, `"persistent_volume"`, `"persistent_volume_claim"`, `"component_status"`, `"service_account"`. Each key points to an EntityList of same type.
 
 ```ruby
-watcher = client.watch_events(namespace: 'development', field_selector: 'involvedObject.name=redis-master')
-watcher.each do |notice|
-  # process notice date
-end
+client.all_entities
 ```
 
-#### Get a proxy URL
+### Get a proxy URL
 You can get a complete URL for connecting a kubernetes entity via the proxy.
 
 ```ruby
@@ -539,7 +727,7 @@ 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
+### 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:
 
@@ -576,16 +764,21 @@ client.get_pod_log('pod-name', 'default', tail_lines: 10)
 # => "..."
 ```
 
+Kubernetes can fetch a specific number of bytes from the log, but the exact size is not guaranteed and last line may not be terminated:
+```ruby
+client.get_pod_log('pod-name', 'default', limit_bytes: 10)
+# => "..."
+```
+
 You can also watch the logs of a pod to get a stream of data:
 
 ```ruby
-watcher = client.watch_pod_log('pod-name', 'default', container: 'ruby')
-watcher.each do |line|
+client.watch_pod_log('pod-name', 'default', container: 'ruby') do |line|
   puts line
 end
 ```
 
-#### Process a template
+### OpenShift: 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