Client Interface

Client

class lightkube.Client(config=None, namespace=None, timeout=None, lazy=True, field_manager=None, trust_env=True)

Creates a new lightkube client

parameters

• config - Instance of SingleConfig or KubeConfig. When not set the configuration will be detected automatically using the following order: in-cluster config, KUBECONFIG environment variable, ~/.kube/config file.
• namespace - Default namespace to use. This attribute is used in case namespaced resources are called without defining a namespace. If not specified, the default namespace set in your kube configuration will be used.
• timeout - Instance of httpx.Timeout. By default all timeouts are set to 10 seconds. Notice that read timeout is ignored when watching changes.
• lazy - When set, the returned objects will be decoded from the JSON payload in a lazy way, i.e. only when accessed.
• field_manager - Name associated with the actor or entity that is making these changes.
• trust_env - Ignore environment variables, also passed through to httpx.Client trust_env. See its docs for further description. If False, empty config will be derived from_file(DEFAULT_KUBECONFIG)

apply(self, obj, name=None, *, namespace=None, field_manager=None, force=False)

Create or configure an object. This method uses the server-side apply functionality.

parameters

• obj - object to create. This need to be an instance of a resource kind.
• name - (optional) Required only for sub-resources: Name of the resource to which this object belongs.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• field_manager - Name associated with the actor or entity that is making these changes.
• force - (optional) Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people.

config

Return the kubernetes configuration used in this client

create(self, obj, name=None, *, namespace=None, field_manager=None)

Creates a new object

parameters

• obj - object to create. This need to be an instance of a resource kind.
• name - (optional) Required only for sub-resources: Name of the resource to which this object belongs.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• field_manager - (optional) Name associated with the actor or entity that is making these changes. This parameter overrides the corresponding Client initialization parameter.

delete(self, res, name, *, namespace=None, grace_period=None, cascade=None)

Delete an object

parameters

• res - Resource kind.
• name - Name of the object to delete.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• grace_period - (optional) The duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is None (default), the default grace period for the specified type will be used. Defaults to a per object value if not specified. Zero means delete immediately.
• cascade - (optional)* Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are:
  • 'CascadeType.ORPHAN' - orphan the dependents;
  • 'CascadeType.BACKGROUND' - allow the garbage collector to delete the dependents in the background;
  • 'CascadeType.FOREGROUND' - a cascading policy that deletes all dependents in the foreground.

deletecollection(self, res, *, namespace=None, grace_period=None, cascade=None)

Delete all objects of the given kind

• res - Resource kind.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• grace_period - (optional) The duration in seconds before the objects should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is None (default), the default grace period for the specified type will be used. Defaults to a per object value if not specified. Zero means delete immediately.
• cascade - (optional)* Whether and how garbage collection will be performed. Either this field or OrphanDependents may be set, but not both. The default policy is decided by the existing finalizer set in the metadata.finalizers and the resource-specific default policy. Acceptable values are:
  • 'CascadeType.ORPHAN' - orphan the dependents;
  • 'CascadeType.BACKGROUND' - allow the garbage collector to delete the dependents in the background;
  • 'CascadeType.FOREGROUND' - a cascading policy that deletes all dependents in the foreground.

get(self, res, name, *, namespace=None)

Return an object

parameters

• res - Resource kind.
• name - Name of the object to fetch.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).

list(self, res, *, namespace=None, chunk_size=None, labels=None, fields=None)

Return an iterator of objects matching the selection criteria.

parameters

• res - resource kind.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• chunk_size - (optional) Limit the amount of objects returned for each rest API call. This method will automatically execute all subsequent calls until no more data is available.
• labels - (optional) Limit the returned objects by labels. More details.
• fields - (optional) Limit the returned objects by fields. More details.

log(self, name, *, namespace=None, container=None, follow=False, since=None, tail_lines=None, timestamps=False, newlines=True)

Return log lines for the given Pod

parameters

• name - Name of the Pod.
• namespace - (optional) Name of the namespace containing the Pod.
• container - (optional) The container for which to stream logs. Defaults to only container if there is one container in the pod.
• follow - (optional) If True, follow the log stream of the pod.
• since - (optional) If set, a relative time in seconds before the current time from which to fetch logs.
• tail_lines - (optional) If set, the number of lines from the end of the logs to fetch.
• timestamps - (optional) If True, add an RFC3339 or RFC3339Nano timestamp at the beginning of every line of log output.
• newlines - (optional) If True, each line will end with a newline, otherwise the newlines will be stripped.

namespace

Return the default namespace that will be used when a namespace has not been specified

patch(self, res, name, obj, *, namespace=None, patch_type=, field_manager=None, force=False)

Patch an object.

parameters

• res - Resource kind.
• name - Name of the object to patch.
• obj - patch object.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• patch_type - (optional) Type of patch to execute. Default PatchType.STRATEGIC.
• field_manager - (optional) Name associated with the actor or entity that is making these changes. This parameter overrides the corresponding Client initialization parameter. NOTE: This parameter is mandatory (here or at Client creation time) for PatchType.APPLY.
• force - (optional) Force is going to "force" Apply requests. It means user will re-acquire conflicting fields owned by other people. This parameter is ignored for non-apply patch types

replace(self, obj, name=None, *, namespace=None, field_manager=None)

Replace an existing resource.

parameters

• obj - new object. This need to be an instance of a resource kind.
• name - (optional) Required only for sub-resources: Name of the resource to which this object belongs.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• field_manager - (optional) Name associated with the actor or entity that is making these changes. This parameter overrides the corresponding Client initialization parameter.

wait(self, res, name, *, for_conditions, namespace=None, raise_for_conditions=())

Waits for specified conditions.

parameters

• res - Resource kind.
• name - Name of resource to wait for.
• for_conditions - Condition types that are considered a success and will end the wait.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• raise_for_conditions - (optional) Condition types that are considered failures and will exit the wait early.

watch(self, res, *, namespace=None, labels=None, fields=None, server_timeout=None, resource_version=None, on_error=)

Watch changes to objects

parameters

• res - resource kind.
• namespace - (optional) Name of the namespace containing the object (Only for namespaced resources).
• labels - (optional) Limit the returned objects by labels. More details.
• fields - (optional) Limit the returned objects by fields. More details.
• server_timeout - (optional) Server side timeout in seconds to close a watch request. This method will automatically create a new request whenever the backend close the connection without errors.
• resource_version - (optional) When set, only modification events following this version will be returned.
• on_error - (optional) Function that control what to do in case of errors. The default implementation will raise any error.

namespace parameter

All API calls for namespaced resources will need to refer to a specific namespace. By default the namespace provided in the kubeconfig file is used. This default can be overridden when instantiating the client class with a different value. You can also specify a specific namespace for a single call using the namespace parameter.

The methods create or replace will use the namespace defined in the object when it's present. Notice that if the object namespace and the method's namespace parameter are set, both must have the same value.

Override rules summary:

• client.method(..., namespace=..)
• [obj.metadata.namespace] (Only when calling create or replace)
• Client(..., namespace=...)
• kubernetes config file

List or watch objects in all namespaces

The methods list and watch can also return objects for all namespaces using namespace='*'.

KubeConfig

class lightkube.KubeConfig(*, clusters, contexts, users=None, current_context=None, fname=None)

Class to represent a kubeconfig. See the specific constructors depending on your use case.

from_dict(conf, fname=None)

Creates a KubeConfig instance from the content of a dictionary structure.

Parameters

• conf: Configuration structure, main attributes are clusters, contexts, users and current-context.
• fname: File path from where this configuration has been loaded. This is needed to resolve relative paths present inside the configuration.

from_env(service_account='/var/run/secrets/kubernetes.io/serviceaccount', default_config='~/.kube/config')

Attempts to load the configuration automatically looking at the environment and filesystem.

The method will attempt to load a configuration using the following order:

• in-cluster config.
• config file defined in KUBECONFIG environment variable.
• configuration file present on the default location.

Parameters

• service_account: Allows to override the default service account directory path. Default /var/run/secrets/kubernetes.io/serviceaccount.
• default_config: Allows to override the default configuration location. Default ~/.kube/config.

from_file(fname)

Creates an instance of the KubeConfig class from a kubeconfig file in YAML format.

Parameters

• fname: Path to the kuberneted configuration.

from_one(*, cluster, user=None, context_name='default', namespace=None, fname=None)

Creates an instance of the KubeConfig class from one cluster and one user configuration

from_server(url, namespace=None)

Creates an instance of the KubeConfig class from the cluster server url

from_service_account(service_account='/var/run/secrets/kubernetes.io/serviceaccount')

Creates a configuration from in-cluster service account information.

Parameters

• service_account: Allows to override the default service account directory path. Default /var/run/secrets/kubernetes.io/serviceaccount.

get(self, context_name=None, default=None)

Returns a SingleConfig instance, representing the configuration matching the given context_name. Lightkube client will automatically call this method without parameters when an instance of KubeConfig is provided.

Parameters

• context_name: Name of the context to use. If context_name is undefined, the current-context is used. In the case both contexts are undefined, and the default is provided, this method will return the default. It will fail with an error otherwise.
• default: Instance of a SingleConfig to be returned in case both contexts are not set. When this parameter is not provided and no context is defined, the method call will fail.