开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Kubeclient

A Ruby client for Kubernetes REST api. The client supports GET, POST, PUT, DELETE on all the entities available in kubernetes in both the core and group apis. The client currently supports Kubernetes REST api version v1. To learn more about groups and versions in kubernetes refer to k8s docs

VULNERABILITY in <= v4.9.2❗

If you use Kubeclient::Config, all gem versions <= v4.9.3 can return incorrect ssl_options[:verify_ssl], allowing MITM attacks on your connection and thereby stealing your cluster credentials. See #554 for details and which versions got a fix.

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', 'v1')

For A Group Api:

client = Kubeclient::Client.new('http://localhost:8080/apis/batch', 'v1')

Another option is to initialize the client with URI object:

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

SSL

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', 'v1', ssl_options: ssl_options
)

As an alternative to the ca_file it's possible to use the cert_store:

cert_store = OpenSSL::X509::Store.new
cert_store.add_cert(OpenSSL::X509::Certificate.new(ca_cert_data))
ssl_options = {
  cert_store: cert_store,
  verify_ssl: OpenSSL::SSL::VERIFY_PEER
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api', 'v1', 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', 'v1', ssl_options: ssl_options
)

Authentication

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', 'v1', auth_options: auth_options
)

or

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

or

auth_options = {
  bearer_token_file: '/path/to/token_file'
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api', 'v1', auth_options: auth_options
)

Middleware

The Faraday HTTP client used by kubeclient allows configuration of custom middlewares. For example, you may want to add instrumentation, or add custom retry options. Kubeclient provides a hook for injecting these custom middlewares into the request/response chain, via Client#configure_faraday(&block). This provides an access point to the Faraday::Connection object during initialization. As an example, the following code adds retry options to client requests:

client = Kubeclient::Client.new('http://localhost:8080/api', 'v1')
retry_options = { max: 2, interval: 0.05, interval_randomness: 0.5, backoff_factor: 2 }
client.configure_faraday { |conn| conn.request(:retry, retry_options) }

For more examples and documentation, consult the Faraday docs. Note that certain middlewares (e.g. :raise_error) are always included since Kubeclient is dependent on their behaviour to function correctly.

Inside a Kubernetes cluster

The recommended way to locate the API server within the pod is with the kubernetes.default.svc DNS name, which resolves to a Service IP which in turn will be routed to an API server.

The recommended way to authenticate to the API server is with a service account. kube-system associates a pod with a service account and a bearer token for that service account is placed into the filesystem tree of each container in that pod at /var/run/secrets/kubernetes.io/serviceaccount/token.

If available, a certificate bundle is placed into the filesystem tree of each container at /var/run/secrets/kubernetes.io/serviceaccount/ca.crt, and should be used to verify the serving certificate of the API server.

For example:

auth_options = {
  bearer_token_file: '/var/run/secrets/kubernetes.io/serviceaccount/token'
}
ssl_options = {}
if File.exist?("/var/run/secrets/kubernetes.io/serviceaccount/ca.crt")
  ssl_options[:ca_file] = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"
end
client = Kubeclient::Client.new(
  'https://kubernetes.default.svc',
  'v1',
  auth_options: auth_options,
  ssl_options:  ssl_options
)

Finally, the default namespace to be used for namespaced API operations is placed in a file at /var/run/secrets/kubernetes.io/serviceaccount/namespace in each container. It is recommended that you use this namespace when issuing API commands below.

namespace = File.read('/var/run/secrets/kubernetes.io/serviceaccount/namespace')

You can find information about tokens in this guide and in this reference.

Non-blocking IO

You can also use kubeclient with non-blocking sockets such as Celluloid::IO, see here for details. For example:

require 'celluloid/io'
socket_options = {
  socket_class: Celluloid::IO::TCPSocket,
  ssl_socket_class: Celluloid::IO::SSLSocket
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api', 'v1', socket_options: socket_options
)

This affects only .watch_* sockets, not one-off actions like .get_*, .delete_* etc.

Proxies

You can also use kubeclient with an http proxy server such as tinyproxy. It can be entered as a string or a URI object. For example:

proxy_uri = URI::HTTP.build(host: "myproxyhost", port: 8443)
client = Kubeclient::Client.new(
  'https://localhost:8443/api', 'v1', http_proxy_uri: proxy_uri
)

Redirects

You can optionally not allow redirection with kubeclient. For example:

client = Kubeclient::Client.new(
  'https://localhost:8443/api', 'v1', http_max_redirects: 0
)

Timeouts

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:

timeouts = {
  open: 10,  # unit is seconds
  read: nil  # nil means never time out
}
client = Kubeclient::Client.new(
  'https://localhost:8443/api', 'v1', timeouts: timeouts
)

Default timeouts match Net::HTTP and RestClient:

• open is 60 seconds
• read is 60 seconds.

If you want ruby-independent behavior, always specify :open.

Errors

If an error occurs while performing a request to the API server, Kubeclient::HttpError will be raised.

There are also certain case-specific errors that can be raised (which also inherit from Kubeclient::HttpError):

• Kubeclient::ResourceNotFoundError when attempting to fetch a resource that does not exist or any other situation that results in the API server returning a 404.
• Kubeclient::ResourceAlreadyExistsError when attempting to create a resource that already exists.

Discovery

Discovery from the kube-apiserver is done lazily on method calls so it would not change behavior.

It can also be done explicitly:

client = Kubeclient::Client.new('http://localhost:8080/api', 'v1')
client.discover

It is possible to check the status of discovery

unless client.discovered
  client.discover
end

Kubeclient::Config

If you've been using kubectl and have a .kube/config file (possibly referencing other files in fields such as client-certificate), you can auto-populate a config object using Kubeclient::Config:

# assuming $KUBECONFIG is one file, won't merge multiple like kubectl
config = Kubeclient::Config.read(ENV['KUBECONFIG'] || '/path/to/.kube/config')

This will lookup external files; relative paths will be resolved relative to the file's directory, if config refers to them with relative path. This includes external exec: credential plugins to be executed.

You can also construct Config directly from nested data. For example if you have JSON or YAML config data in a variable:

config = Kubeclient::Config.new(YAML.safe_load(yaml_text), nil)
# or
config = Kubeclient::Config.new(JSON.parse(json_text), nil)

The 2nd argument is a base directory for finding external files, if config refers to them with relative path. Setting it to nil disables file lookups, and exec: execution - such configs will raise an exception. (A config can be self-contained by using inline fields such as client-certificate-data.)

To create a client based on a Config object:

# default context according to `current-context` field:
context = config.context
# or to use a specific context, by name:
context = config.context('default/192-168-99-100:8443/system:admin')

Kubeclient::Client.new(
  context.api_endpoint,
  '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. 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:

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 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 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, kubeclient can use googleauth gem to authorize.

This requires the googleauth gem 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:

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 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 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 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 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 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:

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!

Config.new(data, nil) is better but Kubeclient was never reviewed for behaving safely with malicious / malformed config. It might crash / misbehave in unexpected ways...

namespace

Additionally, the config.context object will contain a namespace attribute, if it was defined in the file. It is recommended that you use this namespace when issuing API commands below. This is the same behavior that is implemented by kubectl command.

You can read it as follows:

puts config.context.namespace

Supported kubernetes versions

We try to support the last 3 minor versions, matching the official support policy for Kubernetes. 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...

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
delete_foos(namespace: 'ns', **opts)     # namespaced

create_foo(Kubeclient::Resource.new({metadata: {name: 'name', namespace: 'namespace', ...}, ...}))
create_foo(Kubeclient::Resource.new({metadata: {name: 'name',